create-skill

创建技能

此技能可帮助你搭建符合 Agent Skills 规范和 dotnet/skills 仓库约定的新 Agent 技能。

适用场景

• 从头创建新技能
• 生成带有适当前置元数据的 SKILL.md 文件
• 设置技能目录结构和可选文件夹
• 确保符合 agentskills.io 规范

不适用场景

• 修改现有技能（直接编辑即可）
• 诊断或修复评估未通过的技能（使用 improve-skill-quality）
• 编写技能的 eval.yaml（使用 create-skill-test）
• 创建自定义 Agent（使用 agents/ 目录模式）

输入

输入	必填	说明
技能名称	是	仅限小写字母、数字和连字符（例如，code-review、ci-triage）
描述	是	说明技能的功能，以及 Agent 应在何时使用它（1-1024 个字符）
目的	是	用一段话描述预期结果
工作流步骤	建议填写	Agent 应遵循的编号步骤

工作流

步骤 1：验证技能名称

确保名称：

• 仅包含小写字母、数字和连字符
• 不以连字符开头或结尾
• 不包含连续连字符
• 长度为 1-64 个字符

步骤 2：编写描述——它是路由器

运行时在决定是否加载技能时，只会看到 description 中的文本。 正文再完美，如果描述写得含糊，也不会被调用。

---
name: <skill-name>
description: <what it does>. USE FOR: <symptoms, error codes, artifact names, quoted user requests>. DO NOT USE FOR: <nearby-but-wrong intents, with the skill that owns them>.
---

• 以动作动词开头，并使用用户自己的措辞：症状、错误代码（CS1501、 MSTEST0014）、产物名称（.testsettings、binlog），以及开发者通常会输入的请求。
• 根据真正的区分因素，而不是主题，与相邻技能划分范围。“这种抽象是否已经存在？”可以区分两种技能；“测试”则不行。将相应的排除项添加到两个相邻技能中。
• 明确涵盖那些可能会被路由到相邻技能的模糊词。如果用户会说“审查我的测试”，而相邻技能负责“审查”，就要明确说明。
• 检查每条 DO NOT USE FOR 条款是否会排除该技能旨在处理的场景——例如，“已升级到 v3”的排除项可能会挡住该技能本来要处理的升级后修复场景。
• 字数预算：每条描述最多 1,024 个字符，整个插件渲染后的技能菜单也有字数限制。帮助程序或参考目录可以设置 disable-model-invocation: true，以释放菜单空间。它仍是可读资源，但模型无法按名称调用它。使用者会通过提供的目录路径（原生评估中的暂存路径）直接读取目录或其捆绑文件。应相对于目录解析捆绑文件路径，而不是相对于项目工作区。
• 不要使用 XML 标签。Claude（claude.ai 和 Claude Code 市场同步）会拒绝包含类似标签文本的描述，例如 Vector<T> 或 <Import>。请用文字表达（“泛型 Vector 类型”、“Import 元素”）；skill-validator check 会因此失败。

步骤 3：围绕基线模型的增量编写

每项技能都会与同一个未加载任何技能的模型进行正面对比评分。模型无需帮助就能生成的内容价值为零；会让模型变得更慢或更谨慎的内容，价值低于零。完整证据请参阅 improve-skill-quality/references/writing-for-baseline-delta.md。

应做	而非
编码模型原本会做错的决策	重述模型已经能复现的 API 签名
使用“When A, do B, never C, verify D”表格	列出看似可行的替代方案
定义具体的输出契约（精确命令、结论行、结果表）	使用“考虑……”“你可能想要……”
让输出结构与输入规模相匹配	为包含 8 个测试的套件制作 12 个章节的仪表板
设置停止条件，避免过度应用	未经测量就采取行动，重写可用代码
指示 Agent 查找仓库路径	将可查找到的路径标为必需输入
如实报告还原、构建或测试失败	命令失败后仍声称成功
通过编译或探测验证关键 API 声明	仅凭阅读源码就认定正确
将罕见或开销较大的路径置于 references/ 中	用一个大型 SKILL.md 覆盖所有路径

不要矫枉过正：如果答案比基线更短，却也更缺乏可操作性，仍然会失分。

步骤 4：创建技能目录

plugins/<plugin>/skills/<skill-name>/
└── SKILL.md

步骤 5：生成带 frontmatter 的 SKILL.md

使用步骤 2 中拟定的 frontmatter 创建该文件。

步骤 6：添加正文部分

建议包含以下部分：

1. 用途：用一段话描述预期结果
2. 适用场景：列出适用情形
3. 不适用场景：说明边界和排除项
4. 输入：列出必需和可选输入的表格
5. 工作流：包含检查点的编号步骤
6. 验证：说明如何确认技能正常工作
7. 常见陷阱：列出已知问题及避免方法

