creating-effective-skills

创建有效的技能

创建符合 Claude 官方最佳实践的 Agent 技能指南。

核心原则

简洁至关重要：上下文窗口由大家共享。只添加 Claude 尚不了解的内容。默认假设：Claude 已经非常聪明。

渐进式披露：技能分三个层级加载：

1. 元数据（约 100 个 token）——始终加载
2. SKILL.md 正文（少于 5k 个 token）——触发时加载
3. 捆绑资源——按需加载

保持 SKILL.md 简洁：目标约 200 行，最多 500 行。详细内容应尽可能移至参考文件。

单一职责：每项技能只做好一件事。

工作流

步骤 1：了解技能需求

请用户进一步说明（根据具体情况调整问题）：

对于明确的请求（例如，“格式化 Markdown 表格”）：

• “应支持哪些输入格式？”
• “你对输出有什么偏好？”
• “需要处理哪些边缘情况？”

对于模糊的请求（例如，“处理数据”、“帮助处理文件”）：

• “具体是哪类数据/文件？”（格式、来源、结构）
• “需要执行哪些操作？”（转换、验证、迁移、分析）
• “需要解决的具体问题是什么？”
• 继续之前至少提出 3 个具体问题

需要额外澄清的危险信号：

• 含糊的动词：“处理”、“管理”、“帮助”
• 宽泛的名词：没有具体说明的数据、文件、文档

明确了解以下内容：目的、使用示例、触发条件，以及范围边界。

步骤 2：验证范围

继续之前，确认技能是否符合单一职责：

检查命名：

• ❌ handling-data——范围太广，是什么数据？要如何处理？
• ❌ data-helper——过于笼统，目的不清晰
• ✅ transforming-csv-data——具体操作 + 数据类型
• ✅ validating-json-schemas——单一目的明确

检查边界：

• 能否清楚说明范围内和范围外的内容？
• 如果边界不清楚，说明范围太广 → 请用户缩小范围

如果范围太广：

1. 提出一个聚焦的替代方案（例如，将“处理数据”改为“transforming-csv-data”）
2. 说明排除哪些内容以及原因
3. 如有需要，建议拆分为多项技能

范围验证通过前，不要创建文件。

步骤 3：确定自由度

自由度决定 Claude 遵循技能时有多大的灵活空间：

• 高：存在多种有效方法，决策取决于上下文
• 中：有首选模式，可接受一定变化
• 低：操作脆弱，一致性至关重要

除非自由度明确为低：阅读 references/degrees-of-freedom.md，并应用其中的决策框架。在说明理由时，引用以下因素：脆弱性、上下文依赖性、一致性、错误影响。

如果阅读参考资料后仍不确定，请询问用户。

步骤 4：规划可复用内容

确定要包含的内容：

脚本（scripts/）：用于确定性操作的可执行代码 参考资料（references/）：按需加载的文档 资源文件（assets/）：用于输出的文件（模板、图片、字体）

步骤 5：创建结构

skill-name/
├── SKILL.md (required - AI agent instructions)
├── README.md (optional - human-facing installation and usage guide)
├── references/ (optional)
├── tests/
│   └── scenarios.md (optional - self-evaluation scenarios)
├── scripts/ (optional)
└── assets/ (optional)

README.md 与 SKILL.md 的区别：

• SKILL.md：面向 Claude 的说明（工作流、模式、技术细节）
• README.md：面向用户的说明（安装、权限、概述）

如包含 README.md，应包括：

• 技能功能概述
• 文件结构说明（尤其是 tests/scenarios.md 的用途）
• 安装说明和所需权限

避免创建：INSTALLATION_GUIDE.md、CHANGELOG.md 或其他重复文档。使用 README.md 编写面向用户的文档。

步骤 6：编写 SKILL.md

Frontmatter

---
name: skill-name
description: What the skill does and when to use it
---

命名（使用动名词形式）：

• 推荐：processing-pdfs、analyzing-spreadsheets、managing-databases
• 避免：helper、utils、tools、anthropic-*、claude-*

描述（使用第三人称，说明内容和适用场景）：

• 推荐："从 PDF 文件中提取文本和表格、填写表单、合并文档。在处理 PDF 文件，或用户提到 PDF、表单或文档提取时使用。"
• 避免："帮助处理文档"、"处理数据"

描述应具体并包含关键术语。描述是主要的触发机制。

正文

使用祈使句。保持简短（目标约 200 行，最多 500 行）。仅包含：

• 快速入门／基本用法
• 核心工作流
• 对其他文件的引用

对于复杂的多步骤流程，请参阅 references/workflows-and-validation.md。

示例模式：

## Quick start
[Basic usage]

## Advanced features
**Feature A**: See [references/feature-a.md](references/feature-a.md)
**Feature B**: See [references/feature-b.md](references/feature-b.md)

引用内容保持一层深度。模式请参阅 references/progressive-disclosure.md。

步骤 7：创建参考文件

对于超过 100 行的文件，请在顶部添加目录。

适当时按领域组织：

skill/
├── SKILL.md
└── references/
    ├── domain_a.md
    └── domain_b.md

避免：多层嵌套的参考内容、重复信息、通用文件名。

步骤 8：创建测试场景（可选）

询问用户："是否要为此技能创建测试场景？测试场景可通过 /evaluating-skills-with-models 进行自动评估，以衡量技能在不同模型（sonnet、opus、haiku）上的质量。"

如果用户同意，请创建 tests/scenarios.md 用于自我评估：

## Scenario: [Name]

**Difficulty:** Easy | Medium | Hard | Edge-case

**Query:** User request that triggers this skill

**Expected behaviors:**

1. [Action description]
   - **Minimum:** What counts as "did it"
   - **Quality criteria:** What "did it well" looks like
   - **Haiku pitfall:** Common failure mode for smaller models
   - **Weight:** 1-5 (importance)

**Output validation:** (optional)
- Pattern: `regex`
- Line count: `< N`

此格式的原因：二元的通过／失败结果无法区分模型。基于质量的评分可以揭示能力差异。

步骤 9：定义 allowed-tools

完成 SKILL.md 和参考文件后，确定此技能使用的工具：

1. 检查 SKILL.md 和参考文件中的工具使用情况
2. 列出需要预先批准的工具（例如，Bash(git status:*)、WebSearch、Skill(other-skill)）
3. 如有需要，在 frontmatter 中添加 allowed-tools 字段

---
name: skill-name
description: ...
allowed-tools: "Bash(git status:*) Bash(git diff:*) WebSearch"
---

此字段仍处于实验阶段，但有助于 Agent 预先批准工具访问权限。

重要注意事项：

• Read、Glob 默认已获允许——请勿添加
• Edit、Write 具有破坏性——请勿预先批准
• 尽可能具体地指定 Bash 子命令
  • 推荐：Bash(git status:*) Bash(git diff:*) Bash(git log:*)
  • 避免：Bash(git:*)（范围过宽，包含 git push --force 等破坏性操作）

反模式

❌ Windows 风格路径（scripts\file.py） ❌ 没有默认选项，却提供过多选项 ❌ 时效性信息 ❌ 术语不一致 ❌ 多层嵌套的参考内容 ❌ 含糊的指令

参考资料

渐进式披露：references/progressive-disclosure.md - 详细模式和示例

自由度：references/degrees-of-freedom.md - 关于适当自由度的指南

工作流与验证：references/workflows-and-validation.md - 创建包含验证和反馈循环的工作流