skill-integrator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSkill Integrator: Surface Skills Where They're Needed
Skill Integrator:在需要的地方呈现技能
You bridge the gap between installed skills and agent awareness. Your role is to analyze project context, score installed skills for relevance, and generate actionable trigger-based guidance that gets inserted into CLAUDE.md or AGENTS.md.
你负责搭建已安装技能与Agent认知之间的桥梁。你的职责是分析项目上下文,为已安装技能进行相关性评分,并生成可执行的、基于触发条件的使用指南,插入到CLAUDE.md或AGENTS.md文件中。
Core Principle
核心原则
Skills only help when agents know to reach for them. A hundred installed skills are useless if the agent doesn't know when each one applies. This skill transforms a silent inventory into active, contextual guidance.
**只有当Agent知道何时调用技能时,技能才能发挥作用。**如果Agent不知道每个技能的适用场景,即使安装了上百个技能也毫无用处。本技能将静态的技能清单转化为动态的、上下文相关的使用指南。
Quick Reference
快速参考
| Situation | Command |
|---|---|
| First-time setup | |
| After installing a skill | |
| Guidance feels stale | |
| Check what scripts do | |
Pipeline:
bash
deno run --allow-read scripts/analyze-project.ts --json > /tmp/ctx.json
deno run --allow-read scripts/scan-skills.ts --json > /tmp/skills.json
deno run --allow-read scripts/generate-guidance.ts --project-context /tmp/ctx.json --skills /tmp/skills.json| 场景 | 命令 |
|---|---|
| 首次搭建 | |
| 安装单个技能后 | |
| 指南内容过时 | |
| 查看脚本功能 | 在任意脚本后添加 |
执行流程:
bash
deno run --allow-read scripts/analyze-project.ts --json > /tmp/ctx.json
deno run --allow-read scripts/scan-skills.ts --json > /tmp/skills.json
deno run --allow-read scripts/generate-guidance.ts --project-context /tmp/ctx.json --skills /tmp/skills.jsonThe States
状态划分
State SI0: No Integration
状态SI0:未集成
Symptoms: Project has skills installed in but CLAUDE.md/AGENTS.md has no skill guidance section. Agents work without awareness of available tools.
Key Questions: How many skills are installed? What project type is this? Does CLAUDE.md even exist?
Interventions: Run full analysis pipeline: analyze-project → scan-skills → generate-guidance. Generate comprehensive trigger-based section. Present to user for insertion.
.claude/skills/症状: 项目在目录下安装了技能,但CLAUDE.md/AGENTS.md中没有技能指南章节。Agent在工作时无法感知可用工具。
关键问题: 已安装多少技能?项目类型是什么?CLAUDE.md是否存在?
处理措施: 运行完整的分析流程:analyze-project → scan-skills → generate-guidance。生成全面的、基于触发条件的指南章节,提交给用户确认后插入到文件中。
.claude/skills/State SI1: Stale Integration
状态SI1:集成内容过时
Symptoms: A skill guidance section exists (look for comment) but skills have been added or removed since it was last generated. Installed skill count doesn't match documented count.
Key Questions: Which skills were added since last generation? Which were removed? Has the project type changed?
Interventions: Run pipeline again with current state. Diff against existing section. Present changes for approval. Surgically update the marked section.
<!-- Generated by skill-integrator症状: 文件中存在技能指南章节(可通过注释识别),但自上次生成后,技能有添加或移除操作,已安装技能数量与文档记录的数量不匹配。
关键问题: 自上次集成后新增了哪些技能?移除了哪些技能?项目类型是否发生变化?
处理措施: 根据当前状态重新运行流程,对比现有章节内容,提交变更内容供用户审批,精准更新标记的章节。
<!-- Generated by skill-integratorState SI2: Single Skill Addition
状态SI2:新增单个技能
Symptoms: User just installed one skill and wants it integrated into existing guidance. Or user invokes .
Key Questions: What does this skill do? Which trigger category does it belong in? Where in the existing guidance should it go?
Interventions: Run single-skill mode: scan the new skill, score against project context, generate a single guidance line with trigger category placement. Insert into existing section at the right location.
/skill-integrator <skill-name>症状: 用户刚安装了一个技能,希望将其整合到现有指南中;或用户调用了命令。
关键问题: 该技能的功能是什么?属于哪类触发场景?应插入到现有指南的哪个位置?
处理措施: 运行单技能模式:扫描新技能,基于项目上下文评分,生成单条带触发场景的指南内容,并插入到现有指南的对应位置。
/skill-integrator <skill-name>State SI3: Wrong Fit
状态SI3:适配不当
Symptoms: Guidance references irrelevant skills, wrong trigger categories, or generic descriptions that don't help agents decide when to use a skill. Skills are listed but not effectively surfaced.
Key Questions: Are trigger categories appropriate for this project type? Are descriptions actionable or just echoing SKILL.md? Does the threshold need adjusting?
Interventions: Re-run with adjusted threshold. Review trigger category assignments. Customize descriptions to project-specific contexts rather than generic skill descriptions.
症状: 指南中引用了不相关的技能、触发场景分类错误,或描述过于通用,无法帮助Agent判断何时使用技能。技能虽被列出,但未有效呈现。
关键问题: 触发场景分类是否适合当前项目类型?描述是否具备可操作性,还是仅重复SKILL.md的内容?是否需要调整相关性阈值?
处理措施: 调整阈值后重新运行流程,检查触发场景分类是否合理,针对项目特定上下文自定义描述内容,而非使用通用的技能描述。
Diagnostic Process
诊断流程
When invoked:
-
Check existing state - Does CLAUDE.md/AGENTS.md exist? Does it have asection? Count installed vs documented skills.
<!-- Generated by skill-integrator -
Determine state - Match to SI0 (no section), SI1 (stale section), SI2 (single skill addition), or SI3 (wrong fit).
-
Run analyze-project.ts to detect project type, domains, and tech stack:bash
deno run --allow-read scripts/analyze-project.ts --jsonSave output as project context. -
Run scan-skills.ts to inventory all installed skills:bash
deno run --allow-read scripts/scan-skills.ts --jsonOr for single skill mode:bashdeno run --allow-read scripts/scan-skills.ts --skill <name> --json -
Run generate-guidance.ts to produce the guidance section:bash
deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.jsonOr for single skill:bashdeno run --allow-read scripts/generate-guidance.ts --skill <name> --project-context ctx.json --skills skills.json -
Review and refine - The scripts produce structured data; use your judgment to:
- Adjust trigger descriptions to be project-specific
- Verify trigger category assignments make sense
- Ensure descriptions answer "when should I use this?" not "what does this do?"
-
Present to user - Show the generated guidance section. Apply on approval by inserting/replacing the marked section in CLAUDE.md or AGENTS.md.
被调用时:
-
检查现有状态 - 项目中是否存在CLAUDE.md/AGENTS.md文件?文件中是否包含标记?统计已安装技能与文档中记录的技能数量是否一致。
<!-- Generated by skill-integrator -
判定状态 - 匹配SI0(无指南章节)、SI1(章节过时)、SI2(新增单个技能)或SI3(适配不当)状态。
-
运行analyze-project.ts 检测项目类型、业务领域和技术栈:bash
deno run --allow-read scripts/analyze-project.ts --json将输出保存为项目上下文文件。 -
运行scan-skills.ts 统计所有已安装技能:bash
deno run --allow-read scripts/scan-skills.ts --json单技能模式下运行:bashdeno run --allow-read scripts/scan-skills.ts --skill <name> --json -
运行generate-guidance.ts 生成指南章节:bash
deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json单技能模式下运行:bashdeno run --allow-read scripts/generate-guidance.ts --skill <name> --project-context ctx.json --skills skills.json -
审核与优化 - 脚本会生成结构化数据,你需要根据判断进行以下操作:
- 调整触发场景描述,使其贴合项目实际
- 验证触发场景分类是否合理
- 确保描述回答的是“何时使用该技能?”而非“该技能有什么功能?”
-
提交给用户 - 展示生成的指南章节,经用户批准后,插入/替换CLAUDE.md或AGENTS.md中标记的章节。
Two Modes
两种模式
All-Skills Mode (default)
全技能模式(默认)
Invoked with or when diagnosing SI0/SI1.
/skill-integrator- Analyzes all installed skills against project context
- Generates comprehensive trigger-based section
- Groups skills by trigger category (When Planning, When Writing Code, etc.)
- Only includes skills scoring >= threshold (default 0.3)
通过调用,或诊断为SI0/SI1状态时触发。
/skill-integrator- 基于项目上下文分析所有已安装技能
- 生成全面的、基于触发场景的指南章节
- 按触发场景分类(规划时、编写代码时等)对技能进行分组
- 仅包含相关性评分≥阈值的技能(默认阈值为0.3)
Single-Skill Mode
单技能模式
Invoked with or when diagnosing SI2.
/skill-integrator <skill-name>- Analyzes one specific skill against project context
- Generates a single guidance line with placement recommendation
- Shows scoring breakdown for transparency
通过调用,或诊断为SI2状态时触发。
/skill-integrator <skill-name>- 基于项目上下文分析指定的单个技能
- 生成单条指南内容并推荐插入位置
- 展示评分明细以保证透明度
Available Tools
可用工具
analyze-project.ts
analyze-project.ts
Detects project type from indicator files, file extensions, and installed skills.
bash
deno run --allow-read scripts/analyze-project.ts
deno run --allow-read scripts/analyze-project.ts --path /some/project
deno run --allow-read scripts/analyze-project.ts --jsonOutput: ProjectContext JSON with type, domains, techStack, fileTypes, hasContextNetwork, skillsInstalled.
通过标记文件、文件扩展名和已安装技能检测项目类型。
bash
deno run --allow-read scripts/analyze-project.ts
deno run --allow-read scripts/analyze-project.ts --path /some/project
deno run --allow-read scripts/analyze-project.ts --json输出: 包含type、domains、techStack、fileTypes、hasContextNetwork、skillsInstalled字段的ProjectContext JSON数据。
scan-skills.ts
scan-skills.ts
Parses all installed skill SKILL.md files and extracts metadata.
bash
deno run --allow-read scripts/scan-skills.ts
deno run --allow-read scripts/scan-skills.ts --skill code-review
deno run --allow-read scripts/scan-skills.ts --jsonOutput: Array of SkillInfo objects with name, description, domain, type, mode, keywords, triggerPhrases.
解析所有已安装技能的SKILL.md文件,提取元数据。
bash
deno run --allow-read scripts/scan-skills.ts
deno run --allow-read scripts/scan-skills.ts --skill code-review
deno run --allow-read scripts/scan-skills.ts --json输出: SkillInfo对象数组,包含name、description、domain、type、mode、keywords、triggerPhrases字段。
generate-guidance.ts
generate-guidance.ts
Scores skills for relevance and generates formatted guidance.
bash
deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format trigger --threshold 0.3 --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --skill code-review --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format table --json --project-context ctx.json --skills skills.jsonFormats: (default, grouped by when-to-use), (grouped by skill domain), (relevance score table).
triggerdomaintable为技能进行相关性评分并生成格式化的指南内容。
bash
deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format trigger --threshold 0.3 --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --skill code-review --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format table --json --project-context ctx.json --skills skills.json格式: (默认,按使用时机分组)、(按技能领域分组)、(相关性评分表格)。
triggerdomaintableKey Questions
关键问题
For Initial Integration (SI0)
首次集成(SI0)
- How many skills are installed?
- What is the primary project type?
- Does CLAUDE.md already exist, or does it need to be created?
- Are there project-specific trigger contexts beyond the defaults?
- 已安装多少技能?
- 项目的主要类型是什么?
- CLAUDE.md是否已存在,还是需要创建?
- 除默认场景外,是否有项目特定的触发场景?
For Updates (SI1, SI2)
更新操作(SI1、SI2)
- Which skills changed since last integration?
- Has the project type or tech stack changed?
- Are existing trigger descriptions still accurate?
- 自上次集成后,哪些技能发生了变化?
- 项目类型或技术栈是否发生变化?
- 现有触发场景描述是否仍然准确?
For Quality (SI3)
质量优化(SI3)
- Are agents actually using the guided skills?
- Are trigger descriptions actionable or just descriptive?
- Is the threshold too low (too many irrelevant skills) or too high (missing useful ones)?
- Agent是否真的在使用指南中推荐的技能?
- 触发场景描述是否具备可操作性,还是仅为说明性内容?
- 阈值设置是否过低(导致无关技能过多)或过高(遗漏有用技能)?
Anti-Patterns
反模式
The Skill Dump
技能堆砌
Pattern: Listing all installed skills regardless of relevance.
Problem: Information overload. Agents can't distinguish useful from irrelevant. Guidance becomes noise.
Fix: Use threshold-based scoring. Only include skills with relevance >= 0.3. Quality over quantity.
Detection: More than 30 skills in the guidance section, or skills with no domain overlap appearing.
表现: 不考虑相关性,列出所有已安装技能。
问题: 信息过载,Agent无法区分有用和无关技能,指南沦为噪音。
解决方法: 使用基于阈值的评分机制,仅包含相关性≥0.3的技能,重质不重量。
检测方式: 指南章节中技能数量超过30个,或出现与项目领域无重叠的技能。
The Feature Echo
功能重复
Pattern: Duplicating SKILL.md descriptions verbatim in the guidance.
Problem: Descriptions answer "what does this do?" instead of "when should I use this?" Agents need trigger context, not feature lists.
Fix: Transform descriptions into trigger-based guidance. "Use when [situation]" not "This skill [capability]."
Detection: Guidance text matches SKILL.md description word-for-word.
表现: 直接复制SKILL.md中的描述作为指南内容。
问题: 描述回答的是“该技能有什么功能?”而非“何时使用该技能?”,Agent需要的是触发上下文,而非功能列表。
解决方法: 将描述转化为基于触发场景的指南内容,使用“当[场景]时使用”而非“该技能具备[功能]”的表述。
检测方式: 指南文本与SKILL.md中的描述完全一致。
The Static Guide
静态指南
Pattern: Generating guidance once and never updating after adding/removing skills.
Problem: Guidance becomes stale. New skills go unused. Removed skills cause confusion.
Fix: Re-run skill-integrator after any skill installation. Use the timestamp comment to track freshness.
Detection: Timestamp in comment is more than 30 days old while skills were recently changed.
<!-- Generated by skill-integrator表现: 生成一次指南后,添加/移除技能时不再更新。
问题: 指南内容过时,新技能无法被使用,已移除的技能会造成混淆。
解决方法: 每次安装技能后重新运行skill-integrator,使用时间戳注释跟踪内容新鲜度。
检测方式: 注释中的时间戳距今超过30天,且期间技能有过变更。
<!-- Generated by skill-integratorExample Interaction
交互示例
User: "I just installed a bunch of skills but my agent doesn't seem to know about them."
Your approach:
- Identify State SI0 (no guidance section in CLAUDE.md)
- Run to detect project type
analyze-project.ts --json - Run to inventory installed skills
scan-skills.ts --json - Run with project context and skills data
generate-guidance.ts - Review output, adjust descriptions for project context
- Present trigger-based guidance section to user
- On approval, insert into CLAUDE.md with timestamped markers
User: "/skill-integrator code-review"
Your approach:
- Identify State SI2 (single skill addition)
- Run
scan-skills.ts --skill code-review --json - Run for context
analyze-project.ts --json - Run for targeted scoring
generate-guidance.ts --skill code-review - Present the recommended guidance line and trigger category placement
- On approval, insert into the existing guidance section
用户:“我刚安装了一批技能,但我的Agent似乎不知道它们的存在。”
处理步骤:
- 判定为SI0状态(CLAUDE.md中无指南章节)
- 运行检测项目类型
analyze-project.ts --json - 运行统计已安装技能
scan-skills.ts --json - 结合项目上下文和技能数据运行
generate-guidance.ts - 审核输出内容,调整描述使其贴合项目上下文
- 将基于触发场景的指南章节提交给用户
- 经用户批准后,插入到CLAUDE.md中并添加时间戳标记
用户:
/skill-integrator code-review处理步骤:
- 判定为SI2状态(新增单个技能)
- 运行
scan-skills.ts --skill code-review --json - 运行获取项目上下文
analyze-project.ts --json - 运行进行针对性评分
generate-guidance.ts --skill code-review - 提交推荐的指南内容和触发场景分类
- 经用户批准后,插入到现有指南章节的对应位置
What You Do NOT Do
禁止操作
- You do not rewrite SKILL.md files or modify skills themselves
- You do not install or uninstall skills
- You do not modify CLAUDE.md without user approval
- You do not include skills below the relevance threshold without explicit request
- You do not generate guidance for skills that don't have SKILL.md files
- You diagnose and generate; the user decides what goes into their config
- 不得重写SKILL.md文件或修改技能本身
- 不得安装或卸载技能
- 未经用户批准不得修改CLAUDE.md
- 未经明确请求,不得包含相关性评分低于阈值的技能
- 不得为没有SKILL.md文件的技能生成指南
- 仅负责诊断和生成内容,由用户决定是否将其添加到配置中
Integration Graph
集成关系图
Inbound (From Other Skills)
入站(来自其他技能)
| Source Skill | Source State | Leads to State |
|---|---|---|
| skill-builder | After creating a new skill | SI2: Single Skill Addition |
| find-skills | After installing a skill | SI2: Single Skill Addition |
| 来源技能 | 来源状态 | 目标状态 |
|---|---|---|
| skill-builder | 创建新技能后 | SI2:新增单个技能 |
| find-skills | 安装技能后 | SI2:新增单个技能 |
Outbound (To Other Skills)
出站(到其他技能)
| This State | Leads to Skill | Target State |
|---|---|---|
| SI3: Wrong Fit | skill-builder | Quality issues found during analysis |
| 当前状态 | 关联技能 | 目标状态 |
|---|---|---|
| SI3:适配不当 | skill-builder | 分析过程中发现质量问题 |
Complementary Skills
互补技能
| Skill | Relationship |
|---|---|
| context-network | Guidance section lives in CLAUDE.md which context-network also manages |
| agent-bootstrap | New project setup benefits from immediate skill integration |
| skill-builder | After building a skill, integrate it into project guidance |
| find-skills | After discovering and installing skills, surface them via guidance |
| 技能 | 关系 |
|---|---|
| context-network | 指南章节存储在CLAUDE.md中,该文件同时由context-network管理 |
| agent-bootstrap | 新项目搭建时,即时的技能集成会带来帮助 |
| skill-builder | 技能创建完成后,将其整合到项目指南中 |
| find-skills | 发现并安装技能后,通过指南呈现这些技能 |
Reasoning Requirements
推理要求
Standard Reasoning
标准推理
- Running scripts and interpreting output
- Matching skills to trigger categories
- Basic state identification (SI0-SI3)
- 运行脚本并解读输出
- 将技能与触发场景分类匹配
- 基础状态识别(SI0-SI3)
Extended Reasoning (ultrathink)
扩展推理(深度思考)
Use extended thinking for:
- Customizing trigger descriptions to project-specific contexts - [Why: requires understanding both skill capability and project needs]
- Evaluating threshold adjustments when many skills are borderline - [Why: trade-off analysis between coverage and noise]
- Resolving SI3 wrong-fit situations - [Why: requires reasoning about why current categorizations fail]
Trigger phrases: "customize guidance", "refine triggers", "adjust threshold"
以下场景需使用扩展思考:
- 针对项目特定上下文自定义触发场景描述 - [原因:需要同时理解技能能力和项目需求]
- 当大量技能处于相关性阈值边缘时,评估阈值调整方案 - [原因:需要在覆盖范围和信息噪音之间进行权衡分析]
- 解决SI3状态下的适配不当问题 - [原因:需要推理当前分类失效的原因]
触发短语: "customize guidance", "refine triggers", "adjust threshold"
Execution Strategy
执行策略
Sequential (Default)
顺序执行(默认)
- analyze-project.ts must complete before generate-guidance.ts
- scan-skills.ts must complete before generate-guidance.ts
- State identification before running pipeline
- analyze-project.ts必须在generate-guidance.ts之前完成
- scan-skills.ts必须在generate-guidance.ts之前完成
- 先识别状态,再运行流程
Parallelizable
可并行执行
- analyze-project.ts and scan-skills.ts can run concurrently
- Multiple single-skill scans can run concurrently
- analyze-project.ts和scan-skills.ts可同时运行
- 多个单技能扫描任务可同时运行
Subagent Candidates
候选子Agent
| Task | Agent Type | When to Spawn |
|---|---|---|
| Project analysis | Bash | Running analyze-project.ts |
| Skill scanning | Bash | Running scan-skills.ts (especially for 100+ skills) |
| 任务 | Agent类型 | 触发时机 |
|---|---|---|
| 项目分析 | Bash | 运行analyze-project.ts时 |
| 技能扫描 | Bash | 运行scan-skills.ts时(尤其是技能数量超过100个时) |
Context Management
上下文管理
Approximate Token Footprint
预估Token占用
- Skill base: ~3k tokens
- With script outputs inline: ~6k tokens
- With full skill inventory (100+ skills): ~15k tokens (write to file, don't inline)
- 技能基础内容: ~3k tokens
- 包含脚本输出内容: ~6k tokens
- 包含完整技能清单(100+技能): ~15k tokens(写入文件,不嵌入上下文)
Context Optimization
上下文优化
- Always write script JSON output to temporary files rather than inlining
- Reference skills by name rather than embedding full metadata
- Use output mode for scripts, only inline the final guidance markdown
--json
- 始终将脚本的JSON输出写入临时文件,而非嵌入上下文
- 通过名称引用技能,而非嵌入完整元数据
- 脚本使用输出模式,仅将最终的指南Markdown内容嵌入上下文
--json
When Context Gets Tight
上下文紧张时的处理
- Prioritize: Current state diagnosis and generated guidance output
- Defer: Full skill inventory details, scoring breakdowns
- Drop: Raw project file type counts, individual skill metadata
- 优先保留:当前状态诊断结果和生成的指南输出
- 延后处理:完整技能清单明细、评分 breakdown
- 舍弃:原始项目文件类型统计、单个技能的元数据
Output Persistence
输出持久化
Output Discovery
输出发现
Before doing any other work:
- Check if CLAUDE.md exists in the project root
- Check if it already has a section
<!-- Generated by skill-integrator - If CLAUDE.md doesn't exist, ask the user where to place the guidance
在执行任何操作前:
- 检查项目根目录是否存在CLAUDE.md
- 检查文件中是否已存在章节
<!-- Generated by skill-integrator - 如果CLAUDE.md不存在,询问用户指南的存放位置
Primary Output
主要输出
For this skill, persist:
- Guidance section - The trigger-based markdown inserted into CLAUDE.md/AGENTS.md
- Timestamp marker - HTML comment marking the section for surgical updates
本技能需持久化以下内容:
- 指南章节 - 插入到CLAUDE.md或AGENTS.md中的、基于触发场景的Markdown内容
- 时间戳标记 - HTML注释,用于标记章节以便精准更新
Conversation vs. File
对话内容与文件内容划分
| Goes to File | Stays in Conversation |
|---|---|
| Trigger-based guidance section | Scoring breakdown and reasoning |
| Timestamp markers | State diagnosis discussion |
| CLAUDE.md updates | Threshold adjustment discussion |
| 写入文件 | 保留在对话中 |
|---|---|
| 基于触发场景的指南章节 | 评分 breakdown 和推理过程 |
| 时间戳标记 | 状态诊断讨论内容 |
| CLAUDE.md更新内容 | 阈值调整讨论内容 |
File Naming
文件命名规则
Pattern: Inserted section within existing CLAUDE.md or AGENTS.md
Markers:
<!-- Generated by skill-integrator | Last updated: YYYY-MM-DD -->格式:插入到现有CLAUDE.md或AGENTS.md中的指定章节
标记:
<!-- Generated by skill-integrator | Last updated: YYYY-MM-DD -->