skill-best-practices

---

技能最佳实践

参考资料：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

说明

第 1 步：确定用例类别

确定你要构建的技能属于哪种类型：

• 文档与素材创建 — 输出一致（文档、设计、代码）
• 工作流自动化 — 采用一致方法的多步骤流程
• MCP 增强 — 在 MCP 工具访问的基础上提供工作流指导

开始编写前，先定义 2–3 个具体用例（参见下方的规划部分）。

第 2 步：创建文件夹和 SKILL.md

• 使用 kebab-case 命名文件夹（例如 my-skill-name）
• 在其中创建文件名大小写敏感的 SKILL.md
• 编写包含 name 和 description 的 YAML frontmatter（参见技术要求）

第 3 步：编写描述——这是最关键的部分

描述决定 Claude 何时加载你的技能。描述必须包含：

• 作用：技能的功能
• 使用时机：具体的触发短语
• 可选：排除触发条件（“请勿用于……”）

请参阅“编写有效的描述”，了解正反示例。

第 4 步：编写正文说明

遵循推荐模板：## Instructions → 编号步骤 → ## Examples → ## Troubleshooting。 内容应具体且可执行。将详细文档移至 references/，并添加链接。

第 5 步：更新 CLAUDE.md 和 README.md

在此仓库中创建或修改任何技能后，务必更新这两个文件中的技能表：

• CLAUDE.md — “Included Skills”下的技能表（Trigger 列：用一句话描述何时触发）
• README.md — “Enthaltene Skills”下的技能表（Beschreibung 列：用德语写一句话）

两个文件必须保持同步。此步骤为必做项，不得跳过。

此外，在此仓库中处理技能时，也要调用 cc-best-practices 技能，确保上下文管理和会话管理符合项目标准。

第 6 步：验证 YAML 和 skills CLI 兼容性

在测试或提交之前，从仓库根目录运行验证脚本：

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh

继续之前，修复所有 FAIL 行。常见问题：

• description 使用了块标量（> 或 |）→ 改为带引号的单行字符串
• 父级映射键下的子键没有缩进 → 增加两个空格的缩进

推送后，还要运行远程检查，确认 npx skills add --list 能找到所有技能：

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote

第 7 步：测试触发和功能行为

运行 10–20 个测试查询。目标：技能在约 90% 的相关查询中触发，且绝不在无关主题上触发。 不断调整描述，直到触发可靠（参见测试方法）。

第 7 步：根据反馈迭代

• 触发不足 → 在描述中增加更多触发短语
• 触发过度 → 添加排除触发条件，缩小范围
• 未遵循说明 → 将关键步骤前置，并使用明确的措辞

---

示例

示例 1：从零开始构建新技能

用户说：“帮我创建一个用于在 Linear 中规划冲刺的技能”

操作：

1. 确定类别：工作流自动化 + MCP 增强
2. 定义用例：触发词 = “plan sprint”“create sprint tasks”；步骤 = 获取 Linear 状态 → 分析速度 → 创建任务
3. 创建文件夹 linear-sprint-planner/SKILL.md
4. 编写描述：“管理 Linear 冲刺规划工作流。当用户说‘plan sprint’‘create sprint tasks’或‘set up iteration’时使用。”
5. 编写分步说明，并包含 Linear MCP 工具调用
6. 使用 10 个触发短语进行测试；如果技能没有自动加载，则调整描述

结果：功能完备的技能，可在收到冲刺规划请求时自动触发，并执行完整工作流，无需用户每次都重新解释步骤。

示例 2：审查现有技能

用户说：“审查我的 SKILL.md 并提出改进建议”

操作：

1. 阅读 SKILL.md 的 frontmatter——检查 name（是否为 kebab-case？）、description（是否包含 WHAT + WHEN？是否少于 1024 个字符？是否包含触发短语？）
2. 检查正文——是否少于 5,000 个单词？指令是否具体且可执行？是否有 Troubleshooting 部分？是否有示例？
3. 模拟触发——description 是否会让 Claude 在遇到合适的查询时加载此技能？
4. 按以下格式报告结果：每项标准标注 PASS / WARN / FAIL

