name: skill-creator description: 创建新代理技能，遵循代理技能规范。当被要求“创建技能”、“添加新技能”、“编写技能”、“制作技能”、“构建技能”或搭建新技能与SKILL.md时使用。引导需求规划、编写、注册和验证。

<!– 改编自Anthropic和OpenAI的技能创建器实现： https://github.com/anthropics/skills/tree/main/skills/skill-creator https://github.com/openai/skills/tree/main/skills/.system/skill-creator

参考：

代理技能规范：https://agentskills.io/specification
技能编写最佳实践：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
验证库：https://github.com/agentskills/agentskills/tree/main/skills-ref –>

创建新技能

指导用户创建新的代理技能，遵循代理技能规范。按顺序遵循每个步骤。

步骤1：理解技能

在编写之前收集需求。

询问用户：

这个技能应该做什么？（一句话）
代理应该在什么时候使用它？（用户会说的触发短语）
技能需要什么工具？（读取、Grep、Glob、Bash、Task、WebFetch等）
技能应该放在哪里？（哪个插件或目录）

确定技能名称：

仅使用小写字母、数字和连字符（a-z, 0-9, -）
1-64个字符；不能以-开头或结尾；没有连续连字符（--）
描述性且在现有技能中唯一
更喜欢动作导向的名称：processing-pdfs, fix-issue, code-review
检查目标技能目录以避免名称冲突

选择复杂性层级：

层级	结构	使用时机
简单	仅`SKILL.md`	自包含指令，约200行以下
带参考	`SKILL.md` + `references/`	需要代理有条件加载的领域知识
带脚本	`SKILL.md` + `scripts/`	需要Python脚本的工作流自动化
完整	以上全部	具有自动化和领域知识的复杂技能

阅读${CLAUDE_SKILL_ROOT}/references/design-principles.md获取保持技能专注和简洁的指导。

步骤2：规划技能

分析每个用例从头开始执行的方式。确定在执行这些任务重复时什么可重用资源会有帮助。

对于每个具体示例，询问：

每次重写的代码是什么？→ 候选用于scripts/
需要什么文档来告知决策？→ 候选用于references/
输出中使用的模板或资产是什么？→ 候选用于assets/

示例分析：

“旋转PDF” → 旋转需要重写相同代码 → scripts/rotate_pdf.py
“查询BigQuery指标” → 每次都需要表结构 → references/schema.md
“构建前端应用” → 相同的样板HTML/React → assets/hello-world/

步骤3：研究现有技能

在编写之前，研究1-2个匹配所选层级的现有技能。查看目标仓库或插件中的技能以理解本地约定。

阅读${CLAUDE_SKILL_ROOT}/references/skill-patterns.md获取每个层级的具体示例。

同时阅读仓库根目录的CLAUDE.md（或AGENTS.md），以获取技能应遵循的仓库特定约定。

步骤4：编写SKILL.md

创建<skill-directory>/<name>/SKILL.md。

前置数据

YAML前置数据必须是文件中的第一项。在---之前没有注释或空白行。

---
name: <skill-name>
description: <它做什么>。使用当<触发短语>。<关键能力>。
---

必填字段：

name — 必须与目录名完全匹配
description — 最多1024个字符，没有尖括号（<或>）；包括帮助代理匹配用户意图的触发关键词

可选字段：

allowed-tools — 逗号分隔的列表（例如，Read, Grep, Glob, Bash）；省略以允许所有工具
license — 许可证名称或路径（当包含外部内容时添加）
metadata — 用于额外元数据的任意键值映射
compatibility — 环境要求（最多500字符）；大多数技能不需要这个

对于Claude Code特定字段（argument-hint, disable-model-invocation, context等），阅读${CLAUDE_SKILL_ROOT}/references/claude-code-extensions.md。

描述指南

描述是主要触发机制 — 它决定代理何时激活技能。所有“使用时机”信息属于这里，不在正文中。

用第三人称写：

好：“处理Excel文件并生成报告。使用当…”
坏：“我可以帮你处理Excel文件”或“你可以用这个来…”

包括自然触发短语：

# 好 — 用户实际会说的具体触发
description: 安全代码审查漏洞。使用当被要求“安全审查”、“查找漏洞”、“检查安全问题”、“审计安全”。

# 坏 — 太模糊，没有触发短语
description: 用于代码质量的有用技能。

模式： <它做什么>。使用当<触发短语>。<关键能力>。

正文指南

用命令语气写正文 — 这些是指令，不是文档。

做	不做
“读取文件并提取…”	“这个技能读取文件并提取…”
“仅报告高置信度发现”	“代理应该仅报告高置信度发现”
“询问用户使用哪个选项”	“你可能想问用户…”

结构：

以技能做什么的一行摘要开始
用## 步骤 N: 标题标题组织步骤
使用表格进行决策逻辑和映射
包括预期输出的具体示例
以验证标准或退出条件结束

对于工作流和输出模式，阅读：

${CLAUDE_SKILL_ROOT}/references/workflow-patterns.md — 顺序工作流、反馈循环、计划-验证-执行
${CLAUDE_SKILL_ROOT}/references/output-patterns.md — 模板、示例和结构化数据模式

大小限制：

