skill-builder

Skill Builder

为 Claude Code 构建生产级 Skills，采用规范的结构、易于发现的描述和最佳实践。

快速参考

描述公式：[功能] + [使用时机] + [用户会说的触发词]

名称规则：仅限小写字母、数字和连字符；最多 64 个字符；不含空格

描述规则：最多 1024 个字符；必须具体并包含触发词

Skill 创建工作流

阶段 1：需求收集

使用 AskUserQuestion 了解用户需求：

1. Skill 应该做什么？

   • 它应提供什么能力或专业知识？
   • 它应帮助完成哪些任务？

2. 何时应激活？

   • 什么场景或上下文？
   • 用户会说哪些词语或短语？
   • 涉及哪些文件类型或操作？

3. 范围决策

   • 个人 Skill（~/.claude/skills/）——仅供当前用户使用
   • 项目 Skill（.claude/skills/）——通过 git 与团队共享

4. 结构复杂度

   • 单文件（简单说明／示例）
   • 多文件（脚本、模板、大量文档）

5. 工具限制

   • 完整访问权限（默认）
   • 受限（通过 allowed-tools 字段设置只读或有限范围）

阶段 2：编写描述

描述决定了 Skill 是否容易被发现。请使用这个经过验证的公式：

[Specific operations] + [When to use] + [Trigger terms]

示例解析：

• ❌“帮助处理文档”（太模糊）
• ✅“从 PDF 文件中提取文本和表格、填写表单、合并文档。在处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。”

关键要素：

1. 具体操作：列出明确的操作（提取、分析、生成、验证）
2. 使用时机：场景和上下文（处理 X 时、在 Y 期间、用于 Z 任务）
3. 触发词：用户可能会说的确切词语（PDF、表单、提交消息、数据分析）

更多模式请参阅 examples/descriptions.md。

阶段 3：名称验证

验证并规范名称：

• 转换为小写
• 将空格替换为连字符
• 移除无效字符（仅允许：a-z、0-9、-）
• 确保不超过 64 个字符
• 名称应具体且简洁

示例：

• “My PDF Tool” → “my-pdf-tool”
• “Code Reviewer!!!” → “code-reviewer”
• “data_analysis” → “data-analysis”

阶段 4：规划结构

单文件适用于：

• 说明和示例能轻松放在一个文件中
• 无需脚本或实用工具
• 工作流简单明了

多文件适用于：

• 文档内容较多（拆分到 reference.md）
• 需要脚本或实用工具（scripts/ 目录）
• 包含模板或样板内容（templates/ 目录）
• 示例较多（examples.md）

复杂 Skills 的推荐结构：

skill-name/
├── SKILL.md           # Core instructions (loaded first)
├── reference.md       # Detailed API/reference (loaded if needed)
├── examples.md        # Additional examples (loaded if needed)
├── scripts/           # Utility scripts
│   ├── helper.py
│   └── process.sh
└── templates/         # Template files
    └── template.txt

阶段 5：实施

创建目录

# Personal Skill
mkdir -p ~/.claude/skills/skill-name

# Project Skill
mkdir -p .claude/skills/skill-name

# Multi-file structure
mkdir -p ~/.claude/skills/skill-name/{templates,scripts,examples}

编写 SKILL.md

模板结构：

---
name: skill-name
description: [Use the formula from Phase 2]
allowed-tools: Read, Grep, Glob  # Optional: only if restricting tools
---

# Skill Name

Brief introduction explaining what this Skill does.

## Quick Start

Provide the most common use case with a concrete example.

## Instructions

Step-by-step guidance for Claude:

1. [First step with specific actions]
2. [Second step with expected behavior]
3. [Continue pattern]

## Examples

Show concrete code examples:

```language
# Example code that demonstrates usage

最佳实践

• 关键原则或模式
• 重要注意事项
• 需要避免的常见陷阱

要求

列出所有依赖项：

pip install required-package

#### Add supporting files if multi-file

Reference from SKILL.md:
```markdown
For detailed API reference, see [reference.md](reference.md).

