building-skills

构建技能

Agent 技能 是一个包含 SKILL.md 文件的文件夹，可按需教会 Agent 执行某项任务。该格式是一项开放标准（规范），受到许多 Agent 的支持，因此编写的技能应具备可移植性，而非绑定到某款产品。

每次的目标都是让技能比之前更精简、更清晰、更实用。技能会被读取数千次，却只编写一次——每个词元都必须物有所值。

技能如何加载（渐进式披露）

┌──────────────┐ always loaded ┌───────────────────────────────────────┐
│ 1. metadata  │──────────────▶│ name + description (~100 tokens)      │
└──────────────┘               │ the only input used for triggering    │
                               └───────────────────────────────────────┘
┌──────────────┐   on trigger  ┌───────────────────────────────────────┐
│ 2. SKILL.md  │──────────────▶│ body instructions (aim < 500 lines)   │
└──────────────┘               └───────────────────────────────────────┘
┌──────────────┐   as needed   ┌───────────────────────────────────────┐
│ 3. resources │──────────────▶│ scripts/, references/, assets/        │
└──────────────┘               └───────────────────────────────────────┘

把每项内容放在能发挥作用的最低成本层级：在描述中提供触发线索，在正文中说明核心工作流，并将繁琐细节放在 Agent 仅在需要时才会读取的资源中。

Frontmatter

YAML frontmatter，后接 Markdown。只有 name 和 description 是必填项。

字段	必填	约束
name	是	≤ 64 个字符；仅限小写 a-z、0-9 和连字符；不得以连字符开头或结尾，也不得包含连续连字符；必须与文件夹名称相同
description	是	≤ 1024 个字符（应远短于此）；说明其功能以及适用时机
license	否	许可证名称或文件引用（本仓库使用 MIT）
compatibility	否	≤ 500 个字符；仅在技能需要特定工具、运行时或网络时填写
metadata	否	任意字符串键值映射
allowed-tools	否	以空格分隔的预先批准工具（实验性）

大多数技能只需要 name、description 和 license。不要臆测性地添加字段。

名称

根据技能的用途选择名称形式：

• 特定工具 → 使用工具名称：gh-cli、sourcegraph-cli、miro-mcp。当命名空间有助于明确触发条件时，按工具划分命名空间（gh-address-comments）。
• 可重复的任务、工作流或广泛操作 → 使用动名词形式（动词 + -ing）：building-skills、writing-issues-and-prs、managing-deployments。

无论哪种形式，名称都应简短并使用连字符，避免使用 helper、utils、tools 这类含糊的名称。

描述——触发条件

这是 Agent 决定是否使用技能时唯一能看到的文本，因此所有“何时使用”的信息都应写在这里；不要把这些信息放在正文中。说明技能做什么，以及应在什么具体情境或短语下调用，并使用具体关键词以便发现技能。当能力概述以动词开头时，使用第三人称单数；给 Agent 的指令（包括何时加载技能）使用祈使语气。如果值中包含冒号或其他 YAML 特殊字符，请将其加引号。

• 好：Uses GitHub CLI (gh) for GitHub repositories, issues, pull requests, actions, releases, gists, and API calls. Use when a task requires GitHub operations from the command line.
• 差：Helps with code.（含糊，没有触发条件）

如果技能触发不够频繁，应让描述更明确地指出触发情境，而不是在正文中添加规则。

核心原则

• 简洁为要。 假定 Agent 已经足够聪明。只补充它尚不知道的内容——不明显的步骤、领域事实、项目约定。审视每一行：它值得占用这些词元吗？删掉引言、总结和对常识的解释。
• 说明原因，而不只是做法。 简短的理由能帮助能力出众的 Agent 将方法推广到未预见的情况。将生硬的 ALWAYS/NEVER 规则改写为背后的原因；只有在步骤确实脆弱、容易出错时才使用硬性约束。
• 自由度应与脆弱程度相匹配。 任务开放且有多种有效路径 → 使用高层次说明。存在首选模式 → 使用伪代码或可参数化的示例。步骤脆弱且出错代价高 → 使用选择少、精确的脚本。
• 概括，而非过度拟合。 技能必须适用于未来的多种提示，而不仅是眼前的示例。优先采用经久耐用的模式，而不是特殊处理。
• 使用祈使语气。 直接向 Agent 发出指令（“运行 X”“先阅读 Y”），而非叙述。

结构

skill-name/
├── SKILL.md      # Required: frontmatter + instructions
├── scripts/      # Executable code for deterministic or repeated work
├── references/   # Docs the agent reads on demand (schemas, APIs, deep guides)
└── assets/       # Files used in output (templates, icons, fonts)

• scripts/ — 如果 Agent 每次运行都会重写相同的代码，或者某个步骤需要确定可靠性，就使用此目录。明确说明用途，例如：“运行 scripts/validate.py 检查 frontmatter。”通过实际运行来测试脚本。
• references/ — 将详细材料移到此处，让 SKILL.md 保持精简。在 SKILL.md 中引用每个文件，并说明何时阅读。引用层级保持为一层。
• assets/ — 存放会复制到输出中或在输出中使用的资源，而不是加载到上下文中的资源。

不要添加 README.md、CHANGELOG.md、安装指南或关于如何制作此 skill 的说明。一个 skill 只包含 Agent 完成任务所需的内容。

工作流

1. 理解任务。 获取具体示例：它应该实现什么功能、哪些短语应该触发它、预期输出是什么？将已完成的对话转化为 skill 时，提取已经发生的步骤、工具使用和修正。
2. 规划资源。 针对每个示例，思考什么脚本、参考资料或资源能帮助 Agent 反复完成任务。先列出它们，再开始编写。
3. 起草 SKILL.md。 编写 frontmatter（确保描述准确），然后编写正文：一句话摘要、工作流和具体示例。如果需要资源，先构建资源。
4. 拆分内容。 如果正文超过约 500 行，或涵盖多个变体／领域，就将核心工作流和选择逻辑保留在 SKILL.md 中，并将其余内容移到 references/（每个变体一个文件）。
5. 验证。 检查 frontmatter 和命名规则。然后重新通读整个 skill，确保内容一致：术语、标题样式和格式统一；各章节之间以及 SKILL.md 与参考资料之间没有重复内容——每条信息都应只在一个位置出现。
6. 根据实际使用迭代。 使用 skill，观察 Agent 遇到困难或浪费步骤的地方，并加以改进。如果每次运行都要重新编写相同的辅助工具，就将其打包成脚本。以全新的视角重新审阅草稿并精简。

编辑现有 skill 时

先完整阅读，并保留其 name 和文件夹。让内容更短、更清晰：删除无用内容，将僵化规则改为推理引导，增强描述的触发条件，并将细节移至参考资料。遵循周围内容的风格。优先采用能改善内容的最小改动，其余部分保持不变。