保持SKILL.md在500行以下（推荐< 5000标记）
如果接近限制，将参考材料移到references/文件
根据上下文有条件加载参考文件（不一次全部加载）

使用一致的术语 — 为每个概念选择一个术语并贯穿始终。不要在“API端点”、“URL”、“路由”和“路径”之间交替。

归因

如果技能基于或改编自外部来源，在前置数据关闭---后添加HTML注释：

---
name: example
description: ...
---

<!--
基于[原名称]由[作者/组织]：
https://github.com/example/original-source
-->

步骤5：创建支持文件

包括什么

仅包括直接支持技能功能的文件。

不包括什么

不要创建多余的文档或辅助文件：

README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md

技能应只包含代理做工作所需的内容。不是设置过程，不是面向用户的文档，不是开发历史。

参考（`references/`）

用于代理有条件加载的领域知识。

<name>/
├── SKILL.md
└── references/
    ├── topic-a.md
    └── topic-b.md

从SKILL.md引用：

阅读`${CLAUDE_SKILL_ROOT}/references/topic-a.md`获取[主题]的详细信息。

指南：

保持每个参考文件专注于一个主题
保持参考一级深从SKILL.md（没有嵌套引用链）
对于超过100行的文件，在顶部添加目录
对于超过10k单词的文件，在SKILL.md中包括grep搜索模式
信息应住在SKILL.md或参考中，不是两者

脚本（`scripts/`）

用于受益于结构化Python的工作流自动化。

<name>/
├── SKILL.md
└── scripts/
    └── do_thing.py

脚本要求：

总是使用uv run执行：uv run ${CLAUDE_SKILL_ROOT}/scripts/do_thing.py
为依赖添加PEP 723内联元数据：

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

输出结构化JSON供代理消费
从仓库根目录运行，不是技能目录
在SKILL.md中记录脚本接口（参数、输出格式）
明确处理错误 — 不要推给代理

资产（`assets/`）

用于技能输出中使用的静态文件（模板、图像、样板代码、字体）。这些不加载到上下文中 — 它们被复制或直接使用。

LICENSE

当包含具有特定许可要求的内容时，在技能目录中包含LICENSE文件。

步骤6：验证技能

运行验证脚本以早期捕获问题：

uv run ${CLAUDE_SKILL_ROOT}/scripts/quick_validate.py <path/to/skill-directory>

脚本检查前置数据格式、必填字段、命名规则和常见错误。修复任何错误并重新运行直到验证通过。

或者，使用上游验证工具：

skills-ref validate <path/to/skill-directory>

步骤7：注册技能

注册步骤因仓库而异。检查仓库的CLAUDE.md或README.md获取具体说明。

验证目录名匹配 — 确认目录名与SKILL.md前置数据中的name字段完全匹配
更新文档 — 在README.md中任何技能索引或表中添加技能
更新权限 — 如果仓库有.claude/settings.json，添加Skill(<plugin>:<name>)到permissions.allow数组
检查CLAUDE.md — 阅读仓库的CLAUDE.md，获取该项目的任何额外注册步骤

步骤8：验证

完成前运行此检查清单：

前置数据

[ ] name 匹配目录名
[ ] name 仅使用小写字母、数字、连字符（没有前导/尾随/连续连字符）
[ ] description 在1024个字符以下，没有尖括号
[ ] description 用第三人称，包括触发关键词
[ ] 所有“使用时机”信息在描述中，不在正文中
[ ] ---之前没有内容

内容

[ ] SKILL.md在500行以下
[ ] 用命令语气写
[ ] 步骤编号清晰
[ ] 包括预期输出的示例
[ ] 术语一致贯穿
[ ] 参考文件有条件加载（不无条件）
[ ] 没有多余文件（README.md, CHANGELOG.md等）

注册

[ ] 目录名匹配前置数据name
[ ] 技能添加到仓库文档（README或等效）
[ ] 权限更新（如果适用）
[ ] 任何仓库特定注册步骤完成（检查CLAUDE.md）

脚本（如果适用）

[ ] 使用uv run ${CLAUDE_SKILL_ROOT}/scripts/...
[ ] 有PEP 723内联元数据
[ ] 输出结构化JSON
[ ] 明确处理错误
[ ] 在SKILL.md中记录

验证

[ ] uv run ${CLAUDE_SKILL_ROOT}/scripts/quick_validate.py通过
[ ] 使用真实使用场景测试

报告发现的任何问题，并在完成前修复它们。

name: skill-creator description: 创建新代理技能，遵循代理技能规范。当被要求“创建技能”、“添加新技能”、“编写技能”、“制作技能”、“构建技能”或搭建新技能与SKILL.md时使用。引导需求规划、编写、注册和验证。

创建新技能

步骤1：理解技能

步骤2：规划技能

步骤3：研究现有技能

步骤4：编写SKILL.md

前置数据

描述指南

正文指南

归因

步骤5：创建支持文件

包括什么

不包括什么

参考（references/）

脚本（scripts/）

资产（assets/）

LICENSE

步骤6：验证技能

步骤7：注册技能

步骤8：验证

前置数据

内容

注册

脚本（如果适用）

验证

参考（`references/`）

脚本（`scripts/`）

资产（`assets/`）