Skill Builder 是一个用于创建和校验 Agent Skills 的工具，目标是帮助用户构建聚焦、可被发现的技能，用清晰的描述和渐进式披露模式解决特定问题。
用途
Skill Builder 面向需要构建自定义 Agent Skill 的场景，包括：构建自定义技能、测试技能发现、设计新技能。其核心目标是让技能具备明确的问题定位和有效的触发描述，从而被正确识别和调用。
工作流程
1. 设计技能
在动手构建前，需要先明确以下问题：
- What（做什么）：这个技能解决什么具体问题？
- When（何时用）：哪些触发短语会让 Claude 使用它？（3-5 个具体短语）
- Scope（范围）：是单一能力还是多个相关特性？
- Location（位置）：个人目录（~/.claude/skills/）还是项目目录（.claude/skills/）？
示例：
- What：从 git diff 生成清晰的提交信息
- When：用户想创建提交、审查已暂存变更、解释代码变更
- Scope：单一能力（仅提交信息，不含其他 git 任务）
- Location：个人目录（跨项目可用）
2. 撰写描述
描述公式为：<做什么>。当 <触发条件1> 或 <触发条件2> 或 <触发条件3> 时使用。
- 好的示例：从 git diff 生成清晰的提交信息。当创建提交、审查已暂存变更，或解释代码中发生了哪些变化时使用。
- 较弱的示例：帮助处理 git（过于模糊，没有触发条件）。
有效的触发词类型：
- 动作动词：extract、analyze、generate、review、validate、debug、migrate
- 文件类型：PDF、.xlsx、Python files、YAML
- 领域术语：commits、staging、forms、spreadsheets、SwiftUI
长度限制：名称最多 64 字符，描述最多 1024 字符。
3. 创建目录结构
最小技能（单一聚焦任务）：
my-skill/
└── SKILL.md
需要支持文件的技能：
my-skill/
├── SKILL.md (main instructions - keep <200 lines)
└── REFERENCE.md (detailed patterns, examples)
4. 编写 SKILL.md
最小模板（200 行以内）：
---
name: Your Skill Name
description: What it does and when to use. [Include 3-5 trigger phrases]
---
# Your Skill Name
## Quick Start
[One-paragraph overview of what this skill does]
## Instructions
1. Understand the requirement: [Ask clarifying questions]
2. [Core step with specific approach]
3. [Next step]
4. [Final step with verification]
## Examples
[2-3 concrete, realistic examples]
## Best Practices
- Do X in situation Y
- Avoid Z because...
- Use this pattern when...
5. 校验技能质量
结构检查清单：
- YAML frontmatter 有效（第 1 行和内容前均有 ---）
- name 少于 64 字符
- description 少于 1024 字符
- description 包含 3-5 个触发短语并覆盖“做什么”和“何时用”
- Markdown 语法正确（# 用于标题，``` 用于代码块）
- 引用的文件都存在于技能目录中
发现性检查清单：
- description 不能用来描述另一个不同的技能
- 触发词与用户实际表述问题的方式一致
- 3-5 个具体术语，而非泛化语言
- 与相关技能有清晰区分
功能检查清单：
- 指令是分步且清晰的
- 示例具体而非抽象
- 记录了边界情况或限制
- 工作流聚焦于单一能力
6. 测试发现
生成 2-3 个与描述匹配的自然提示。
以“Commit Message Generator”为例：
- 适合：“Write a commit message for these staged changes”
- 适合：“Help me create a clear git commit”
- 适合：“I need to describe what I just changed”
- 不适合：“Analyze my code”（属于其他技能的领域）
以“SwiftUI Engineer”为例：
- 适合：“Review my SwiftUI code for anti-patterns”
- 适合：“Debug this view rendering issue”
- 适合：“Help me migrate this from AppKit to SwiftUI”
- 不适合：“Write Python code”（领域不符）
7. 常见模式
- 单一能力技能：一个具体任务（提交信息、PDF 提取）
- 多模式技能：一个统一下的相关能力
- SwiftUI Engineer：架构、审查、调试、现代化
- 主文件保持 150-200 行，详细模式放在 REFERENCE.md
- 主文件说明“何时使用哪个模式”
结构参考
最小单文件结构：
适用场景：指令简单的聚焦技能
skill/
└── SKILL.md (100-150 lines)
带渐进式披露的结构：
适用场景：相关能力较多或示例丰富
skill/
├── SKILL.md (150-200 lines with quick patterns)
└── REFERENCE.md (300-400 lines with detailed examples and TOC)
核心原则
- 聚焦范围：一个技能 = 一个主要能力或一组相关能力
- 具体触发：包含用户实际会说的领域术语
- 渐进式披露：仅在需要时加载细节（使用 REFERENCE.md）
- 具体示例：展示真实场景，而非抽象概念
- 单层引用：所有引用从 SKILL.md 指向支持文件即可
- 无重复：不要跨技能重复模式
需要避免的反模式
- 过度堆叠：“做提交、审查代码、分析数据、生成文档……”→ 拆分为多个聚焦技能
- 触发模糊：“帮助处理东西”“通用目的”→ 添加 3-5 个具体领域术语
- 嵌套引用：SKILL.md → REFERENCE.md → DETAILS.md → 保持引用扁平（仅一层深）
- 营销化语言：“效果惊人的神奇工具！”→ 具体说明它做什么
何时迭代
如果 Claude 未在预期时使用你的技能：
- 首先检查 YAML 语法（最常见问题）
- 在 description 中添加更具体的触发词
- 确认 description 覆盖“做什么”和“何时用”
- 用自然语言表述进行测试
- 确保触发词与用户词汇一致