skill-gen

Skill Generator

根据用户需求生成结构规范的 Claude Code skills。

快速开始

创建新 skill 时，向用户收集以下信息：

1. 这个 skill 应该做什么？
2. 一个简短的名称（例如，processing-pdfs、testing-code）
3. Claude 应该在什么时候使用它？
4. 它需要脚本，还是只需要说明？

工作流

步骤 1：收集需求

• 用途：这个 skill 有什么作用？
• 触发条件：它应该在什么时候启用？（关键词、场景）
• 复杂度：仅需说明，还是需要脚本或参考资料？
• 自由度：严格（精确步骤）还是灵活（一般指导）？

步骤 2：生成 Skill 结构

创建目录：~/.claude/skills/{skill-name}/

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

步骤 3：编写 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)
**Feature B**: See [references/feature-b.md](references/feature-b.md)

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

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

1. 告知用户：“SKILL.md 有 {N} 行——已超过建议的 500 行上限，不利于获得最佳性能。”
2. 找出可拆分的部分：详细参考资料、较长示例、高级功能、API 文档
3. 移至参考文件：references/{topic}.md——链接保持在一层深度
4. 在 SKILL.md 中替换为简短摘要和链接：

   **Advanced feature X**: See [references/feature-x.md](references/feature-x.md)
   

5. 为任何超过 100 行的参考文件添加目录

即使少于 500 行，如果某个部分内容独立且只在特定场景下需要，也优先考虑拆分。

步骤 5：验证

定稿前，根据验证清单逐项检查。

命名规则

• 长度：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.

description: Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

避免使用：“帮助处理文档”、“处理数据”、“处理文件相关事务”

核心原则

简洁

上下文窗口由多方共享。逐条审视信息：

• “Claude 真的需要这段解释吗？”
• “我可以假设 Claude 知道这些吗？”
• “这段话的价值是否值得占用这些 token？”

只添加 Claude 尚不了解的上下文。

自由度

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

自由度	适用场景	示例
高（文本说明）	存在多种有效方法，且依赖具体上下文	代码审查指南
中（伪代码/参数）	有首选模式，也允许一定变化	报告生成模板
低（精确脚本）	操作脆弱、一致性至关重要	数据库迁移

渐进式披露

• SKILL.md = 概览 + 导航（目录）
• 参考文件 = 详细内容（按需加载）
• SKILL.md 正文保持在 500 行以内
• 参考文件与 SKILL.md 之间保持一层深度（不嵌套引用）
• 对较长的参考文件（100 行以上）添加目录

术语一致性

选定一个术语并在全文统一使用。不要混用“API endpoint”、“URL”、“API route”和“path”。

模式

带检查清单的工作流

适用于复杂的多步骤操作：

## Workflow

Copy this checklist and track progress:

```
- [ ] Step 1: Analyze input
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
```

反馈循环

运行验证器 → 修复错误 → 重复：

1. Make changes
2. Validate: `python scripts/validate.py`
3. If validation fails: fix issues, return to step 2
4. Only proceed when validation passes

模板模式

提供输出格式模板，并根据需求匹配严格程度。

示例模式

为依赖输出质量的 skills 提供输入/输出示例。

条件工作流

引导用户完成决策：

**Creating new?** → Follow "Creation workflow"
**Editing existing?** → Follow "Editing workflow"

脚本最佳实践

• 明确处理错误 — 不要把问题推给 Claude
• 避免来历不明的常量 — 说明并记录所有数值
• 列出依赖项 — 指明需要安装的包
• 明确说明执行意图：
  • “运行 script.py 提取字段”（执行）
  • “查看 script.py 了解算法”（作为参考阅读）
• 所有文件路径都使用正斜杠（scripts/helper.py，而不是 scripts\helper.py）
• MCP 工具引用 — 使用完全限定名称：ServerName:tool_name

反模式

• 解释 Claude 已经了解的内容（什么是 PDF、库如何工作）
• 提供过多工具／库选项 — 给出默认选项，并提供替代方案
• 时效性信息 — 使用带有 <details> 标签的“旧模式”部分
• 多层嵌套引用（文件 → 文件 → 文件）
• Windows 风格路径
• 假定已安装软件包，却没有明确的安装说明

验证清单

核心质量

• 名称：仅使用小写字母、数字和连字符，长度为 1-64 个字符，不含保留字
• 描述：使用第三人称，具体明确，包含内容和适用时机，少于 1024 个字符
• SKILL.md 正文少于 500 行
• 详细信息放在单独的文件中（仅嵌套一层）
• 不含时效性信息
• 术语始终一致
• 示例具体（而非抽象）
• 适当采用渐进式披露
• 工作流步骤清晰

脚本（如适用）

• 脚本明确处理错误
• 不使用来历不明的常量（所有数值均有说明）
• 列出必需的软件包及安装说明
• 所有路径均使用正斜杠
• 关键操作包含验证／确认步骤
• 对质量要求高的任务设置反馈循环

测试

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

延伸阅读

评估驱动开发：请参阅 references/eval-driven-development.md，了解构建 → 测试 → 观察 → 迭代循环、双 Claude 迭代开发，以及在初次创建后用于改进技能的观察模式。