SNNN-011/skill-authoring

技能创作指南

创建真正能改变 Agent 行为技能的指南，而不是那些永远不会被读取的文档。

核心原则：技能是操作指令，不是文章。 如果加载此技能后 Agent 的行为没有不同，那么这个技能就是失败的。

如何使用此技能

此技能通过对话方式使用，而非一次性完成。流程如下：

1. 用户触发技能（例如：“使用技能 skill-authoring，我想为我的 Agent 创建一个技能”）。
2. Agent 停止写作，开始进行步骤 1 的访谈：每次只问一个问题，等待回答。
3. 五个问题都回答完毕后，Agent 执行步骤 2 到步骤 5，并向用户展示草稿。
4. 用户同意后，Agent 写入文件（步骤 6），然后运行触发测试（步骤 7）和检查清单（步骤 8）。

Agent 的规则：

• 在步骤 1 的五个问题都回答完毕之前，不要编写 SKILL.md。过早的草稿会中断访谈。
• 不要同时提出所有五个问题。每次只问一个，并在每个问题中附带简短示例。
• 如果用户只想要“快速示例”，至少也要问问题 1 和问题 4，然后再继续。
• 在开始时说明，最终结果是一个可以直接使用的 SKILL.md 文件。

此技能何时激活

• 用户说“创建一个技能”、“制作技能”、“如何创建技能”、“为我的 Agent 创建技能”。
• 用户有 Agent 能力的想法，但不知道如何表达。
• 已有的技能从未被触发过，或者 Agent 不遵循它。
• 需要决定：这应该是技能、Agent、命令还是钩子？

要搜索已有技能，请先使用 skill-scout。要审计已积累的技能，请使用 skill-stocktake。

步骤 0 - 编写前的基本规则

一个好的技能应具备四个特性：

特性	含义
具体	解决一种特定任务，而不是“所有关于后端的事情”
可操作	包含步骤、命令、真实示例，而非理论
可触发	description 包含用户实际会使用的词语
有限制	少于 500 行；理想情况下为 100-250 行

如果技能想法不满足这四个条件，先改进想法，而不是编写文件。

步骤 1 - 捕捉实际问题，而非功能

不要从“用于测试的技能”开始。从具体的失败案例开始。

向用户提出这五个问题（一次一个，不要同时提出）：

1. Agent 现在做错了什么或做得不一致？给我一个具体的例子。
2. 这种情况发生在什么时候？（编写代码、审查 PR、部署、回答用户问题、分析数据）
3. 正确的结果是什么样的？展示一个你认为好的输出示例。
4. Agent 不知道哪些信息，需要通过此技能告诉它？（团队约定、步骤顺序、陷阱）
5. 在执行此技能时，Agent 不应该做什么？

问题 4 和问题 5 的答案就是技能的实际内容。问题 1 和问题 2 的答案是 description 的内容。

如果用户无法回答问题 1，则中止过程。暂无需要创建的技能——只有愿望。直接说明这一点。

步骤 2 - 选择正确的形式

不要把所有东西都做成技能。选择能解决问题的最简单形式。

需求	形式	原因
编写代码时反复使用的知识/约定	技能	自动加载，无需调用
需要独立上下文的多步骤工作	Agent	可并行运行，拥有自己的上下文
用户有意识地使用参数触发的操作	命令	/{名称} 显式调用，非自动
事件触发时的自动行为（提交前、编辑后）	钩子	无需模型决策即可运行
适用于所有工作的简短规则	规则	始终激活，无需触发
供人类阅读的长篇解释	文档	无需 Agent 加载

经验法则：

• 需要触发？技能。
• 需要独立上下文或受限工具？Agent。
• 需要手动传入参数调用？命令。
• 需要在未被要求时运行？钩子。
• 需要始终正确，永不违反？规则。
• 需要供人类阅读，而非 Agent？文档。

如果在技能和规则之间犹豫不决：如果内容少于 10 行且适用于所有地方，那就是规则。

