文档技能规范

编写或更新一项技能，使其符合宿主（host）所期望的结构。请使用下方提供的结构与核对清单。

输入

1. 目标技能 —— 技能文件夹路径（例如项目中的技能目录 skills/example/），或技能名称。
2. 源内容 —— 待转化为技能或合并进技能的草稿、用户指令或笔记。

若未提供任一输入： 使用当前上下文或已明确讨论的上下文（例如正在讨论的技能本身或其路径）。

输出

SKILL.md 文件被更新（如需，同步更新配套文件）。

流程

1. 技能目录结构

• 每个技能独占一个文件夹；主文件必须为 SKILL.md（严格大小写敏感，名称不可变更）。
• 文件夹名： 必须采用 kebab-case 格式（全小写、仅含字母、数字与短横线 -；禁止空格、下划线 _ 或大写字母）。Frontmatter 中的 name 字段值必须与该文件夹名完全一致。
• 技能存放位置： 在项目中，通常位于专用的 skills 目录下（例如 skills//）。宿主会从该路径自动发现技能，即使该路径嵌套在子包内（如 package 内部）。
• 仅允许以下可选子目录： scripts/（存放可执行代码）、references/（按需加载的文档材料）、assets/（模板、图标等资源）。禁止在技能文件夹内放置 README.md；所有说明性内容应统一置于 SKILL.md 或 references/ 中。长篇参考材料应放入 references/ 并在 SKILL.md 中链接（渐进式披露）。
• 长度限制： SKILL.md 应控制在约 5000 字以内。长篇参考资料请移入 references/ 并通过链接引用。
• 渐进式披露（Progressive disclosure）： 技能采用三级加载机制：(1) YAML frontmatter 始终加载，使助手能判断何时启用该技能；(2) SKILL.md 正文仅在技能相关时加载；(3) references/ 或 assets/ 中的文件仅在实际需要时打开。此举可在保障专业能力可用的前提下，最小化 token 消耗。
• 可组合性（Composability）： 多项技能可同时加载并协同工作。请确保所写技能能与其他技能共存，切勿假设其为唯一激活的技能。

2. SKILL.md 格式规范

Frontmatter（首尾以 --- 包裹的 YAML 区块）

Frontmatter 定义技能的触发时机与运行方式。下表遵循官方技能参考文档。

name 与 description 为必填字段。name 必须与文件夹名（kebab-case）完全一致。description 应严格遵循格式：[功能描述] + [适用场景] + [核心能力]，总长度不超过 1024 字符；禁止使用 XML 尖括号（< >）。避免模糊表述（如“辅助项目工作”）；需包含具体触发短语，并在必要时注明文件类型（例如“.fig 文件”、“PDF 合同审查”）。

可选字段： license（例如开源项目使用 MIT）、compatibility（1–500 字符：产品依赖、系统依赖、网络要求等）、metadata（例如作者、版本号、mcp-server 等）。详见完整技能指南。

安全要求： Frontmatter 中禁止出现 XML 尖括号（< >）。技能名称中避免使用保留字（如宿主或厂商名称）。

YAML 注意事项： 避免在字段值中使用冒号（:），否则可能被误解析为新字段键。建议改用类似 “Scope is” 的表达，而非 “Scope:”。

内容类型

• 参考型内容（Reference content） —— 约定、模式、风格规范等。助手会在你当前工作中内联应用这些规则，无需显式调用控制。
• 任务型内容（Task content） —— 针对某项具体操作（部署、提交、代码生成等）的分步指令。常通过 /skill-name 直接调用。建议设置 disable-model-invocation: true 以禁用自动加载。

正文结构（每项技能均须保持相同顺序）

为便于快速扫描，所有技能正文须严格遵循以下节标题顺序：

1. # 标题 —— H1 级标题即技能名，后接一句简短介绍（说明其作用）。
2. ## 输入 —— 技能所需内容（用户输入、路径、选项等）。各项编号列出；若无要求，标注为 “None” 或 “Optional”。
3. ## 输出 —— 技能执行结果（如生成一个文件、触发某种行为、移交至其他模块等）。用一段简短文字概括。
4. ## 流程 —— 实现方法。使用编号步骤或子章节（如 “### 1. 步骤名称”）。所有操作指南与规则均放在此处。务必具体、可执行（例如：“运行 python scripts/validate.py --input {filename}”，而非“验证数据”）。需涵盖常见错误的处理方式；必要时引用配套文件（例如：“查询前请先查阅 references/api-patterns.md”）。
5. ## 示例 —— 可选但强烈推荐。列举典型场景：“用户说 X → 执行动作 → 结果”。
6. ## 故障排查 —— 可选但强烈推荐。格式为：错误现象或症状 → 原因 → 解决方案。
7. ## 参考 —— 可选。链接至相关技能或外部文档。

仅当某节内容确实完全不适用时才可跳过。不确定时，请至少包含 输入、输出、流程 和 参考 四节；并在有助于理解时补充 示例 与 故障排查。整体布局须与仓库中其他技能保持一致。

正文中的变量替换（Substitutions）

依据官方文档定义：

• $ARGUMENTS —— 调用技能时传入的所有参数。若正文中未显式使用该变量，则参数将自动追加为 ARGUMENTS: 形式。
• $ARGUMENTS[N] 或 $N —— 第 N 个参数（索引从 0 开始）。
• ${CLAUDE_SESSION_ID} —— 当前会话 ID（由宿主定义）。
• ${CLAUDE_SKILL_DIR} —— 包含该技能 SKILL.md 文件的目录路径（由宿主定义）。