Use the helper script:
```bash
python scripts/helper.py input.txt

### Phase 6: Validation

Before finalizing, check:

- [ ] Description follows formula (what + when + triggers)
- [ ] Description under 1024 characters
- [ ] Name is lowercase-with-hyphens, under 64 chars
- [ ] YAML has opening and closing `---`
- [ ] YAML uses spaces not tabs
- [ ] Instructions are clear and actionable
- [ ] Examples are concrete and tested
- [ ] Dependencies are documented
- [ ] Tool restrictions (if any) are appropriate

See [reference/validation-checklist.md](reference/validation-checklist.md) for complete checklist.

### Phase 7: Testing

1. **Restart Claude Code** (required for Skills to load)

2. **Test discovery**:
   - Ask using trigger terms from your description
   - Verify Skill activates automatically
   - Try variations of trigger phrases

3. **Test workflow**:
   - Follow instructions as Claude
   - Verify all examples work
   - Check edge cases

4. **Debug if needed**:
   ```bash
   # Check Skill was loaded
   # Ask: "What Skills are available?"

   # View Skill file
   cat ~/.claude/skills/skill-name/SKILL.md

   # Check for YAML syntax errors
   claude --debug

常见问题及解决方案

问题：Skill 未激活

原因：

1. 描述太模糊
2. 触发词与用户用词不匹配
3. YAML 语法错误
4. 未重启 Claude Code

解决方案：

1. 在描述中加入确切的触发词，使其更具体
2. 添加更多同义词和相关词语
3. 验证 YAML（检查 --- 分隔符，并使用空格而非制表符）
4. 重启 Claude Code

问题：Skill 在不该激活时激活

原因：

1. 描述范围太宽泛
2. 与其他 Skills 重叠

解决方案：

1. 缩小描述范围
2. 添加具体上下文（文件类型、操作）
3. 考虑拆分为专注于特定用途的 Skills

问题：YAML 语法错误

常见错误：

• 缺少开头的 ---（第 1 行）
• 缺少结尾的 ---（Markdown 内容之前）
• 使用制表符而非空格
• 含特殊字符的字符串未加引号

修复方法：

---
name: skill-name
description: Description text here
---

# Markdown starts here

迭代与改进

使用 Skill 后，持续改进：

1. 跟踪激活模式：它是否会在预期情况下激活？
2. 收集反馈：有哪些内容令人困惑或缺失？
3. 优化描述：添加实际使用中出现的触发词
4. 扩展示例：添加遇到的真实场景
5. 更新说明：明确有歧义的步骤

教育原则

创建 Skill 时，请牢记：

描述为何重要：Claude 会根据描述发现 Skill。描述模糊 = 永远不会激活。

多文件结构为何有效：渐进式加载。Claude 会先读取 SKILL.md，仅在需要时才读取辅助文件，从而保持上下文聚焦。

工具限制为何强大：它能创建安全、聚焦的 Skill。只读分析 Skill 不会意外修改文件。

触发词为何关键：用户不知道你的 Skill 存在。他们会自然地提出问题。触发词能将他们的表达与 Skill 联系起来。

快速模板

基础 Skill 模板：templates/basic-skill.md

高级多文件模板：templates/advanced-skill.md

描述示例：examples/descriptions.md

打造出色 Skill 的技巧

1. 描述要具体——明确具体操作、文件类型和场景
2. 加入触发词同义表达——用户的说法各不相同
3. 从简单开始，之后再扩展——先使用单个文件，需要时再增加复杂度
4. 用真实请求测试——使用用户实际会说的话
5. 清楚说明依赖项——不要假设软件包已安装
6. 提供具体示例——展示，而不是只讲述
7. 让说明可执行——提供具体步骤，而非模糊指引
8. 谨慎考虑适用范围——个人用途适合实验，项目用途适合团队
9. 明智地使用工具限制——分析或审查时使用只读 Skill
10. 根据使用情况迭代——根据真实激活模式优化触发词

后续步骤

创建 Skill 后：

1. 与团队分享（如果是项目 Skill，请提交到 git）
2. 如果这是其他人也应了解的模式，请记录在项目的 CLAUDE.md 中
3. 为相关工作流创建相关 Skill
4. 考虑将多个 Skill 打包成插件，以便更广泛地分发

---

请记住：出色的 Skill 具有包含触发词的具体描述。这就是会被使用的 Skill 与永远不会激活的 Skill 之间的区别。