skill-writer

技能编写器

将此流程作为创建和改进技能的唯一规范工作流。 主要成功条件：在撰写前尽可能覆盖高价值输入，同时尽量减少浪费的运行时令牌。

按顺序执行工作流步骤。只加载当前步骤所需的参考文件。 SKILL.md 是主要路由文件：每个随附的参考文件都应平铺在 references/ 下，并在此处列出，同时直接说明“何时打开”。

核心工作流参考

需要……时打开	阅读
选择创建、更新、迭代或先研究后执行时的最简工作流路径	references/mode-selection.md
在决定文件前选择足够简单的执行形式	references/execution-shapes.md
应用有关深度、简洁性和可移植性的写作约束	references/design-principles.md
判断哪些内容应放在 SKILL.md、references/、SPEC.md 或支持文件中	references/reference-architecture.md
创建或更新技能的维护契约	references/spec-template.md
查找缺失的高信号来源，包括历史记录和回归问题	references/source-discovery.md
将上游提示词、工作流、评估标准、基准测试或文档改编为技能	references/source-adaptation.md
执行完整的综合流程，并进行覆盖检查和来源记录	references/synthesis-path.md
撰写或更新 SKILL.md、SPEC.md 和支持文件	references/authoring-path.md
改进触发语句以及误报和漏报情况	references/description-optimization.md
根据正例、反例或修复示例进行迭代	references/iteration-path.md
存储持久化工作示例和留出示例，以供后续修订使用	references/iteration-evidence.md
选择响应模板、架构或输出契约	references/output-contracts.md
为技能生成的输出或运行时行为添加或更新评估	references/skill-evals.md
排查布局过载、隐藏引用或其他结构问题	references/structure-troubleshooting.md
注册技能并运行最终验证检查	references/registration-validation.md

工件布局参考

需要……时打开	阅读
将整个技能放在一个连贯的 SKILL.md 中	references/layout-inline-skill.md
将可选的深度知识拆分到按需路由的参考文件中	references/layout-reference-backed-skill.md
为确定性自动化或验证添加脚本	references/layout-script-backed-workflow.md
定义通常通过显式参数调用的技能	references/layout-argument-driven-skill.md
提供可复用的模板、架构或其他静态资源	references/layout-asset-template-skill.md

工作流机制参考

需要……时打开	阅读
将任务拆分为固定顺序的步骤	references/workflow-prompt-chaining.md
对请求进行分类，并将其路由到不同的后续路径	references/workflow-routing.md
将独立工作拆分为并行单元或投票任务	references/workflow-parallel.md
动态发现工作单元并协调工作者输出	references/workflow-orchestrator-workers.md
在撰写或执行期间运行“验证—修复—重复”检查	references/workflow-validation-loops.md
在执行高风险操作前验证计划	references/workflow-plan-validate-execute.md

Claude Code 参考资料

在以下情况下打开……	阅读
使用 Claude 专属的 frontmatter 或调用控制	references/claude-frontmatter-invocation.md
使用 Claude 参数字段或替换变量	references/claude-argument-substitutions.md
构建在隔离的 context: fork 中运行的技能	references/claude-subagent-fork.md
构建使用 Claude hooks 进行确定性强制执行的技能	references/claude-hook-backed.md
使用 Claude shell 预处理来动态注入上下文	references/claude-dynamic-context.md

示例配置

在以下情况下打开……	阅读
查看文档密集型技能应有的深度	references/example-documentation-skill.md
查看工作流流程型技能应有的深度	references/example-workflow-process-skill.md
查看优秀的路由型技能是什么样的	references/example-router-skill.md
查看优秀的子 Agent 分叉型技能是什么样的	references/example-subagent-fork-skill.md
查看优秀的 hook 支持型技能是什么样的	references/example-hook-backed-skill.md

步骤 1：确定目标、路径和形式

