文档撰写技能

撰写或更新一个技能，使其符合主机的预期结构。请使用以下结构和核对清单。

输入

1. 目标技能– 技能文件夹的路径（例如项目技能目录skills/example/）或技能名称。
2. 来源– 草稿、用户指示或笔记，用于创建技能或合并到技能中。

如果您未提供任何一项：使用当前或给定的上下文（例如，正在讨论的技能或路径）。

输出

SKILL.md 已更新（以及所需的支持文件）。

流程

1. 技能布局

• 每个技能一个文件夹。主文件始终是SKILL.md（确切的名称，区分大小写）。
• 文件夹名称：必须为kebab-case（短横线分隔式命名法）（小写，连字符；无空格、下划线或大写字母）。前言中的名称必须与文件夹名称匹配。技能存放位置：
• 在项目中，通常是一个专门的技能目录（例如skills/<名称>/）。宿主会从此位置发现技能，即使它被嵌套（例如在包内）。仅限可选的子文件夹：
• 使用scripts/（可执行代码）、references/（按需加载的文档）和assets/（模板、图标等）。不要将 README.md 放在技能文件夹内；所有文档都放在 SKILL.md 或 references/ 中。较长的参考资料放在references/中，并从 SKILL.md 链接（渐进式披露）。长度：
• 保持 SKILL.md 在约 5,000 字以内。较长的参考资料放在references/references/链接自 SKILL.md。
• 渐进式披露：技能使用三个层级——(1) YAML 前置元数据始终加载，以便助手知道何时使用该技能；(2) SKILL.md 正文在技能相关时加载；(3) references/ 或 assets/ 中的文件仅在需要时打开。这既能降低令牌使用量，又能保持专业知识可用。
• 可组合性：技能可以一起加载。编写技能时，要确保它能与其他技能协同工作；不要假定它是唯一活跃的技能。

2. SKILL.md 格式

前置元数据（位于第一个---行之间的 YAML 块）

前置元数据配置技能运行的时间和方式。下表遵循官方技能参考。

name和description是必填项。name必须与文件夹名称匹配（kebab-case）。description应遵循：[功能] + [使用时机] + [核心能力]— 不超过1024个字符；不使用XML尖括号（< >）。避免使用模糊的表述，如"协助项目"；需包含具体的触发短语，如果相关，请包含文件类型（例如".fig文件"、"PDF合同审阅"）。

可选： 许可证（例如，开源用 MIT），兼容性（1–500 字符：产品、系统依赖、网络）。元数据（例如作者、版本、mcp服务器）。参见完整技能指南。

安全：前置内容中不要包含XML尖括号。避免在技能名称中使用保留名称（例如主机或供应商名称）。

YAML注意事项：避免在值内部使用冒号。它们可能被解析为新键。在文本中使用类似“范围是”的表述，而不是“范围：”。

内容类型

• 参考内容– 约定、模式、风格。助手会将其内联应用于您当前的工作。无需调用控制。
• 任务内容– 针对特定操作（部署、提交、代码生成）的分步说明。通常通过/技能名称直接调用。使用disable-model-invocation: true以便技能不会自动加载。

正文部分（每个技能的顺序相同）

使用相同的部分顺序，以便技能易于浏览：

1. # 标题– 技能名称作为一级标题（H1），然后是一段简短的介绍（说明其功能）。
2. ## 输入– 技能所需内容（用户输入、路径、选项）。对项目进行编号。当不需要任何内容时，使用"无"或"可选"。
3. ## 输出– 你将获得什么（一个文件、一种行为、一项交接）。一个简短的段落。
4. ## 流程– 如何操作。编号的步骤或子章节（例如 "### 1. 步骤名称"）。将所有操作方法和规则放在这里。要具体且可操作（例如，"运行python scripts/validate.py --input {filename}"，而不是"验证数据"）。包含常见故障的错误处理；在相关时引用捆绑文件（例如，"在查询之前，请查阅references/api-patterns.md"）。
5. ## 示例– 可选但推荐。常见场景："用户说 X → 操作 → 结果。"
6. ## 故障排除– 可选但推荐。错误或症状 → 原因 → 解决方案。
7. ## 参考– 可选。指向相关技能或文档的链接。

仅当某部分确实不适用时才跳过。不确定时，应包括输入、输出、过程和参考；在有助于理解的地方添加示例和故障排除。与其他仓库中技能的布局保持一致。

