如何为大模型智能体编写高质量的技能指令文件

本指南从 Claude Code 团队公开的工程实践中提炼，但原则适用于所有大模型 Agent 框架。
文中用"模型"指代底层大语言模型，用"智能体"指代搭载了工具和指令的 Agent 系统。

---

摘要：本文从 Claude Code 团队的工程实践中提炼出为大模型智能体编写技能指令文件的核心方法论。核心原则是渐进式披露——别一次性把所有信息塞给智能体，让它按需获取、分层展开。文章将指令信息按加载时机分为触发层、主指令层、参考层三层架构，并给出主指令层的六条写作原则（只放每次都需要的内容、给方向不给全文、规则少而精、给示例不给穷举、不要过度约束、保持可演进）。此外还涵盖能力扩展优先用子任务而非加工具、参考层目录组织、上下文获取策略（硬塞式与自主搜索式结合）、常见错误、检查清单及完整示例，帮助读者写出既精简又高效的技能指令文件。

核心原则：渐进式披露（Progressive Disclosure）

一句话：别一次性把所有信息塞给智能体，让它按需获取、分层展开。

这是经过大量工程实践验证的第一原则。你塞得越多，智能体反而越受限；你给得越克制，它发挥得越好。

为什么会这样？因为大模型的注意力和上下文窗口都是有限资源。无关信息不仅占用窗口，还会分散模型的注意力，干扰它做"正事"——这在工程上叫上下文污染。

---

一、信息分层：三层架构

不管你用什么框架，指令信息都应该按"加载时机"分成三层：

层级	加载时机	放什么	建议体量
触发层	每次对话都可见	技能名称 + 一段触发描述	100 词以内
主指令层	技能被激活时加载	核心流程、关键规则、引用入口	等效 500 行以内
参考层	按需读取	详细文档、脚本、模板、示例库	不限

心法：主指令是"作战简报"，不是"百科全书"。只放智能体每次执行都需要知道的内容；其余外置，留一句指引。

在不同框架中的对应关系

本指南的概念	Claude Code	Cursor / Windsurf	Dify / Coze	LangChain / 自研框架
触发层	frontmatter description	.cursorrules 简介	技能卡片描述	tool/skill 的 description 字段
主指令层	SKILL.md 正文	.cursorrules 正文	提示词编排主体	system prompt / instruction
参考层	references/ 目录	项目文档 + @引用	知识库文档	外挂文档 / RAG 检索源

---

二、触发层怎么写

触发描述是智能体决定"要不要启用这个技能"的唯一依据。

要点

• 同时说明"做什么"和"什么时候用"。不要只写功能，要覆盖触发场景和用户可能的措辞方式。
• 包含同义词和关键词变体。用户说"做个 PPT"和"做个演示文稿"和"帮我准备 slides"是同一件事。
• 适当主动。大模型普遍有"不触发"的倾向（宁可不用工具也不用错），所以触发描述可以写得稍微宽泛一点。

示例（差）：

生成周报文档。

示例（好）：

生成周报文档。当用户提到写周报、周总结、weekly report、本周汇报、总结这周工作时触发。即使用户没有明确说"周报"二字，只要意图是汇总近期工作产出，也应触发。

---

三、主指令层怎么写

这是 skill 的核心。以下六条原则是从工程实践中反复验证出来的。

原则 1：只放"每次都需要"的内容，细节外置

问自己：这条信息是不是智能体每次执行这个技能都需要看到的？

• 是 → 放在主指令
• 不是 → 外置到参考文件，在主指令留一句指引

示例：

提交代码前，阅读 references/commit-convention.md 中的详细规范并严格遵守。

智能体真要提交时会自己去读；99% 不需要提交的时候，这些规范不会占用上下文。

在不同框架中的实现方式：

• 有文件系统的 Agent（Claude Code、Cursor 等）：直接引用文件路径
• 知识库型平台（Dify、Coze 等）：把详细文档上传到知识库，在提示词中写"需要时从知识库检索 XXX 相关内容"
• 自研框架：通过 RAG 或工具调用实现按需检索