步骤 3 - 先查找重复项

在编写之前，先进行搜索。不同平台的技能文件夹不同——根据用户的平台进行调整：

平台	技能文件夹
Claude Code	~/.claude/skills/ 或项目内的 .claude/skills/
OpenCode	~/.config/opencode/skills/ 或 .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# 已安装的技能（根据上表替换 <skill-folder>）
grep -ril "关键词" <skill-folder> --include=SKILL.md

# 如果你在包含 skills/ 文件夹的仓库中
grep -ril "关键词" skills --include=SKILL.md

如果用户不知道他们的技能文件夹，解释上表并让他们选择使用的平台。不要猜测。

如果存在接近的匹配项，决定：直接使用，扩展现有技能，还是创建新的。重复的技能会使 Agent 在选择时感到困惑，并增加上下文负担。

步骤 4 - 编写 description（最关键的部分）

description 是 Agent 决定是否加载技能时唯一会读取的部分。如果这里错了，技能就等于死了。

公式：

[执行的活动] + [触发上下文] + [用户使用的关键词] + [何时不使用]

错误示例：

description: 帮助进行测试

正确示例：

description: 使用 Vitest 和 Testing Library 进行 React 测试的模式 - 渲染、用户事件、网络 mock 和可访问性断言。在编写或修复 React 组件测试时使用。不适用于 E2E 测试（请使用 e2e-testing）。

规则：

• 使用用户实际会输入的词语，而不是内部术语。
• 注明边界，以免技能侵占其他技能的工作。
• 单行，字符串内无换行符。
• 避免使用“代码”、“帮助”、“各种”等单一泛词。

快速测试：关闭文件，只阅读 description。如果你作为 Agent 都不清楚何时应该加载它，那就重写。

步骤 5 - 组织内容

经过验证有效的各部分顺序：

---
name: 技能名称
description: <步骤 4 的公式>
metadata:
  origin: ECC
---

# 标题

一个段落：此技能将改变 Agent 行为的哪些方面。

## 何时激活
具体的触发条件列表。

## 核心内容
工作步骤、决策表或规则。这占技能内容的 70%。

## 示例
一个错误示例，一个正确示例。必须是真实的，而不是占位符。

## 反模式
应避免的错误，附带简短理由。

## 检查清单
可验证的复选框。

## 相关技能
两到四个技能名称。

内容编写规则：

• 使用命令式语句（“执行 X”），而不是被动描述（“X 可以被执行”）。
• 决策用表格，步骤用编号列表，命令用代码块。
• 每条规则必须可验证——“编写干净的代码”是不可验证的，“函数最多 50 行”是可验证的。
• 在 Agent 会执行的部分中，不要出现 [在此处填写]、TODO 或 ... 这样的占位符。
• 不要原样复制外部产品的身份标识——提取其思想，用自己的上下文重写。
• 不要包含机密信息：API 密钥、令牌、绝对私人路径、公司内部名称。

长度限制：500 行（硬上限 800）。如果超过，拆分成两个技能或将详细信息移至同一技能文件夹下的 references/。

步骤 6 - 写入文件

在写入之前，询问最后两件事：

1. 技能语言 - 用户日常使用的语言，还是为了可移植性使用英文？遵循用户的回答，不要随意选择。
2. 文件夹名称 - 提出一个描述性的 kebab-case 名称（例如：test-komponen-react），请求批准。

然后写入 <skill-folder>/<名称>/SKILL.md。不允许违反的规则：

• Frontmatter 中的 name: 必须与文件夹名称完全一致。否则，某些平台会拒绝加载技能。
• 先向用户展示完整的草稿，然后再保存。不要悄悄保存。
• 在 Agent 将执行的部分，不能有占位符（TODO、[在此处填写]、...）。
• 保存后，报告完整路径并用一句话说明如何触发：“在此之后，当 <触发条件> 发生时，要求 Agent 使用技能 <名称>。”

步骤 7 - 使用前进行测试