步骤 7：按需添加可选目录

plugins/<plugin>/skills/<skill-name>/
├── SKILL.md
├── scripts/       # Executable code agents can run
├── references/    # Additional documentation loaded on demand
└── assets/        # Templates, images, data files

使用相对于 SKILL.md 所在目录的路径引用捆绑文件，例如 references/details.md 或 scripts/validate.ps1。不要指示 Agent 搜索技能的安装目录。如果缺少捆绑文件会降低结果质量，可允许列出已知的捆绑文件目录一次，并要求 Agent 报告覆盖范围有所降低。

步骤 8：更新 CODEOWNERS

在 .github/CODEOWNERS 中为新技能及其测试目录添加条目：

/plugins/<plugin>/skills/<skill-name>/  @owner-team
/tests/<plugin>/<skill-name>/           @owner-team

使用同一插件中同级技能所采用的所有者模式。

步骤 9：验证技能

• 确认 frontmatter 字段有效
• 确保 SKILL.md 少于 500 行
• 检查文件引用是否使用相对路径
• 验证指令是否具体且可操作
• 运行 dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin>

步骤 10：添加评估

没有 eval.yaml 的技能无法证明其效果优于基线。使用 create-skill-test 在同一个拉取请求中添加评估，并确保规模足以获得统计效力——少于 5 个不同刺激项的评估永远无法得出通过结论。

例外情况是带有 disable-model-invocation: true 的辅助工具或参考目录：模型无法调用它，因此直接评估只会比较两个完全相同的组。应通过读取其资源的使用方技能的结果评估来覆盖它。

SKILL.md 模板

创建新技能时请使用此模板：

---
name: <skill-name>
description: <1-1024 char description of what the skill does and when to use it>
---

# <Skill Title>

<One paragraph describing the skill's purpose and outcome.>

## When to Use

- <Scenario 1>
- <Scenario 2>

## When Not to Use

- <Exclusion 1>
- <Exclusion 2>

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| <input-name> | Yes/No | <description> |

## Workflow

### Step 1: <Action>

<Instructions for this step>

### Step 2: <Action>

<Instructions for this step>

## Validation

- [ ] <Verification step 1>
- [ ] <Verification step 2>

## Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| <Problem> | <How to avoid or fix> |

验证清单

创建技能后，请验证：

• 技能名称与目录名称完全一致
• 技能名称仅包含小写字母和连字符
• 描述非空且少于 1024 个字符
• 描述不包含类似 XML 的标签（例如 Vector<T>）
• SKILL.md 正文少于 500 行
• 说明具体且可执行
• 捆绑文件的路径相对于包含 SKILL.md 的目录
• 捆绑文件缺失时不会导致功能静默降级
• 工作流包含带有明确检查点的编号步骤
• 存在验证部分，且包含可观察的成功标准
• 不包含机密、令牌或内部 URL
• .github/CODEOWNERS 中为新技能及其测试目录添加了条目
• 描述列出具体触发条件，并排除最相近的同级技能
• 每个部分都会改变未掌握该技能的模型原本会做错的决策
• 技能说明了何时不应采取行动，以及真实可信的失败报告应是什么样
• 存在 eval.yaml，且达到不同刺激项的最低要求（否则，该技能必须设置 disable-model-invocation: true，并通过其使用方进行覆盖）

常见陷阱

陷阱	解决方案
名称包含大写字母	仅使用小写字母：code-review，不要用 Code-Review
描述含糊不清	说明它的作用以及适用时机
说明模棱两可	使用包含具体操作的编号步骤
缺少验证步骤	添加用于验证成功的检查点
SKILL.md 过长	将详细内容移至 references/ 文件
对环境的假设写死在文档中	在 compatibility 字段中注明要求
缺少 CODEOWNERS 条目	为 /plugins/<plugin>/skills/<skill-name>/ 和 /tests/<plugin>/<skill-name>/ 添加条目，并匹配同级技能的所有者模式
技能重述模型已经知道的内容	删除这些内容；技能的评分依据是它相对于未掌握该技能的模型带来的提升
将可发现的路径列为必需输入	告诉 Agent 去发现这些路径，否则它会停下来询问用户
按主题而不是实际区别与同级技能划分描述	按真实的区分标准划分，并在两侧都明确排除
排除条款阻止了技能自身适用的场景	针对真实工作流阶段，重新审视每条“不要用于”条款
添加技能时未添加评估	在同一个 PR 中添加 eval.yaml；未经评估的技能没有证据支撑

参考资料

• Agent Skills 规范
• 仓库 README
• 贡献指南
• create-skill-test — 编写技能的 eval.yaml
• improve-skill-quality — 修复表现不如基线的技能