原则 2：给方向，不给全文

不要替智能体决定它应该看到什么。给它搜索入口和方向，让它自己去挖。

大模型自己清楚自己缺什么信息。它自己找到的内容，能接上它当前的推理链路；你替它硬塞的，它未必能完全理解上下文关联。

差的做法： 把整个 API 文档复制进主指令
好的做法：

API 用法详见 references/api-guide.md。如需查找具体端点，使用搜索工具定位关键词。

原则 3：规则要少而精

Claude Code 团队只有约 20 个工具，还觉得"已经很多了"——每多一个工具，模型每次推理就多一个选项要权衡，决策空间膨胀会降低可靠性。

规则也是一样的道理：

• 核心规则不超过 5-7 条
• 每条规则附上简短的"为什么"，比单纯的"必须"更有效
• 99% 用不到的规则外置到参考文件

差的写法：

必须使用 TypeScript。

好的写法：

使用 TypeScript 编写所有代码，因为项目的类型系统依赖 TS 严格模式来保证接口安全。

解释原因不是多余的废话，它帮助模型理解规则的优先级和适用边界，在遇到规则冲突时做出更合理的判断。

原则 4：给示例，而不是给穷举

一个好的输入输出示例比十条抽象规则更有效。模型从示例中提取的模式比从规则中推导的更稳定。

## 命名规范

示例 1：
输入：添加了用户认证功能
输出：feat(auth): 实现基于 JWT 的用户认证

示例 2：
输入：修复了登录页面的样式问题
输出：fix(ui): 修复登录页按钮对齐问题

原则 5：不要过度约束

这是最隐蔽的坑。Claude Code 团队的切身教训：早期模型能力弱时，他们做了一个待办清单工具并定期插入提醒。后来模型升级了，这个设计反而让智能体变得死板——它觉得必须严格遵守清单，不敢灵活调整。

随着模型能力增强，曾经需要的"辅助轮"可能变成限制它发展的"枷锁"。

避免以下做法：

• 每隔几步插入"别忘了检查 XXX"的提醒
• 把每一步的具体操作都写死——给目标和约束，让智能体自己规划路径
• 强制使用固定的检查清单或流程模板（除非确实是刚性流程）

更好的做法是给目标、给约束、给边界，但把"怎么到达"留给智能体。

原则 6：保持可演进

定期审视你的指令集：

• 三个月前模型需要的辅助手段，现在可能已经是负担
• 模型能力在上升，但你的指令没跟上，指令就会从"辅助"变成"加锁"
• 新模型可能已经内化了你曾经需要显式写明的能力

建议每次底层模型升级后，重新评估一遍现有指令是否仍然必要。

---

四、能力扩展：优先用子任务，而不是加工具

当你想让智能体做更多事情时，本能反应是"加一个工具"。但每多一个工具，模型的决策空间就膨胀一分。

更好的扩展策略（按优先级排序）：

1. 文件引用 / 知识库检索——不加工具、不改指令，通过文档扩展能力
2. 子智能体 / 子任务委托——需要时启动专门的子流程，完成后返回结果，不污染主流程的上下文
3. 延迟加载工具——工具列表里只放一个轻量的入口，智能体需要时通过搜索发现并加载完整的工具定义
4. 真正加一个新工具——只在以上方式都不适用时才考虑

Claude Code 团队的原话概括：我们现在无需添加任何工具，就可以向智能体的操作空间里添加内容。

---

五、参考层怎么组织

推荐的目录结构

your-skill/
├── 主指令文件           # 中枢（必需）
├── references/          # 详细参考文档（按需读取）
│   ├── api-guide.md
│   ├── style-rules.md
│   └── troubleshooting.md
├── scripts/             # 可执行脚本（按需调用）
│   └── validate.py
└── assets/              # 模板、素材等（按需使用）
    └── template.docx

参考文件写作要点

• 超过 300 行的文件，在开头加目录索引
• 按领域拆分文件，不要把所有内容塞进一个大文件
• 主指令中用条件句指引：

  - 如果需要处理 AWS 部署 → 阅读 references/aws.md
  - 如果需要处理 GCP 部署 → 阅读 references/gcp.md
  