结果：按优先级排列的改进清单，并针对每个问题提供具体修复方案。

示例 3：排查技能未触发的问题

用户说：“我的技能从不自动加载，我总是得手动调用它”

操作：

1. 阅读 description 字段——是否过于宽泛？（“帮助处理项目”不会起作用）
2. 检查是否缺少触发短语——是否包含用户实际会说的词语？
3. 询问 Claude：“你会在什么时候使用 [skill name] 技能？”——Claude 会复述 description，问题所在便一目了然
4. 重写 description，添加具体的触发短语并重新测试

结果：更新后的 description 包含具体触发条件；技能会在相关查询中自动加载。

---

什么是技能？

技能是一个包含以下内容的文件夹：

• SKILL.md（必需）：包含 YAML frontmatter 的 Markdown 指令
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的文档
• assets/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露——分为三个层级：

1. YAML frontmatter：始终包含在系统提示词中；告知 Claude _何时_加载技能
2. SKILL.md 正文：在相关时加载；包含完整指令
3. references/ 中的链接文件：按需加载

可组合性——技能可与其他技能协同工作；不要假设技能具有排他性。

可移植性——在 Claude.ai、Claude Code 和 API 中的运行方式完全一致。

---

规划：从用例开始

开始编写前，先定义 2–3 个具体用例：

Use Case: <name>
Trigger: User says "<phrase>" or "<phrase>"
Steps:
  1. ...
  2. ...
Result: <expected outcome>

问问自己：

• 用户想要完成什么？
• 需要怎样的多步骤工作流？
• 需要哪些工具（内置工具或 MCP 工具）？
• 应嵌入哪些领域知识？

三种技能类别

类别	适用场景	关键技术
文档与素材创建	需要稳定、高质量的输出（文档、设计、代码）	风格指南、模板、质量检查清单
工作流自动化	需要以一致方法处理多步骤流程	分步执行并设置验证关卡、迭代循环
MCP 增强	在 MCP 工具访问的基础上提供工作流指导	顺序调用 MCP、嵌入领域专业知识

---

技术要求

文件和文件夹命名

• 文件夹：只能使用 kebab-case（notion-project-setup）——不得包含空格、下划线或大写字母
• 文件：必须恰好命名为 SKILL.md（区分大小写）——不得使用其他形式
• 技能文件夹内不得包含 README.md（将文档放入 SKILL.md 或 references/）

YAML frontmatter

最低必需格式：

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

name（必需）：

• 使用 kebab-case，不得包含空格或大写字母
• 必须与文件夹名称一致

description（必需）：

• 必须同时包含两项：技能的功能，以及何时使用它（触发条件）
• 少于 1024 个字符
• 不得包含 XML 标签（< 或 >）
• 包含用户实际会说的具体触发短语
• 如果相关，注明文件类型

可选字段：

license: MIT
compatibility: "Requires Python 3.10+"
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name

安全限制——frontmatter 中禁止包含：

• XML 尖括号（< >）
• 包含 “claude” 或 “anthropic” 的名称（保留名称）

---

编写有效的描述

结构：[功能] + [使用时机] + [关键能力]

良好示例：

# Specific and actionable
description: Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files, asks for "design specs", "component
  documentation", or "design-to-code handoff".

# Includes trigger phrases
description: Manages Linear project workflows including sprint planning and
  task creation. Use when user mentions "sprint", "Linear tasks", or asks
  to "create tickets".

不佳示例：

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

---

编写说明（SKILL.md 正文）

建议结构：

# Your Skill Name

## Instructions

### Step 1: [First Major Step]

Clear explanation of what happens.

### Step 2: ...

## Examples

### Example 1: [Common scenario]

User says: "..."
Actions:

