anthropic-skill-creator

创建技能

构建能够正确触发、可靠执行且简洁明了的技能。

核心原则

• 使用渐进式披露：
  • 使用 Frontmatter（name、description）进行触发选择。
  • 使用 SKILL.md 正文说明核心工作流。
  • 使用 references/ 存放仅在需要时加载的详细信息。
• 确保技能可组合：不要假设当前只有这一个技能处于启用状态。
• 对脆弱的验证逻辑，优先使用确定性脚本。

工作流

1. 定义 2-3 个具体用例。
2. 起草触发效果强的 Frontmatter。
3. 设计可复用资源（scripts/、references/、assets/）。
4. 编写可执行的说明和错误处理方式。
5. 运行触发、功能和性能测试。
6. 根据触发不足或过度触发的信号进行迭代。

1) 定义用例

为每个用例记录：

• 用户的表达方式（用户实际会怎么说）
• 预期结果
• 多步骤工作流和所需工具（内置工具和/或 MCP）
• 需要设置防护措施的失败点

如果用例描述模糊，请先提出有针对性的追问，再开始编写。

2) Frontmatter 设计（最重要）

只写正确触发所需的内容。

必填字段：

• name：使用 kebab-case，并与文件夹名称一致
• description：必须同时包含以下内容
  • 技能的功能
  • 适用时机（触发短语/上下文/文件类型）

描述公式：

• [功能] + [适用时机] + [关键能力]

良好示例：

• “处理用于合同审查的 PDF 法律文档。用户要求从 .pdf 合同中提取条款、标记风险或总结修订内容时使用。”

不良示例：

• “帮助处理项目。”

精确度控制：

• 添加负向触发条件，以减少过度触发。
• 在适用时注明相关文件类型。
• 使用与用例中真实用户表达一致的措辞。

3) 资源规划

• scripts/：重复使用的确定性检查/转换脚本
• references/：大型文档、领域逻辑、特定变体的指导
• assets/：输出中使用的模板和产物

规则：

• 保持 SKILL.md 简洁；链接到 references/。
• 避免在技能文件夹中添加额外文档（如 README.md、变更日志等）。

4) 编写说明

编写祈使式、可测试的步骤。

包含：

• 清晰的步骤顺序和依赖关系
• 验证检查点
• 常见错误及具体修复方法
• 用户输入示例和预期输出

对于关键检查，优先使用脚本，而不是只用文字描述。

5) 测试协议

运行以下三组测试。

A. 触发测试

• 明显的请求应触发
• 改述后的请求应触发
• 无关请求不应触发

目标基准：

• 在包含 10-20 个提示词的测试集中，相关提示词的触发率约为 90%

B. 功能测试

验证：

• 输出正确
• 工具/API 调用成功
• 错误处理路径
• 边缘情况

C. 性能对比

对比启用和未启用技能时的表现：

• 澄清轮数
• 失败的工具/API 调用次数
• Token 用量
• 端到端完成质量

6) 迭代规则

触发不足的信号：

• 预期会加载时，技能却未加载
• 用户总是需要手动调用技能

修复方法：

• 在 description 中加入更清晰的触发短语和技术术语。

过度触发的信号：

• 技能针对无关请求加载

修复方法：

• 添加负向触发条件，并收紧范围描述。

执行问题：

• 输出不一致、反复重试、用户需要纠正

修复方法：

• 收紧说明、添加明确的验证步骤，并将关键检查写成脚本。

故障排除速查指南

• 上传时提示缺少 SKILL.md：文件名必须恰好为 SKILL.md。
• Frontmatter 无效：检查 YAML 分隔符 --- 和语法是否有效。
• 技能名称无效：使用小写 kebab-case。
• 未遵循技能：将关键说明移到顶部，并写得具体明确。
• 行为缓慢：将长内容移至 references/；减少启用的技能数量。

脚手架

为新技能目录生成脚手架：

# Use default path (.agents/skills)
bash scripts/new_skill.sh <skill-name>

# Place in .claude/skills directory
bash scripts/new_skill.sh <skill-name> --path .claude/skills

参考资料

• references/checklist.md
• references/prompt-templates.md
• references/patterns.md
• references/source.md：源 PDF 和提取的原则
• references/trigger-examples.md：用于优化描述的触发/未触发示例
• references/failure-remedies.md：失败模式和最低限度的有效修复措施