add-skill

添加 Skill

根据用户需求创建结构规范的 Claude Code skills。

快速模式

如需快速创建，用户可以一次性提供所有信息：

/add-skill name=my-skill purpose="Does X" trigger="when user asks for Y"

解析并生成，无需交互式提示。

工作流

步骤 1：获取最新文档

务必先获取官方文档，确保符合当前规范：

WebFetch: https://code.claude.com/docs/en/skills
Prompt: Extract skill file format, required fields, naming rules, and best practices

如果 WebFetch 失败，则使用备用方法：

WebSearch: "Claude Code skills SKILL.md format site:code.claude.com"

步骤 2：收集需求

询问用户（或解析快速模式中的信息）：

1. 范围：全局 Skill 还是仓库本地 Skill？
   • 全局 → ~/.claude/skills/{skill-name}/（在所有项目中均可用）
   • 仓库本地 → .claude/skills/{skill-name}/（仅适用于此仓库，并与代码一同提交）
2. 名称：仅使用小写字母和连字符（优先使用动名词形式：processing-pdfs、testing-code）
3. 用途：它的作用是什么？（1–2 句话）
4. 触发条件：Claude 应在何时使用它？（关键词、场景）
5. 复杂度：仅包含说明，还是需要脚本/参考资料？
6. 自由度：严格（精确步骤）还是灵活（一般性指导）？

步骤 3：创建 Skill 结构

{base-path}/skills/{skill-name}/
├── SKILL.md           # Required: Main instructions (<500 lines)
├── scripts/           # Optional: Executable code
│   └── main.py
└── references/        # Optional: Detailed docs (one level deep)
    └── examples.md

步骤 4：生成 SKILL.md

---
name: {skill-name}
description: {What it does in third person}. Use when {trigger conditions}.
---

# {Skill Title}

{Brief overview - assume Claude is smart, only add context it doesn't already have}

## Quick Start

{Minimal working example or first step}

## Instructions

{Step-by-step guidance with appropriate freedom level}

## Advanced Features

**Feature A**: See [references/feature-a.md](references/feature-a.md)

步骤 5：检查行数并应用渐进式披露

起草 SKILL.md 后，统计其行数。如果接近或超过 500 行：

1. 告知用户：“SKILL.md 有 {N} 行，超过了建议的 500 行上限。”
2. 找出可拆分的部分：详细参考资料、较长示例、高级功能
3. 移至参考文件：references/{topic}.md —— 仅允许一层嵌套
4. 在 SKILL.md 中替换为简短摘要和链接
5. 为任何超过 100 行的参考文件添加目录

步骤 6：验证

定稿前，按照验证清单逐项检查。

步骤 7：核实

ls -la ~/.claude/skills/{skill-name}/
cat ~/.claude/skills/{skill-name}/SKILL.md

使用 claude --debug 测试，检查是否存在加载错误。

命名规则

• 长度：1–64 个字符
• 格式：仅限小写字母、数字和连字符
• 优先使用动名词形式：processing-pdfs、testing-code、writing-documentation
• 可接受的替代形式：pdf-processing、process-pdfs
• 不允许：以 - 开头或结尾、连续出现 --、保留词（anthropic、claude）、XML 标签
• 避免使用：含义模糊的名称（helper、utils、tools）、过于宽泛的名称（documents、data）
• 必须匹配：文件夹名称

描述规则

• 最多：1024 个字符，不能为空，且不得包含 XML 标签
• 始终使用第三人称：使用“处理 Excel 文件”，而不是“我可以帮助你”
• 两者都要包含：它的作用，以及适用场景
• 具体明确：Claude 会根据描述从 100 多个 skills 中进行选择

良好示例：

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

不良示例：“帮助处理文档”“处理数据”“处理文件”

核心原则

简洁

逐项审视每条信息：

• “Claude 确实需要这段说明吗？”
• “可以假设 Claude 已经了解这一点吗？”
• “这段内容值得占用相应的 token 吗？”

自由度

自由度	适用场景	示例
高（文本说明）	存在多种有效方法	代码审查指南
中（伪代码/参数）	存在首选模式	报告生成模板
低（精确脚本）	易出错的操作、对一致性要求高	数据库迁移

术语一致

选定一个术语并在全文中保持一致。不要混用“API endpoint”/“URL”/“API route”。

模式

带检查清单的工作流

对于复杂的多步骤操作，提供可复制的检查清单。

反馈循环

运行验证器 → 修复错误 → 重复，直到通过。

条件工作流

通过决策节点引导操作：创建新的？ →“创建工作流” / 编辑现有内容？ →“编辑工作流”

脚本最佳实践

• 明确处理错误，不要把问题推给 Claude
• 不要使用来历不明的常量——说明并记录所有数值
• 列出依赖项及安装说明
• 明确执行意图：“运行 script.py”（执行）与“参见 script.py”（参考）
• 所有文件路径均使用正斜杠
• MCP 工具引用使用完整限定名称：ServerName:tool_name

反模式

• 解释 Claude 已经知道的内容
• 提供过多工具／库选项——给出一个默认选项，并提供备用方案
• 时效性信息——使用 <details> 标签收纳过时模式
• 多层嵌套引用（文件 → 文件 → 文件）
• 假设软件包已安装，却不提供安装说明

验证清单

核心质量

• 名称：仅使用小写字母、数字和连字符，1–64 个字符，不含保留字
• 描述：使用第三人称，内容具体，说明内容和适用时机，少于 1024 个字符
• SKILL.md 正文少于 500 行
• 其他详细信息放在独立的参考文件中（仅一层）
• 不含时效性信息
• 全文术语一致
• 提供具体示例（而非抽象示例）
• 适当使用渐进式披露

脚本（如适用）

• 脚本明确处理错误
• 不使用来历不明的常量（所有数值均有依据）
• 列出所需软件包及安装说明
• 所有路径均使用正斜杠

测试

• 使用真实场景进行测试
• 适用于目标模型（Haiku 需要更多指导，Opus 需要更少）

延伸阅读

• 评估驱动开发：参见 references/eval-driven-development.md
• 示例：参见 references/examples.md
• 官方文档：https://code.claude.com/docs/en/skills