深入解析 get-shit-done 的 Project Skills Discovery：执行前如何按需发现并应用项目级技能规则

本文基于 get-shit-done 参考文档 project-skills-discovery.md 展开，结合 Skill Discovery Contract、多个 Agent 定义与测试用例，系统讲解 GSD 在多 Agent 流水线中如何发现项目自定义 Skills、按其规则行动、同时把上下文成本压到最低。读完你将掌握：技能目录的查找顺序、SKILL.md 与 rules/*.md 的分层加载策略、五类角色的应用差异，以及底层扫描器与清单的工程实现。

为什么要做“项目技能发现”：上下文预算是第一驱动力

在 Claude Code 等大上下文环境下，Agent 每读入一份文件都会占用宝贵的上下文窗口。get-shit-done 的 Agent 系统中，一个常见误区是“开工前把所有项目规范读一遍”——这恰恰是文档要避免的做法。

参考文档开宗明义地指出，执行开始前（Before execution）应当检查项目自定义的 Skills 并应用其规则，但其关键约束是有选择、分层次地加载：

• 项目根目录下可能同时存在 .claude/skills/、.agents/skills/ 等技能目录，也可能存在体量巨大的 AGENTS.md；
• 文档明确给出量级参考：单个技能的 SKILL.md 是“轻量索引，约 130 行”，而一份完整 AGENTS.md 可能高达 100KB+，全部载入会显著消耗上下文（参见 agent-size-budget 所校验的预算纪律）；
• 因此核心策略是：只加载技能目录的轻量索引，规则细节按需读取，绝不整体吞入大型 AGENTS.md。

这里需要区分两个“Skills”概念：本仓库自身的 GSD 框架技能（目录名以 gsd- 前缀标识，见 Skill Discovery Contract）与用户项目自定义的技能。本文讨论的 Project Skills Discovery 面向的是运行在用户仓库中的 GSD Agent 去发现宿主项目定义的技能。

五个发现步骤：一套共享给所有 GSD Agent 的流程

参考文档明确规定这些步骤“shared across all GSD agents”（所有 GSD Agent 共享），其顺序与终止条件都经过设计，目的是用最少的磁盘探测获得最准确的技能清单：

Step 1 — 探测目录，不存在即跳过 检查 .claude/skills/ 或 .agents/skills/ 目录；若两者都不存在，直接跳过整个技能发现流程，不再浪费时间。

Step 2 — 列出可用技能 将技能目录下的每个子目录视为一个技能。

Step 3 — 为每个技能读取 SKILL.md SKILL.md 被刻意设计成轻量索引（约 130 行），用于描述该技能的用途与何时触发，而不是承载全部规则细节。

Step 4 — 按需加载 rules/*.md 仅在当前任务真正需要时，才读取具体技能下的 rules/*.md 规则文件。例如 Executor 在执行某任务需要对应编码规范时才去加载。

Step 5 — 不要整体加载 AGENTS.md 即使项目根目录存在 AGENTS.md（体量可达 100KB+），也不要整份载入。原因是其上下文成本过高，与第 3、4 步的“轻量索引 + 按需细读”策略相悖。

这套流程在多个 Agent 定义中得到逐字贯彻。例如 gsd-codebase-mapper.md、gsd-code-reviewer.md、gsd-doc-verifier.md 等 Agent 的 **Project skills:** 小节都完整写入了相同的三步序列：探测 .claude/skills/ 或 .agents/skills/ → 读取每个技能的 SKILL.md（标注 ~130 行轻量索引）。

五类角色的应用差异：发现之后“怎么用”由调用方决定

参考文档强调：发现并加载规则之后，如何应用取决于调用它的 Agent（how to apply the loaded rules depends on the calling agent），并且“调用方的 Agent 文件应当明确指定采用哪种应用方式”。文档给出了五类约定：

角色	应用方式
Planner	在计划中把项目技能模式与约定纳入考量
Executor	遵循与当前待实现任务相关的技能规则
Researcher	确保研究输出契合项目技能模式
Verifier	在扫描反模式与质量验证时套用技能规则
Debugger	遵循与被调查 Bug、被应用的修复相关的技能规则

该约定同样体现在 Agent 文件中。引用参考文档、并明确写出各自应用场景的 Agent 包括：

• gsd-executor.md：@~/.claude/get-shit-done/references/project-skills-discovery.md，注明“Load rules/*.md as needed during implementation”（实现阶段按需加载），并要求遵循与即将提交任务相关的技能规则；
• gsd-verifier.md：同样引用该文档，注明在 verification 阶段按需加载 rules/*.md，并在扫描反模式、核对质量时应用技能规则；
• gsd-debugger.md：用于 investigation and fix（排查与修复）；
• gsd-planner.md、gsd-phase-researcher.md：Planner 与 Researcher 分别把技能模式纳入计划与研究报告。

注意：Agent 中出现的 ~/.claude/get-shit-done/references/... 是 GSD 安装到本机后的展开路径；在当前仓库中，对应文件即 get-shit-done/references/project-skills-discovery.md。

技能根目录的完整扫描契约

若说参考文档回答的是“Agent 行为层面怎么发现”，那么 Skill Discovery Contract 就是这些规则的工程化落地契约，它定义了扫描、盘点与渲染 GSD 技能的权威规则。当 GSD 作为框架扫描技能时，会同时区分项目根与全局托管根：

类别	根目录	用途
项目根（相对项目根扫描）	.claude/skills/、.agents/skills/、.cursor/skills/、.github/skills/、./.codex/skills/	项目专属技能，以及项目 CLAUDE.md 的技能区段
全局托管根（相对用户主目录）	~/.claude/skills/、~/.codex/skills/	托管运行时安装与清单上报
弃用的仅导入根	~/.claude/get-shit-done/skills/	仅用于旧版迁移，新安装不应写入
遗留 Claude 命令	~/.claude/commands/gsd/	非技能根，仅用于识别遗留 Claude 安装

参考文档只提及前两个项目根（.claude/skills/ 与 .agents/skills/），而 Discovery Contract 在此基础上把项目扫描面扩展到了 Cursor、GitHub、Codex 等更多运行时的技能根——这体现了两份文档的层次关系：参考文档约束 Agent 行为，契约文档约束实现边界。

契约还定义了规范化规则，例如：只扫描含 SKILL.md 的子目录；从 YAML frontmatter 读取 name 与 description，name 缺失时回退用目录名；从正文中匹配 TRIGGER when: ... 提取触发提示；把 gsd-* 目录视为框架自装技能；把 ~/.claude/get-shit-done/skills/ 条目视为弃用等。这解释了为什么 Agent 只需“列出子目录再读 SKILL.md”——frontmatter 的 name/description/trigger 正是被后续扫描器重用的标准化元数据。

源码中的三层扫描实现：SDK 查询、CLAUDE.md 渲染与安装清单

契约文件把“发现”落到三个可执行的位置，从源码结构看恰好构成三层能力：

第一层：SDK 查询器 —— sdk/src/query/skills.ts 返回去重后的技能名清单，扫描范围是项目根 + 全局托管根，不扫描弃用的仅导入根。这是 Agent 与运行时查询“当前项目有哪些技能”的入口。

第二层：CLAUDE.md 技能区段生成 —— get-shit-done/bin/lib/profile-output.cjs 它负责构建项目 CLAUDE.md 的技能区段：只扫描项目根，跳过 gsd-* 目录（让项目区段聚焦于用户/项目自定义技能），并把 ./.codex/skills/ 纳入项目发现集合。也就是说，技能发现的结果会物化进宿主项目的 CLAUDE.md，供后续会话直接看到技能索引。

第三层：安装清单 —— get-shit-done/bin/lib/init.cjs 为 skill-manifest 生成技能盘点对象，上报 skills、roots、installation、counts 四类信息；当发现任何以 gsd- 开头的技能名时标记 gsd_skills_installed，当 ~/.claude/commands/gsd/ 下存在 .md 命令文件时标记 legacy_claude_commands_installed。

这三层各司其职：SDK 负责“查”，profile-output 负责“写进宿主文档”，init 负责“安装后盘点”。相关行为在测试中可验证，例如 skill-manifest.test.cjs、skill-frontmatter-contract.test.cjs 与 agent-skills.test.cjs 都直接或间接约束了技能的发现、frontmatter 元数据与 Agent 对技能目录的感知。若想深入，agent-required-reading-consistency.test.cjs 与 agent-size-budget.test.cjs 还从一致性、体积预算角度守护 Agent 读取策略。

从参考文档看最佳实践：如何在自己的项目中落地

参考文档虽短，但蕴含一套可移植的方法论。若要为自己的 Claude Code / GSD 项目启用这套技能发现，可遵循以下要点：

1. 技能必须是“索引 + 细节”两层结构：每个技能目录放一个轻量 SKILL.md（明确 name、description、何时触发），把繁重规则拆到 rules/*.md，让 Agent 先用 ~130 行的索引判断“是否与我相关”，再决定要不要细读。
2. 把“不做什么”也写进约定：像“不要整份加载 100KB+ 的 AGENTS.md”这样的负面清单，与正面步骤同等重要——它直接保护上下文预算。
3. 应用方式交由调用方声明：技能是通用资产，但 Planner、Executor、Verifier 对它的用法不同，应像 GSD 各 Agent 那样在各自定义中写明“在哪个阶段、为何种目的加载”。
4. 目录探测要有终止条件：.claude/skills/ 与 .agents/skills/ 都不存在就跳过，避免无谓的文件系统遍历。
5. 让实现与行为分层：Agent 侧只遵循“探测 → 列目录 → 读 SKILL.md → 按需读 rules/*.md”的行为契约，至于具体扫描哪些根、如何去重与渲染，交给 sdk/src/query/skills.ts、profile-output.cjs、init.cjs 这类底层实现。

综上，Project Skills Discovery 是 get-shit-done 在“功能强大的多 Agent 规范驱动系统”与“有限上下文”之间取得平衡的关键机制：通过把技能发现收敛为五个步骤、把技能内容收敛为两层结构、把应用方式下放给各 Agent 定义，让项目级规则在正确时机以最小成本进入推理过程，而不至于拖垮整次会话。