关于如何在技能运行前注入 Shell 命令输出，请参阅《注入动态上下文》。

3. 编写或更新技能时的核对清单

1. Frontmatter： description 须严格遵循 [功能描述] + [适用场景] + [核心能力] 格式，且内容具体（包含用户可能说出的短语，例如“当用户说 save 或 /save 时使用”）。name 须与技能文件夹名一致。对于任务型或具副作用的技能，请按官方文档要求设置 disable-model-invocation: true。
2. 节标题顺序： 必须为：输入 → 输出 → 流程 → （可选）示例 → （可选）故障排查 → （可选）参考。顺序须与其他技能完全一致。
3. 长度控制： SKILL.md 总行数应少于 500 行；长篇参考资料请移至其他文件，并在 SKILL.md 中链接（渐进式披露）。
4. 配套文件： 若使用了 scripts/、references/ 或 assets/，须在 SKILL.md 中明确说明，并指出加载时机。保持 SKILL.md 聚焦核心说明；长篇或细节类文档请放入 references/ 并建立链接。
5. 参数引用： 如技能接受输入，请使用 $ARGUMENTS 或 $N，并视情况添加 argument-hint。
6. 调用控制： 合理使用 disable-model-invocation 和/或 user-invocable，确保技能在预期场景下运行（参见《控制谁可调用技能》）。

4. 执行步骤

1. 读取目标技能路径及任何源内容。
2. 应用上述核对清单与结构规范。除非用户明确要求，否则不得更改技能原有行为。
3. 编写或更新 SKILL.md（如需，同步更新配套文件）。仅记录技能实际具备的能力；禁止添加尚未实现的功能。

示例

用户说： “创建一个用于验证 CSV 上传的技能。”

操作： 创建文件夹 skills/validate-csv/（或项目指定的技能路径；注意 kebab-case）。添加 SKILL.md 并填写必需的 frontmatter（name: validate-csv；description 须符合 [功能描述] + [适用场景] + [核心能力] 格式，例如：“验证 CSV 上传。当用户说 validate CSV、check upload 或 /validate-csv 时使用。核心能力：Schema 校验、编码自动识别。”）。依次添加 输入、输出、流程、可选的 参考。若技能需运行脚本，请添加 scripts/validate.sh 并在 流程 中引用。

结果： 新建技能可响应所述触发短语；若该技能属于某个流程，协调器（coordinator）与相关流程也将自动更新。

用户说： “更新 save 技能，使其提及 update-gitignore。”

操作： 打开 save 技能的 SKILL.md（例如 skills/save/SKILL.md）。在 流程 中添加新步骤或引用。若触发短语发生变更，请同步更新 description。若 Save 流程有改动，还需同步更新协调器（coordinator）与 references/coordinator-flows.md。

故障排查

Frontmatter 无效 / 上传失败。
原因：YAML 格式错误（缺少 --- 分隔符、引号未闭合、或字段值中冒号被误识别为新字段键）。
解决方案：确保 frontmatter 完全位于两个 --- 行之间；描述文本中避免使用冒号，改用 “Use when” 而非 “When:”；frontmatter 中禁止出现 < 或 >。

技能未触发。
原因：description 过于模糊，或未完整包含三要素公式（功能描述、适用场景、核心能力），或缺失明确触发短语。
解决方案：严格使用 [功能描述] + [适用场景] + [核心能力] 格式，并加入具体触发短语（例如“当用户说 X、Y 或 /skill-name 时使用”）。若该技能属于某个流程，这些短语也应出现在协调器流程表中。调试建议： 向助手提问：“你会在什么情况下使用 [技能名] 技能？”，根据其回答中缺失的部分调整 description。

技能触发过于频繁。
原因：description 描述范围过宽，或与其他技能存在重叠。
解决方案：添加否定性触发条件（例如“切勿用于简单数据探索；请改用 data-viz 技能”）。收窄适用范围（例如“专用于 PDF 法律合同审查”，而非“处理文档”）。明确说明不适用场景（例如“仅限在线支付工作流，不适用于通用金融查询”）。

文件夹名错误。
原因：文件夹名含空格、下划线或大写字母。
解决方案：重命名为 kebab-case 格式；同步更新 SKILL.md 中的 name 字段；更新所有引用位置（协调器、代理、README、package.json、检查清单脚本、agents/references/ 等）。

编写完成后

• 协调器同步： 若修改了 description（例如“适用场景”或“核心能力”部分，使其更贴合用户请求），且该技能属于某个流程，请同步更新协调器代理（coordinator agent）及 references/coordinator-flows.md 中的流程步骤，确保流程表与代理描述保持一致。
• 重命名/移动： 若技能被重命名或移动（例如 generate-figma → designer-figma），请更新所有引用位置：协调器、代理、README、package.json、其他技能中对该技能的链接、verify-task 检查清单脚本、agents/references/（例如若该技能出现在某个流程中，则需更新 coordinator-flows.md）、以及 .gitignore。

参考

官方技能参考文档 —— 包含 frontmatter 字段说明、调用权限控制、子代理运行方式、变量替换语法等。协调器（Coordinator）— 流程表与代理描述须遵循 [功能描述] + [适用场景] + [核心能力] 公式，并与用户实际说出的短语保持一致。

完整技能构建指南 —— 渐进式披露机制、description 公式详解、优秀/反面示例、可选 frontmatter 字段、触发逻辑与故障排查、最佳实践等。