替换（在正文中）

来自官方文档：

• $ARGUMENTS– 调用技能时传递的所有参数。如果内容中不存在，参数会以ARGUMENTS:的形式追加。
• $ARGUMENTS[N]或$N– 第N个参数（基于0的索引）。
• ${CLAUDE_SESSION_ID}– 当前会话ID（由主机定义）。
• ${CLAUDE_SKILL_DIR}– 包含技能SKILL.md文件的目录（由主机定义）。

关于在技能运行前注入shell输出，请参见注入动态上下文.

3. 撰写或更新时的核对清单

1. 前置元数据： 描述遵循[它做什么] + [何时使用] + [核心功能]的格式，且要具体（包含用户可能说的短语，例如“当用户说保存、/save 时使用”）。名称与技能匹配。任务型或副作用型技能：disable-model-invocation: true需根据官方文档设置。
2. 章节：按输入、输出、流程的顺序，然后可选示例和故障排除，最后是参考。顺序与其他技能保持一致。
3. 长度：不超过 500 行；冗长的参考资料放在其他文件中，并从 SKILL.md 链接。
4. 支持文件：如果使用，请在 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 文件，并包含必需的前置元数据（name: validate-csv，描述使用[功能说明] + [使用时机] + [核心能力]格式，例如：“验证CSV上传。当用户说验证CSV、检查上传、/validate-csv时使用。核心能力：模式检查、编码检测。”）。添加输入、输出、处理过程，以及可选的参考部分。如果该技能运行一个脚本，则添加scripts/validate.sh并在处理过程中引用它。

结果：一个新的技能，在指定的短语触发；如果它是流程的一部分，则更新协调器和流程。

用户说：“更新保存技能，提及 update-gitignore。”

操作：打开保存技能的 SKILL.md（例如skills/save/SKILL.md）。在处理过程中添加新的步骤或引用。如果触发短语发生变化，则更新描述。同步协调器和references/coordinator-flows.md如果保存流程发生变化。

故障排除

无效的前置元数据/上传错误。
原因：YAML格式问题（缺少---分隔符、未闭合的引号，或冒号被读取为新键）。
解决方案：确保前置元数据位于两个---行之间。避免在描述文本中使用冒号；用"Use when"而非"When:"。前置元数据中不要包含<或>。

技能未触发。
原因：描述过于模糊或缺少完整公式（功能、使用时机、关键能力）或触发短语。
解决方案：使用[功能] + [使用时机] + [关键能力]的格式，并添加具体的"当用户说X、Y时使用/技能名称"。如果技能是流程的一部分，相同的短语也应出现在协调器流程表中。调试：询问助手“你会在什么时候使用[技能名称]这个技能？”，并根据缺失的内容调整描述。

技能触发过于频繁。
原因：描述过于宽泛或与其他技能重叠。
解决方案：添加负面触发条件（例如：“不要用于简单的数据探索；请使用数据可视化技能”）。缩小范围（例如：“用于合同审查的PDF法律文档”，而不是“处理文档”）。明确何时不使用（例如：“专门用于在线支付工作流，不用于一般财务查询”）。

文件夹名称错误。
原因：文件夹名称包含空格、下划线或大写字母。
解决方案：重命名为短横线命名法。更新SKILL.md中的名称以匹配。更新所有引用（协调器、代理、README、package.json、检查脚本、agents/references/）。编写完成后，

协调器同步：

• 如果你更改了描述（例如“何时使用”或匹配用户请求的关键能力），请更新协调器代理以及references/coordinator-flows.md中的流程步骤。references/coordinator-flows.md如果该技能属于某个流程的一部分，那么流程表和代理描述要保持同步。
• 重命名/移动：如果某个技能被重命名或移动（例如：generate-figma → designer-figma），更新所有引用：协调器、代理、README、package.json、链接到该技能的其他技能、verify-task 检查清单脚本、agents/references/（例如，如果技能出现在流程中，则更新 coordinator-flows.md）以及 .gitignore。

参考

官方技能参考– 前言信息、控制谁调用技能、在子代理中运行、替换。协调器– 流程表和代理描述应遵循[功能] + [使用时机] + [关键能力]并与用户使用的短语相匹配。

构建技能的完整指南– 渐进式披露、描述公式、好/坏示例、可选的前言信息、触发与故障排除、指令最佳实践。