第 23 章 · 指令、Skills 与渐进加载

本章目标：知道一条要求应该放在当前 prompt、项目指令还是可复用 Skill 中，并理解渐进披露怎样节省上下文。

1. 指令有作用域

一次性要求只属于当前任务；仓库长期约定适合 AGENTS.md 或 CLAUDE.md；跨项目个人偏好属于用户级配置。越靠近工作目录的项目指令通常越具体。

指令文件适合构建命令、目录职责、代码规范和审查要求。它不适合塞入完整 API 手册和几千行流程，否则每个任务都为无关内容付费。

2. Skill 是工作方法包

Skill 通常包含元数据、SKILL.md、参考资料、脚本和模板。它不是新工具，而是告诉 Agent 在某类任务中如何使用现有工具。发布、数据库迁移、文档渲染和故障排查都适合 Skill。

一个 Skill 的核心问题是触发描述：模型怎样知道何时使用。如果 description 太宽，会误触发；太窄，则明明需要却发现不了。

3. 渐进披露

开始时只加载每个 Skill 的名称和描述；匹配任务后加载完整 SKILL.md；遇到具体问题再读取 references；确定性步骤运行 scripts。这个分层让 Agent 能携带许多能力，而不把所有说明常驻上下文。

元数据：几十 tokens，始终可发现
→ SKILL.md：被选中时加载
→ references：需要细节时读取
→ scripts：确定性执行，不靠模型重写

4. 规则与 Skill 的选择

“这个仓库永远用 pnpm”是规则；“发布 npm 包的完整步骤”是 Skill；“本次只发布 beta”是当前 prompt。选择标准是作用域和复杂度，而不是文件格式。

当 Skill 依赖外部系统时，可以声明 MCP 依赖；需要强制验证时配合 Hook；需要团队分发时打包为 Plugin。不同机制组合，而不是争夺唯一位置。

5. 如何写可执行 Skill

好的 Skill 说明输入、步骤、决策点、工具、验证和失败处理。确定命令放脚本，复杂判断留给模型。示例要覆盖常见分支，但不要把某次项目路径写死成通用规则。

Skill 本身也需要版本、测试和安全审查。脚本拥有真实权限，不能因为来自“说明文件”就跳过信任检查。

6. 维护反馈循环

Agent 反复犯同一项目错误，应更新规则；重复执行同一复杂流程，应抽成 Skill；Skill 触发错误，应调整描述并用任务样本评测。这样人类的审查反馈逐步变成可复用基础设施。