至少三个测试。不要跳过任何一个。

测试 1 - 正向触发（激活） 给 Agent 一个应该触发此技能的任务，但不要提及技能名称。

“请为 LoginButton 组件编写测试。”

如果技能被加载，则通过。如果失败，说明 description 缺少关键词。

测试 2 - 负向触发（不激活） 给出一个相似但不属于其领域的任务。

“请为登录流程编写 E2E 测试。”

如果技能未被加载（或者 Agent 选择了其他合适的技能），则通过。如果失败，说明 description 范围过广。

测试 3 - 执行 要求 Agent 执行一个能真正触发技能的任务，然后对比有技能和无技能时的输出。

无技能：Agent 编写了风格 X 的测试
有技能：Agent 编写了风格 Y 的测试（符合团队约定）

如果能展示出行为上的差异，则通过。如果输出相同，则技能无用——删除或合并。

步骤 8 - 发布检查清单

• 文件位于 <skill-folder>/{名称}/SKILL.md，且 name: 与文件夹名称完全一致
• description 为单行，包含用户的关键词和范围边界
• description 不使用块状字面量（|），仅使用内联字符串
• 包含明确的“何时激活”部分
• 每条规则都可验证，没有“编写好的代码”这类内容
• 至少有一个错误示例和一个正确示例
• 包含反模式
• 少于 500 行
• 不包含秘密、令牌或绝对私人路径
• 已执行测试 1、2、3，并记录了结果
• 已执行步骤 3，没有重复项
• 在末尾列出了 2-4 个相关技能

只有在用户仓库中确实可用时才进行自动验证：

# ECC / 包含技能验证器的仓库
node scripts/ci/validate-skills.js

如果没有验证器，手动检查最容易失败的四个点：name: 与文件夹匹配，description 为单行，行数少于 500，没有占位符。告知用户使用的是这种手动检查方法。

即用模板

---
name: 技能名称
description: <活动> - <范围>。当 <具体触发条件> 时使用。不适用于 <超出范围>。
metadata:
  origin: ECC
---

# 技能名称

加载此技能后 Agent 行为的变化。

## 何时激活
- <触发条件 1>
- <触发条件 2>

## 步骤
1. <可以直接执行的第一步>
2. <第二步>
3. <验证>

## 示例
错误：<经常出现的代码或回答>
正确：<期望的版本，附带简短理由>

## 反模式
- <错误> - <为什么不好>

## 检查清单
- [ ] <机器或眼睛可以检查的内容>

## 相关技能
- `<技能-a>`、`<技能-b>`

反模式（创作方面）

• 无触发条件的技能。 description 模糊不清，技能永远不会被加载。这是最常见的失败原因。
• 文本墙式技能。 900 行理论，没有一个命令。Agent 加载了它，然后忽略它。
• “乐于助人”式技能。 没有具体知识，结果与没有技能时完全相同。
• 重复技能。 两个技能声称拥有相同领域；Agent 随机选择。
• 完整复制他人的技能。 包括隐藏指令和你未曾意识到的依赖项。
• 包含机密或私人路径的技能。 在技能被共享时跟着扩散。
• 为一次性事件编写技能。 如果只使用一次，那它就不是技能——它是文档或命令。
• 在搜索之前创建技能。 始终执行步骤 3。

何时不需要创建技能

如果符合以下任一情况，请直接告诉用户：

• 问题是代码中的 bug，而不是 Agent 知识不足。
• 只需要运行一次——直接给指令即可。
• 内容少于 10 行的通用规则——那是规则。
• 只需添加到项目的 AGENTS.md 或 CLAUDE.md 中即可。
• 已有技能覆盖了 80% 的需求——扩展现有技能。

相关技能

• skill-scout - 在创建新技能之前搜索已有技能
• skill-stocktake - 审计已积累的技能质量
• skill-comply - 衡量技能是否真的被 Agent 遵循
• agent-harness-construction - 设计 Agent 的工具和操作边界