1. ...
   Result: ...

## Troubleshooting

### Error: [Common error message]

**Cause:** Why it happens
**Solution:** How to fix

说明的最佳实践

具体且可执行：

# Good
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues:
- Missing required fields (add to CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

包含错误处理——记录常见错误及其原因和解决方案。

清晰地引用随附资源：

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns

采用渐进式披露——让 SKILL.md 专注于核心说明；将详细文档移至 references/ 并链接到这些文档。SKILL.md 应少于 5,000 个单词。

对于关键验证，优先使用随附脚本，而非自然语言说明——代码具有确定性，自然语言解读则不然。

---

测试方法

1. 触发测试

运行 10–20 个查询。技能应在约 90% 的相关查询中触发，并且不应在无关主题中触发。

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"

**调试：**询问 Claude“你会在什么时候使用 [skill name] 技能？”——它会引用描述作为回答。

2. 功能测试

• 生成有效输出
• API 调用成功
• 错误处理正常
• 覆盖边缘情况

3. 性能对比

对比使用和不使用技能时的 token 数量、工具调用次数以及来回交互消息数。

**专业提示：**针对单个有挑战性的任务反复迭代，直到 Claude 成功，然后将有效方法提炼到技能中。

---

故障排除

技能无法上传

错误	原因	修复方法
"Could not find SKILL.md"	文件名错误	将文件名精确改为 SKILL.md
"Invalid frontmatter"	YAML 格式问题	添加 --- 分隔符，并闭合引号
"Invalid skill name"	名称中含空格或大写字母	使用 kebab-case

技能未触发（触发不足）

• 描述过于笼统
• 缺少用户实际会使用的触发短语
• 缺少相关文件类型说明

**修复方法：**在描述中添加更具体的关键词和短语。

技能触发过于频繁（过度触发）

添加否定触发条件并缩小范围：

description: Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration.

未遵循说明

1. 过于冗长——保持简洁，使用项目符号，将详细内容移至 references/
2. 说明埋得太深——将关键说明放在顶部，使用 ## Critical 标题
3. 措辞含糊——明确表达：“CRITICAL: 在调用 X 之前，请验证：……”
4. 模型偷懒——将以下内容添加到用户提示词中（比写在 SKILL.md 中更有效）：“请从容作答，质量优先于速度，不要跳过验证步骤”

上下文过长 / 响应缓慢

• 将详细文档移至 references/
• SKILL.md 应少于 5,000 个单词
• 减少同时启用的技能数量（如果超过 20–50 个，请评估是否需要全部启用）

---

工作流模式

五种模式适用于大多数技能类型：顺序编排、多 MCP 协调、迭代优化、上下文感知的工具选择，以及特定领域智能。

如需各模式的详细示例和实现模板，请参阅 references/patterns.md。

---

快速检查清单

开始之前：

• 确定 2–3 个具体用例
• 确定工具（内置工具或 MCP 工具）
• 规划文件夹结构

开发过程中：

• 文件夹名称采用 kebab-case
• 存在 SKILL.md（拼写完全一致，区分大小写）
• YAML frontmatter 使用 --- 分隔符
• name：采用 kebab-case，不含空格或大写字母
• description 包含内容和适用时机
• 不含任何 XML 标签（< >）
• 说明清晰且可执行
• 包含错误处理
• 提供示例
• 清晰链接参考资料

仓库同步（此仓库必须执行）：

• 更新 CLAUDE.md 技能表
• 更新 README.md 技能表
• 本次会话中已加载 cc-best-practices 技能
• 已运行 validate-skills.sh — 没有 FAIL 行
• 推送后：运行 validate-skills.sh --remote — npx skills 找到所有技能

上传之前：

• 对明显的任务触发
• 对改述后的请求触发
• 不会对无关主题触发
• 功能测试通过

上传之后：

• 在真实对话中测试
• 监控触发不足或过度触发的情况
• 迭代优化说明和指令