对于没有文件系统的平台（如 Dify、Coze），同样的思路可以用知识库分区或多个知识库来实现。

---

六、上下文获取策略

关于怎么让智能体获取它需要的信息，有两种思路：

方式	做法	问题
硬塞式（RAG / 预检索）	预先检索相关内容，塞进上下文	智能体被动接受，检索的未必是它真正需要的
自主搜索式	给智能体搜索工具，让它自己找	它自己知道缺什么，搜到的内容能接上推理链

工程实践的结论：自主搜索式效果更好。

但这不是非此即彼——最佳实践是两者结合：

• 核心上下文（项目简介、技术栈、关键约束）硬塞进去，因为每次都需要
• 细节信息给搜索入口，让智能体按需获取

这也是渐进式披露的体现：第一层硬塞，第二层自取。

---

七、常见错误

把指令写成操作手册
指令文件不是面向人类的文档。人类文档追求完整覆盖；指令文件追求精准命中。写完后问自己：有没有哪段话，删掉之后对智能体的执行效果毫无影响？有的话就删。

所有规则都放在主指令里
99% 场景用不到的规则放在主指令里 = 每次对话都加载 = 上下文污染。

不给引用路径
光说"代码要符合规范"没用，必须指明"代码规范详见 XXX"。智能体需要知道去哪里找。

规则之间互相矛盾
规则越多越容易冲突。如果你写了 20 条规则，大概率有几条是打架的。少即是多。

用复杂的条件逻辑
“如果 A 且 B 但不是 C 的情况下，除非 D 成立……” 这种规则任何模型都难以稳定执行。拆成多个简单的独立规则。

忘了工具也需要演进
三个月前你加的工具或规则，可能因为模型升级已经不再需要了。定期清理，该删就删。

---

八、检查清单

写完指令文件后过一遍：

1. 触发描述是否同时覆盖了"做什么"和"什么时候触发"？
2. 主指令体量是否控制在合理范围内（等效 500 行以内）？
3. 每条规则是否都是"每次执行都需要"的？能外置的是否已外置？
4. 是否给了参考文件的明确路径（或知识库检索关键词）和读取条件？
5. 是否有至少一个示例帮助智能体理解预期输入输出？
6. 是否避免了过度约束（死板步骤、频繁提醒、强制清单）？
7. 参考文件超过 300 行的是否有目录索引？
8. 最近一次底层模型升级后，是否重新评估过指令的必要性？

---

九、完整示例

[触发描述]
生成周报文档。当用户提到写周报、周总结、weekly report、本周汇报时触发。
也适用于用户说"帮我总结这周的工作"等类似表述。

---

# 周报生成

## 概述
根据用户提供的本周工作内容，生成结构化的周报文档。

## 快速参考
| 任务 | 操作 |
|------|------|
| 了解周报格式 | 阅读 references/report-template.md |
| 了解各部门术语 | 阅读 references/terminology.md |

## 核心流程
1. 确认用户本周的关键工作事项（如果用户未提供，主动询问）
2. 阅读 references/report-template.md 了解格式要求
3. 按模板结构组织内容
4. 生成文档并输出

## 关键规则
- 周报语言跟随用户语言（用户用中文就写中文）
- 每个工作事项包含"做了什么"和"结果/进展"两部分
- 总字数控制在 500-1000 字，避免流水账

## 质量检查
生成后检查是否有遗漏的工作事项或格式问题。

这个示例的特点：主指令精简到一眼能看完，细节全部外置，规则只有三条且每条都是每次执行的刚需。

---

最后

给智能体设计指令，既是工程技术，也是一门手艺。不存在一套公式覆盖所有场景。多试、多观察、多迭代，找到适合你的模型和场景的平衡点。

但渐进式披露是目前经过最多工程验证的主线原则——记住这句话就够了：

你塞得越多，智能体反而越受限；你给得越克制，它发挥得越好。