agent-skill-creator

Skill Creator

创建有效、可移植的技能，使其可在 Claude.ai、Claude Code 和 API 中运行。技能是一个文件夹化的指令集，只需编码一次即可复用工作流，并始终如一地应用。

技能结构

skill-name/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
├── scripts/              # Optional: executable code for deterministic tasks
├── references/           # Optional: docs loaded into context as needed
└── assets/               # Optional: files used in output (templates, images, fonts)

SKILL.md

两部分：

1. Frontmatter（YAML）—— name 和 description 字段。始终位于上下文中，用于决定何时触发技能。
2. 正文（Markdown）—— 指令、工作流以及捆绑资源的指引。仅在触发后加载。

捆绑资源

目录	用途	是否加载到上下文中？
scripts/	用于确定性操作的可执行代码（Python/Bash）	仅当 Claude 读取时
references/	Claude 工作时查阅的文档	按需
assets/	用于输出的文件（模板、图片、字体）	从不——直接用于输出

不要包含 README.md、CHANGELOG.md 或任何辅助文档文件。

核心原则

上下文预算

上下文窗口由各方共享。只包含 Claude 尚不知道的内容。优先使用简洁示例，而非冗长解释。每个段落都必须值得其 token 开销——删除不必要的段落。

硬性限制：SKILL.md 正文不得超过 5,000 个单词。将详细内容移至 references/。

自由度

根据任务的脆弱程度匹配具体程度：

• 高自由度（文本指导）——有多种有效方法，且取决于上下文
• 中自由度（伪代码/参数化脚本）——采用首选模式，允许一定变化
• 低自由度（精确脚本）——适用于脆弱操作，强调一致性

渐进式披露

三层加载可最大限度地减少上下文用量：

1. Frontmatter（少于 100 个单词）——始终位于上下文中
2. SKILL.md 正文（少于 5,000 个单词）——技能触发时加载
3. 捆绑资源（不限）——按需加载

保持 SKILL.md 精简。超过 300 行时拆分为参考文件。务必在 SKILL.md 中引用拆分出的文件，并清楚说明何时阅读。

可组合性与可移植性

• 技能必须能够共存，且指令之间不得冲突
• 技能必须可在 Claude.ai、Claude Code 和 API 中运行
• 不要强依赖特定环境的工具

工作流

1. 了解需求

在开始构建之前，收集具体用例。

入口：用户请求创建或改进技能。

操作：

• 确定 2–3 个技能的具体使用示例
• 对每个示例，明确其触发条件、执行步骤和预期结果
• 提出有针对性的问题——避免一次向用户提出过多问题

出口：清楚了解技能的范围、触发条件和预期输出。

2. 规划

确定技能需要哪些可复用资源。

入口：步骤 1 中的具体用例。

操作：

• 对每个用例，明确哪些内容会在每次使用时重写；这些内容应纳入技能
• 对资源分类：
  • 反复重写的代码 → scripts/
  • 反复查阅的知识 → references/
  • 输出中使用的模板/资源 → assets/
• 确定 SKILL.md 的结构——常见模式请参阅 references/workflows.md。

出口：待创建资源清单和 SKILL.md 大纲。

3. 构建

创建技能文件夹并编写其内容。

入口：第 2 步中的资源列表和 SKILL.md 大纲。

操作：

1. 创建技能文件夹，遵循上述结构。如果环境中提供了 scripts/init_skill.py，请将其用作快速搭建工具：

   scripts/init_skill.py <skill-name> --path <output-directory>
   

   否则，手动创建文件夹并编写 SKILL.md。

2. 优先编写打包资源——脚本、参考资料、素材。运行脚本进行测试。删除不需要的脚手架文件。

3. 编写 SKILL.md：

   • Frontmatter：按照 references/description-authoring.md 中的描述公式
   • 正文：使用祈使式或不定式。按工作流步骤或任务类别组织内容。
   • 保持正文精简——深入内容请参阅参考资料
   • 对照 references/validation-checklist.md 进行验证，确保技能满足所有结构要求

4. 删除未使用的脚手架——移除示例文件和空目录。

出口：包含所有资源和 SKILL.md 的完整技能文件夹。

4. 测试

验证触发效果和输出质量。

入口：第 3 步完成的技能。

操作：

• 运行触发测试（正向和负向提示）
• 在真实任务上运行功能测试
• 将结果与基线（不使用技能）进行比较

详细测试方法和成功标准请参阅 references/testing-iteration.md。

出口：技能在 10 个相关提示中至少有 9 个能触发，并生成一致的输出。

5. 迭代

根据实际使用情况进行改进。

入口：测试结果或用户反馈。

操作：

• 诊断问题：触发不足、过度触发或执行失败
• 按照 references/testing-iteration.md 针对问题进行修复
• 重新测试受影响的部分

出口：技能在真实场景中达到成功标准。

打包

将完成的技能打包为 .skill 文件（扩展名为 .skill 的 zip 文件）。如果提供了 scripts/package_skill.py，请使用它——该脚本会自动验证并打包：

scripts/package_skill.py <path/to/skill-folder> [output-directory]

否则，手动压缩技能文件夹，并确保 SKILL.md 位于归档文件的根目录。

参考指南

根据技能的需求查阅以下指南：

• 描述和触发条件：references/description-authoring.md——公式、触发短语、负向触发条件、硬性约束
• 工作流模式：references/workflows.md——顺序式、多服务、迭代式、上下文感知、领域智能
• 输出模式：references/output-patterns.md——模板和基于示例的输出指南
• 测试和迭代：references/testing-iteration.md——触发测试、功能测试、性能指标、诊断
• 验证清单：references/validation-checklist.md——每个技能都必须满足的结构要求
• 故障排除：references/troubleshooting.md——常见故障及解决方法

示例

正向触发

用户：“创建一个用于将 PDF 转换为 Markdown 并包含可复用脚本的新技能。”

预期行为：遵循此技能的工作流——了解用例、规划资源、构建技能。

不触发

用户：“查找并修复 src/api/client.ts 中的 TypeScript 类型错误。”

预期行为：不要使用此技能。选择更相关的技能，或直接处理。

故障排除

创建的技能无法触发

• 错误：预期触发时未选择该技能。
• 原因：描述缺少具体触发短语，或表述过于模糊。
• 解决方案：按照 references/description-authoring.md 重写描述。

创建的技能过于冗长

• 错误：SKILL.md 超过 5,000 个词或占用过多上下文。
• 原因：详细内容应放在参考资料中，而不是正文里。
• 解决方案：将详细内容移至 references/ 文件。让 SKILL.md 保持精简，作为工作流指南。

不同会话中的输出不一致

• 错误：技能每次产生的结果质量都不同。
• 原因：说明含糊不清，或缺少明确的验证步骤。
• 解决方案：添加具体示例、准确的命令和验证步骤。请参阅 references/troubleshooting.md。