skill-integrator

用途

Skill Integrator 用于弥合“已安装技能”与“智能体认知”之间的差距。它的核心原则是：技能只有在智能体知道何时该使用它时才有帮助；如果智能体不知道每个技能的适用场景，安装再多技能也没有意义。该技能把一份沉默的技能清单转化为主动的、带上下文的指引，写入项目的 CLAUDE.md 或 AGENTS.md。

主要能力

分析项目上下文：检测项目类型、领域、技术栈、文件类型等。
扫描已安装技能：解析 .claude/skills/ 下各技能的 SKILL.md，提取名称、描述、领域、类型、模式、关键词、触发短语等元数据。
相关性评分与指引生成：根据项目上下文对技能打分，只纳入达到阈值（默认 0.3）的技能，并按触发类别分组生成指引。
支持多种输出格式：trigger（默认，按何时使用分组）、domain（按技能领域分组）、table（相关性评分表）。
支持全量模式与单技能模式。
通过时间戳标记实现可外科式更新的指引区块。

使用方式

常见调用方式：

首次设置：/skill-integrator，生成完整指引区块。
安装某个技能后：/skill-integrator <skill-name>，添加单个技能。
指引过时：/skill-integrator，按当前清单重新生成。
查看脚本用途：对任意脚本使用 --help。

流水线命令：

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

脚本说明：

analyze-project.ts：从指示文件、文件扩展名和已安装技能检测项目类型。输出 ProjectContext JSON，包含 type、domains、techStack、fileTypes、hasContextNetwork、skillsInstalled。
scan-skills.ts：解析所有已安装技能的 SKILL.md 并提取元数据。输出 SkillInfo 数组，包含 name、description、domain、type、mode、keywords、triggerPhrases。支持 --skill <name> 单技能扫描。
generate-guidance.ts：对技能进行相关性评分并生成格式化指引。支持 --format trigger|domain|table、--threshold、--skill、--json 等参数。

状态模型

SI0 无整合：项目已安装技能，但 CLAUDE.md/AGENTS.md 中没有技能指引区块。处理方式是运行完整分析流水线并生成综合指引。
SI1 整合过时：存在指引区块（含 <!-- Generated by skill-integrator 注释），但技能有增删，已安装数量与文档记录数量不一致。处理方式是重新运行流水线、与现有区块对比、经批准后外科式更新。
SI2 单技能添加：用户刚安装一个技能并希望整合进现有指引，或调用 /skill-integrator <skill-name>。处理方式是单技能模式扫描、评分并插入到合适位置。
SI3 不匹配：指引引用了不相关技能、触发类别错误，或描述过于泛泛无法帮助智能体判断何时使用。处理方式是调整阈值、复查触发类别、按项目上下文定制描述。

适用场景

项目已安装多个技能，但智能体不知道何时该调用它们。
新安装技能后，需要把它加入项目指引。
技能增删后，原有指引区块需要刷新。
指引内容与项目类型不匹配，需要重新评分和分类。

限制与边界

不重写 SKILL.md，也不修改技能本身。
不安装或卸载技能。
未经用户批准不修改 CLAUDE.md。
未经明确要求不纳入低于相关性阈值的技能。
不为没有 SKILL.md 文件的技能生成指引。
该技能只负责诊断和生成，最终写入配置由用户决定。

反模式

技能堆砌：不加筛选列出所有已安装技能，造成信息过载。应使用阈值评分，只纳入相关性 >= 0.3 的技能。
功能复读：逐字复制 SKILL.md 描述。应转化为“何时使用”的触发式指引。
静态指引：生成一次后不再更新。应在技能安装后重新运行，并利用时间戳注释跟踪新鲜度。

输出与持久化

主要输出是插入 CLAUDE.md/AGENTS.md 的触发式 markdown 指引区块，以及用于外科式更新的时间戳标记：。评分明细和状态诊断讨论保留在对话中，指引区块和 CLAUDE.md 更新写入文件。若 CLAUDE.md 不存在，需询问用户放置位置。