1. 确定预期操作（create、update、synthesize、iterate），并在选择文件存放位置前检查工作区中的既有实践。
2. 根据观察到的惯例选择目标技能根目录。如果检查后仍无法确定规范位置，请先直接提问，再编辑文件。
3. 阅读 references/mode-selection.md，选择所需的最精简工作流路径。
4. 阅读 references/execution-shapes.md，选择主要执行形式。
5. 默认采用足够满足需求的最简单形式。如果选择更复杂的形式，请记录拒绝较简单形式的原因。
6. 仅加载该形式所需的确切制品布局、工作流机制和提供方专属的叶级文件。
7. 添加指导内容前，先确定应收窄、替换或移除哪些现有规则、章节或文件。
8. 使用提供方专属机制前，记录其可移植性影响。

步骤 2：按需运行综合流程

阅读 references/synthesis-path.md。

1. 对于新技能、重大变更和研究优先的规划，使用此路径。
2. 收集相关来源，记录来源出处并进行评分。
3. 当源材料不足、过时或含糊不清时，阅读 references/source-discovery.md。
4. 改编上游提示词、工作流、评估标准、基准测试或文档时，阅读 references/source-adaptation.md。
5. 输出有来源支持的决策以及覆盖情况／缺口状态，包括类别和执行形式的选择。
6. 仅在示例配置能为所选类别或形式提供具体帮助时加载。
7. 如果技能使用提供方专属机制，请纳入最新的官方提供方文档，并记录使用限制。
8. 在充分了解所需覆盖范围或明确列出缺口之前，不要开始编写。

步骤 3：根据结果／示例改进时，先运行迭代流程

当所选路径包含 iteration（例如操作 iterate）时，请先阅读 references/iteration-path.md。

1. 收集并匿名化示例，同时记录来源出处。
2. 示例需要在当前轮次之后继续保留时，阅读 references/iteration-evidence.md。
3. 根据工作样本和留出样本评估技能表现。
4. 根据正向、负向和修复证据提出改进建议。
5. 将具体的行为差异带入编写阶段。

所选路径不包含 iteration 时，跳过此步骤。

第 4 步：编写或更新技能产物

阅读 references/authoring-path.md。

1. 用祈使语气编写或更新 SKILL.md，并在描述中加入丰富的触发条件。
2. 将 SKILL.md 保持为运行时路由器，而不是百科全书。
3. 在创建新章节或文件之前，先按照 references/authoring-path.md 执行编辑前精确性检查。
4. 添加大量说明或新的参考文件之前，阅读 references/reference-architecture.md。
5. 创建新技能或对其契约进行重大更改时，使用 references/spec-template.md 创建或更新 SPEC.md。
6. 仅在每个聚焦的参考文件、脚本和资源都有明确的“何时打开……”理由，且无法通过完善现有文件来处理时，才创建它们。
7. 如果添加了随附参考文件，请在此 SKILL.md 中为其添加直接路由条目。
8. 优先使用清单、表格、模板和输入／输出示例，而不是说明性散文。
9. 仅遵循为此技能选定的具体产物布局、工作流机制、Claude 专属内容和输出契约参考。
10. 对于高级执行模式，在将技能视为完成之前，先添加所需的路由、委派或安全契约。
11. 对于编写或生成类技能，请在参考文件中加入转换后的示例：

• 顺利路径
• 安全／稳健变体
• 反模式及修正版本

12. 当请求涉及为正在编写的技能提供评估、回归用例、基准用例或模型评分质量检查时，阅读 references/skill-evals.md。
13. 对技能产物进行任何更改后，在优化描述或验证之前，按照 references/authoring-path.md 执行编辑后精确性检查。

第 5 步：优化描述质量

阅读 references/description-optimization.md。

1. 验证应触发和不应触发的查询集。
2. 通过针对性的描述编辑减少误报和漏报。
3. 除非技能有意针对特定提供商，否则触发条件的措辞应适用于不同提供商。

第 6 步：注册并验证

阅读 references/registration-validation.md。

1. 根据在工作区中确认的当前布局，执行仓库注册步骤。
2. 运行快速验证以检查结构。
3. 在完成前，结合判断审查验证器警告、精确性检查结果和覆盖缺口。

输出格式

返回：

1. Summary
2. Changes Made
3. Validation Results
4. Open Gaps