skill-creator

技能编写

编写技能，使其在恰当的时机加载、教授模型尚不了解的内容，并验证自身成果。

适用时机

在以下情况触发：

• 用户创建技能目录，或要求改进、审查或拆分现有技能。
• 某项技能触发过于频繁、过少，或与同级技能冲突。
• bun run lint-skills 失败，或需要在插件或 marketplace 中注册技能。
• 用户想对某项技能进行 skillgrade 评测。

以下情况不要使用：

• 用户正在编写应用文档、README、变更日志或营销文案。
• 用户正在编辑并非技能的库或插件源代码。

参考索引

只有当主题涉及某个参考文件时才加载它。

文件	加载时机
references/repo-layout.md	在此仓库中添加、重命名或注册技能、镜像到 plugins/，或查看 lint 错误时
references/authoring-patterns.md	编写正文时：触发设计、参考索引、陷阱、验证、版本标记、子 Agent 技能、内联快照

流程

1. 界定技能范围

• 用一句话说明：“在 <具体情境> 下加载此技能，以便 Agent 能够 <预期成果>。”
• 列出可能也适用的同级技能。将每项都设为负向触发条件。
• 如果技能涵盖两个互不相关的工作流，则拆分该技能。如果它会变成只有一段话的空壳，则合并它。
• 遇到真正需要判断的事项（范围、受众、优先选择哪个产品）时询问用户。无需询问能从仓库中读取的信息。

2. 编写 frontmatter

---
name: my-skill                      # lowercase, hyphenated, equals the folder name
description: <what it does>. Use when <symptoms, APIs, file names, error strings>. Do not use for <case> (sibling-skill).
---

• 路由器看到的唯一文本是描述。在描述中写明具体触发条件：命令名称、配置键、文件名和准确的错误字符串。负向条件中应注明同级技能名称。
• 描述保持单行，且不超过 1,024 个字符（lint 会检查这两项）。
• 可选的 when_to_use: 会附加到 Claude Code 技能列表中的 description 后。组合文本会截断至 1,536 个字符，因此应将关键适用场景放在最前面。其他 Agent 会忽略此字段，因此核心触发条件必须保留在 description 中。
• 只有技能会内联运行命令时才使用 allowed-tools:。保持精简，并限制为只读。

3. 编写精简正文

目标是不超过约 250 行。按以下顺序编写：

1. 一行用途说明，以及一行版本信息（“根据 X 8.77 核验，2026 年 10 月”）。
2. ## When to Use：包含 TRIGGER 项目符号列表，以及一个通过名称指向同级技能的 Do not use when 列表。Lint 要求包含 ## When to Use 标题。
3. ## Reference Index：列出每个文件及其加载时机的表格，并注明“只有当主题涉及某个参考文件时才加载它。”
4. ## Procedure：采用编号步骤。编辑前先检查，并在进行重大更改前报告发现。
5. ## Traps：列出不明显的失败情形。跳过模型已经了解的基础知识。
6. ## Verification：列出能够证明成功的确切命令或检查。
7. ## Error Handling：将确切的错误字符串对应到修复方案。

将内容密集的表格、长代码和各主题的深入内容移至 references/<topic>.md，只深入一层。将脆弱或重复的逻辑放入 scripts/。

4. 核实所有事实

• 根据源代码或官方文档核实每条命令、标志、配置键和 API。优先查阅软件包的 --help、类型定义或仓库，而不是依赖记忆。
• 为时效性较强的事实标注版本（“Capacitor 8.5+”“Xcode 27”“CLI 8.77”）。如果目标版本可能更旧，则通过功能检测来控制可选行为。
• 如果无法核实某项事实，请写明“查阅当前文档”，不要猜测。列出常见的幻觉命令，即那些实际不存在的命令。

5. 匹配命令上下文

• 技能正文使用标准的 npm / npx 示例。Capacitor 和 Capgo CLI 示例使用 npx ...@latest。
• 只有在开发此仓库自身或运行 CI 命令时，或者编写 Bun 专用技能时，才使用 bun / bunx。
• 如果技能要编辑其他仓库，请告知 Agent 阅读该仓库的说明，并遵循其包管理器策略。

6. 保留机密信息

当技能编辑用户文件时，告诉 Agent，除非用户提出要求，否则绝不要将用户提供的令牌、密钥、证书或密码替换为占位符。占位符仅用于新的通用示例。除非用户提出要求，否则不要建议轮换机密信息。

7. 注册和验证（此仓库）

遵循 references/repo-layout.md：在 skills/ 中创建规范文件夹、添加 metadata.json、在 package.json 的 skills 中添加条目、通过插件文件夹和 .claude-plugin/marketplace.json 公开，然后运行 bun run sync-skills 和 bun run lint-skills。

8. 行为必须保持稳定时添加评估

使用 skillgrade（eval.yaml + graders/）。结构检查优先使用确定性评估器。仅在进行定性判断时使用 LLM 评分标准。使用 bun run lint-skills-skillgrade 运行，或在 lint 时使用 API 密钥设置 ENABLE_SKILLGRADE=1。

陷阱

• 含糊的描述（“帮助处理 X”）永远不会触发。过于宽泛的描述（“任何与移动设备有关的内容都使用此技能”）会抢占相邻技能的请求。
• 索引条目如果只写“参见 references/”，却没有说明加载条件，会让 Agent 读取所有内容或什么都不读。务必说明何时读取。
• 过时的事实比结构更容易失效。将版本行放在顶部，方便审查者了解哪些内容需要重新检查。
• 编辑 plugins/<plugin>/skills/ 下的镜像副本是错误的。应编辑规范路径 skills/<name>/，然后同步。
• 内联的 !command`` 快照会在每次加载时运行。应添加保护条件（fs.existsSync），并确保运行速度快、输出简短且只读。

验证

1. bun run lint-skills 通过。它会检查名称是否与文件夹匹配、描述长度、## When to Use 标题、metadata.json 是否有效、是否通过 marketplace 公开，以及镜像是否逐字节一致。
2. wc -l skills/<name>/SKILL.md 的行数约为 250 行或更少，并且 references/ 中的每个文件都在 Reference Index 中列出。
3. 对技能中的每条命令运行 grep，结果都能在该工具的 --help 或源代码中找到。
4. 心智路由测试：三个应该触发该技能的提示词都能触发；每个相邻技能各使用一个提示词，都不会触发该技能。

错误处理

Lint 消息	修复方法
<skill>: name "<x>" does not match folder name	让 frontmatter 中的 name 与目录名一致
<skill>: description exceeds 1024 characters	删除冗余内容，保留具体触发条件和否定条款
<skill>: missing usage guidance	添加 ## When to Use 标题
<skill>: missing metadata.json / invalid metadata.json	创建或修复 JSON（参见 references/repo-layout.md）
claude marketplace: skill "<x>" is not exposed by any plugin	创建 plugins/<plugin>/skills/<x>/，然后运行 bun run sync-skills
mirrored skills: ... (run bun run sync-skills)	运行 bun run sync-skills。绝不要手动编辑镜像
<plugin>: unknown skill "<x>"	插件文件夹中没有匹配的 skills/<x>。创建规范技能或移除该文件夹