Skill 编写最佳实践

核心思想

好的 Skill 简洁、结构良好、并经真实使用检验。三条核心原则：简洁——上下文窗口是公共资源，只补充 Claude 尚不具备的信息；恰当的自由度——按任务的脆弱性匹配指令的具体程度（开阔田野给方向，悬崖窄桥给精确护栏）；渐进式披露——SKILL.md 当目录，引用文件只保持一层深、按需加载。开发方法上主张「先建评估、再写文档」，并用「Claude A 设计 / Claude B 测试」的循环在真实使用中迭代打磨。

好的 Skill 简洁、结构良好，并经过真实使用的检验。本指南给出一系列实用的编写决策，帮助你写出 Claude 能够发现并有效使用的 Skill。

关于 Skill 工作原理的概念性背景，参见 Skills 概览。

核心原则

简洁是关键

上下文窗口是一项公共资源。你的 Skill 与 Claude 需要知道的所有其它内容共享这个上下文窗口，包括：

系统提示词
对话历史
其它 Skill 的元数据
你当下的实际请求

并非 Skill 中的每个 token 都有即时成本。启动时，只有所有 Skill 的元数据（name 和 description）会被预加载。只有当某个 Skill 变得相关时，Claude 才会读取它的 SKILL.md，并且仅在需要时才读取额外文件。不过，让 SKILL.md 保持简洁仍然重要：一旦 Claude 加载了它，其中每个 token 都要与对话历史和其它上下文争抢空间。

默认假设： Claude 已经非常聪明

只补充 Claude 尚不具备的上下文。对每一条信息都要追问：

「Claude 真的需要这段解释吗？」
「我能否假定 Claude 已经知道这一点？」
「这一段值不值得它所占的 token 成本？」

正面示例：简洁（约 50 个 token）：

## Extract PDF text

Use pdfplumber for text extraction:

\`\`\`python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

反面示例：过于啰嗦（约 150 个 token）：

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

简洁版本假定 Claude 知道 PDF 是什么、库如何运作。

设定恰当的自由度

让具体程度与任务的脆弱性和多变性相匹配。

高自由度（基于文本的指令）：

适用于：

多种做法都行得通
决策取决于上下文
用启发式经验来引导做法

示例：

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

中自由度（伪代码，或带参数的脚本）：

适用于：

已存在一种首选模式
允许一定程度的变化
配置会影响行为

示例：

## Generate report

Use this template and customize as needed:

\`\`\`python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
\`\`\`

低自由度（具体脚本，参数很少或没有）：

适用于：

操作脆弱、容易出错
一致性至关重要
必须遵循特定的步骤顺序

示例：

## Database migration

Run exactly this script:

\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`

Do not modify the command or add additional flags.

类比： 把 Claude 想象成一个在路径上探索的机器人：

两侧是悬崖的窄桥： 只有一条安全的前进方式。请提供具体的护栏和精确的指令（低自由度）。例如：必须按确切顺序运行的数据库迁移。
没有任何危险的开阔田野： 多条路径都能抵达成功。给出大致方向，并信任 Claude 去找到最佳路线（高自由度）。例如：由上下文决定最佳做法的代码审查。

用你计划使用的所有模型测试

Skill 是对模型的增补，因此其效果取决于底层模型。请用你计划搭配使用的所有模型来测试你的 Skill。

按模型划分的测试考量：

Claude Haiku（快速、经济）：Skill 提供的指引是否充分？
Claude Sonnet（均衡）：Skill 是否清晰高效？
Claude Opus（强大的推理能力）：Skill 是否避免了过度解释？

对 Opus 完美适用的内容，对 Haiku 可能需要更多细节。如果你打算让 Skill 跨多个模型使用，目标应是写出对所有模型都好用的指令。

Skill 结构

YAML frontmatter： SKILL.md 的 frontmatter 需要两个字段：

name：

最多 64 个字符
只能包含小写字母、数字和连字符
不能包含 XML 标签
不能包含保留词：「anthropic」、「claude」

description：

不能为空
最多 1024 个字符
不能包含 XML 标签
应当说明这个 Skill 做什么、以及何时使用它

关于 Skill 结构的完整细节，参见 Skills 概览。

命名约定

使用一致的命名模式，让 Skill 更容易被引用和讨论。可以考虑为 Skill 名称采用动名词形式（动词 + -ing），因为它能清晰地描述该 Skill 所提供的活动或能力。

记住，name 字段只能使用小写字母、数字和连字符。

好的命名示例（动名词形式）：

processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

可接受的替代形式：

名词短语：pdf-processing、spreadsheet-analysis
动作导向：process-pdfs、analyze-spreadsheets

应避免：

含糊的名称：helper、utils、tools
过于宽泛：documents、data、files
保留词：anthropic-helper、claude-tools
在你的 Skill 集合内命名模式不一致

一致的命名让以下事情更容易：

在文档和对话中引用 Skill
一眼看出某个 Skill 的用途
组织和检索多个 Skill
维护一个专业、连贯的 Skill 库

编写有效的 description

description 字段决定了 Skill 能否被发现，应同时包含这个 Skill 做什么、以及何时使用它。

始终用第三人称书写。description 会被注入系统提示词，视角不一致会引发发现问题。

好：「Processes Excel files and generates reports」
避免：「I can help you process Excel files」
避免：「You can use this to process Excel files」

要具体，并包含关键术语。既要写清这个 Skill 做什么，也要写清何时使用它的具体触发条件和场景。

每个 Skill 只有一个 description 字段。description 对于 Skill 的选择至关重要：Claude 要靠它从可能多达 100 多个的可用 Skill 中挑出正确的那个。你的 description 必须提供足够的细节，让 Claude 知道何时该选用这个 Skill，而 SKILL.md 的其余部分则提供实现细节。

有效的示例：

PDF 处理 Skill：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Excel 分析 Skill：

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Git 提交助手 Skill：

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

避免这类含糊的 description：

description: Helps with documents

description: Processes data

description: Does stuff with files

SKILL.md 的角色是一份概览，按需把 Claude 指引到详细材料，就像新人上手指南里的目录。关于渐进式披露如何运作的解释，参见概览中的 Skill 工作原理。

实用建议：

让 SKILL.md 正文保持在 500 行以内，以获得最佳性能
接近这个上限时，把内容拆分到独立文件中
用下文介绍的模式来有效地组织指令、代码和资源

直观概览：从简单到复杂

一个基础的 Skill 起步时只需一个 SKILL.md 文件，其中包含元数据和指令：

随着 Skill 不断扩充，你可以捆绑额外内容，让 Claude 仅在需要时才加载：

一个完整的 Skill 目录结构可能是这样：

pdf/
├── SKILL.md              # Main instructions (loaded when triggered)
├── FORMS.md              # Form-filling guide (loaded as needed)
├── reference.md          # API reference (loaded as needed)
├── examples.md           # Usage examples (loaded as needed)
└── scripts/
    ├── analyze_form.py   # Utility script (executed, not loaded)
    ├── fill_form.py      # Form filling script
    └── validate.py       # Validation script

模式 1：高层指南配引用文件

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude 仅在需要时才加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于横跨多个领域的 Skill，按领域组织内容，以避免加载不相关的上下文。当用户询问销售指标时，Claude 只需读取与销售相关的 schema，而无需读取财务或市场营销数据。这能把 token 用量压低、让上下文保持聚焦。

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

\`\`\`bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
\`\`\`

模式 3：条件式细节

展示基础内容，把进阶内容链接出去：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude 仅在用户需要那些功能时，才会读取 REDLINING.md 或 OOXML.md。

避免深层嵌套引用

当文件是从另一个被引用的文件中再被引用时，Claude 可能只会部分读取这些文件。遇到嵌套引用时，Claude 可能会用 head -100 之类的命令预览内容，而不是读取整个文件，从而导致信息不完整。

让引用层级从 SKILL.md 算起只保持一层深。所有引用文件都应直接从 SKILL.md 链接出去，以确保 Claude 在需要时会读取完整文件。

反面示例：层级太深：

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

正面示例：只有一层深：

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

对于超过 100 行的引用文件，在顶部加上一个目录。这样即便 Claude 用部分读取的方式预览，也能看到可用信息的完整范围。

示例：

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

这样 Claude 就可以读取完整文件，或按需跳转到特定章节。

关于这种基于文件系统的架构如何实现渐进式披露，参见下文进阶部分的运行时环境一节。

对复杂任务使用工作流

把复杂操作拆解成清晰、有序的步骤。对于特别复杂的工作流，提供一份清单，让 Claude 可以复制进自己的回复，并在推进过程中逐项勾选。

示例 1：研究综合工作流（适用于不含代码的 Skill）：

## Research synthesis workflow

Copy this checklist and track your progress:

\`\`\`
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
\`\`\`

**Step 1: Read all source documents**

Review each document in the \`sources/\` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

这个示例展示了工作流如何应用于不需要代码的分析任务。清单这一模式适用于任何复杂、多步骤的流程。

示例 2：PDF 表单填写工作流（适用于含代码的 Skill）：

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

\`\`\`
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
\`\`\`

**Step 1: Analyze the form**

Run: \`python scripts/analyze_form.py input.pdf\`

This extracts form fields and their locations, saving to \`fields.json\`.

**Step 2: Create field mapping**

Edit \`fields.json\` to add values for each field.

**Step 3: Validate mapping**

Run: \`python scripts/validate_fields.py fields.json\`

Fix any validation errors before continuing.

**Step 4: Fill the form**

Run: \`python scripts/fill_form.py input.pdf fields.json output.pdf\`

**Step 5: Verify output**

Run: \`python scripts/verify_output.py output.pdf\`

If verification fails, return to Step 2.

清晰的步骤能防止 Claude 跳过关键的校验环节。这份清单既帮助 Claude、也帮助你跟踪多步骤工作流的进度。

常见模式： 运行校验器 → 修复错误 → 重复

这一模式能极大提升输出质量。

示例 1：风格指南合规检查（适用于不含代码的 Skill）：

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

这展示了用引用文档而非脚本来实现校验循环的模式。这里的「校验器」是 STYLE_GUIDE.md，Claude 通过阅读和比对来完成检查。

示例 2：文档编辑流程（适用于含代码的 Skill）：

## Document editing process

1. Make your edits to \`word/document.xml\`
2. **Validate immediately**: \`python ooxml/scripts/validate.py unpacked_dir/\`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: \`python ooxml/scripts/pack.py unpacked_dir/ output.docx\`
6. Test the output document

校验循环能尽早捕获错误。

内容指南

避免时效性信息

不要纳入会过时的信息：

反面示例：有时效性（终将变得不正确）：

If you're doing this before August 2025, use the old API.
After August 2025, use the new API.

正面示例（使用「旧模式」小节）：

## Current method

Use the v2 API endpoint: \`api.example.com/v2/messages\`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: \`api.example.com/v1/messages\`

This endpoint is no longer supported.
</details>

「旧模式」小节提供了历史背景，又不会让主要内容变得杂乱。

使用一致的术语

选定一个术语，并在整个 Skill 中始终如一地使用它：

好——一致：

始终用「API endpoint」
始终用「field」
始终用「extract」

坏——不一致：

混用「API endpoint」、「URL」、「API route」、「path」
混用「field」、「box」、「element」、「control」
混用「extract」、「pull」、「get」、「retrieve」

一致性有助于 Claude 理解并遵循指令。

常见模式

模板模式

为输出格式提供模板。让严格程度与你的需求相匹配。

对于严格要求（比如 API 响应或数据格式）：

## Report structure

ALWAYS use this exact template structure:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
\`\`\`

对于灵活的指引（当适当变通有益时）：

## Report structure

Here is a sensible default format, but use your best judgment based on the analysis:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]
\`\`\`

Adjust sections as needed for the specific analysis type.

示例模式

对于那些输出质量取决于能否看到范例的 Skill，请像在常规提示词中那样，提供输入/输出配对：

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
\`\`\`
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
\`\`\`

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
\`\`\`
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
\`\`\`

**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
\`\`\`
chore: update dependencies and refactor error handling

- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
\`\`\`

Follow this style: type(scope): brief description, then detailed explanation.

相比单纯的描述，示例能让 Claude 更清楚地理解所期望的风格和细节程度。

条件式工作流模式

引导 Claude 走过各个决策点：

## Document modification workflow

1. Determine the modification type:

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

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete

如果工作流变得庞大或复杂、步骤繁多，可以考虑把它们拆进独立文件，并告诉 Claude 根据手头任务读取相应的文件。

评估与迭代

先构建评估

在编写大量文档之前，先创建评估。 这能确保你的 Skill 解决的是真实问题，而不是为想象出来的问题写文档。

评估驱动的开发：

找出缺口： 在没有 Skill 的情况下，让 Claude 跑一遍有代表性的任务。记录下具体的失败之处或缺失的上下文
创建评估： 构建三个用来测试这些缺口的场景
建立基线： 测量 Claude 在没有 Skill 时的表现
编写最小化指令： 只写出刚好够用、足以填补缺口并通过评估的内容
迭代： 执行评估，与基线对比，并加以打磨

这种做法能确保你解决的是实际存在的问题，而不是在预判可能永远不会出现的需求。

评估的结构：

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

这个示例演示了一个数据驱动的评估，配有一份简单的测试评分标准。目前还没有内置的方式来运行这些评估。用户可以创建自己的评估系统。评估是你衡量 Skill 效果的事实依据。

与 Claude 协作迭代式地开发 Skill

最有效的 Skill 开发流程会让 Claude 自己参与进来。你与一个 Claude 实例（「Claude A」）协作，去创建一个供其它实例（「Claude B」）使用的 Skill。Claude A 帮你设计和打磨指令，而 Claude B 在真实任务中测试它们。这之所以行得通，是因为 Claude 模型既懂如何写出有效的智能体指令，也懂智能体需要哪些信息。

创建一个新 Skill：

不用 Skill 完成一项任务： 用常规提示词，与 Claude A 一起把一个问题做完。在过程中，你会很自然地提供上下文、解释偏好、分享流程性知识。留意你反复提供了哪些信息。
识别可复用的模式： 任务完成后，找出你提供过的、对未来类似任务也有用的上下文。
示例： 如果你做完了一次 BigQuery 分析，你可能提供过表名、字段定义、过滤规则（比如「始终排除测试账户」）以及常用查询模式。
请 Claude A 创建一个 Skill：「创建一个 Skill，把我们刚才用到的这套 BigQuery 分析模式固化下来。包含表 schema、命名约定，以及关于过滤测试账户的那条规则。」
Claude 模型天生就懂 Skill 的格式和结构。你不需要特殊的系统提示词，也不需要一个「编写 skill」的 skill，就能让 Claude 帮你创建 Skill。只需直接请 Claude 创建一个 Skill，它就会生成结构正确的 SKILL.md 内容，带有恰当的 frontmatter 和正文。
检查是否简洁： 检查 Claude A 有没有添加不必要的解释。可以这样要求：「去掉关于 win rate 含义的解释——Claude 已经知道那个了。」
改进信息架构： 请 Claude A 把内容组织得更有效。比如：「把这个重新组织一下，让表 schema 放进一个单独的引用文件。我们以后可能会加更多表。」
在类似任务上测试： 在相关用例上，用 Claude B（一个加载了该 Skill 的全新实例）来使用这个 Skill。观察 Claude B 是否找到了正确的信息、是否正确应用了规则、是否成功完成了任务。
根据观察迭代： 如果 Claude B 遇到困难或漏掉了什么，带着具体情况回到 Claude A：「Claude 用这个 Skill 时，忘了按日期过滤 Q4。我们要不要加一个关于日期过滤模式的小节？」

迭代改进现有 Skill：

改进 Skill 时，同样的分层模式仍然延续。你在以下三者之间交替：

与 Claude A 协作（帮你打磨 Skill 的专家）
用 Claude B 测试（使用该 Skill 去完成真实工作的智能体）
观察 Claude B 的行为，并把洞察带回给 Claude A

在真实工作流中使用这个 Skill： 给 Claude B（已加载该 Skill）真实的任务，而不是测试场景
观察 Claude B 的行为： 留意它在哪里遇到困难、哪里做得好、哪里做出了意料之外的选择
观察示例：「我让 Claude B 出一份区域销售报告时，它写了查询，但忘了过滤掉测试账户，尽管 Skill 里提到了这条规则。」
回到 Claude A 进行改进： 分享当前的 SKILL.md，并描述你观察到的情况。可以问：「我注意到，我让 Claude B 出区域报告时，它忘了过滤测试账户。Skill 里提到了过滤，但也许它不够显眼？」
审视 Claude A 的建议： Claude A 可能会建议重新组织内容、让规则更醒目，使用更强硬的措辞——比如用「MUST filter」而不是「always filter」，或者重构工作流小节。
应用并测试改动： 用 Claude A 的打磨成果更新 Skill，然后再用 Claude B 在类似请求上测试
根据使用情况重复： 随着你遇到新场景，持续这个「观察—打磨—测试」的循环。每一次迭代都基于真实的智能体行为来改进 Skill，而不是基于假设。

收集团队反馈：

把 Skill 分享给队友，并观察他们的使用情况
询问：Skill 是否在预期时机被激活？指令是否清晰？缺了什么？
把反馈吸收进来，弥补你自己使用模式中的盲区

这种做法为何有效： Claude A 懂智能体的需求，你提供领域专长，Claude B 通过真实使用暴露出缺口，而迭代式打磨基于观察到的行为、而非假设来改进 Skill。

在迭代改进 Skill 时，要关注 Claude 在实践中究竟如何使用它们。注意观察：

意料之外的探索路径： Claude 读取文件的顺序，是否和你预想的不一样？这可能意味着你的结构并不像你以为的那样直观
错失的关联： Claude 是否没能顺着引用找到重要文件？你的链接也许需要更明确、更醒目
过度依赖某些小节： 如果 Claude 反复读取同一个文件，考虑一下那部分内容是否应该直接放进主 SKILL.md
被忽略的内容： 如果 Claude 从不访问某个捆绑文件，它也许是多余的，或者在主指令里的信号给得不够

基于这些观察来迭代，而不是基于假设。Skill 元数据中的 name 和 description 尤其关键。Claude 在判断是否要为当前任务触发某个 Skill 时，会用到它们。务必让它们清晰地说明这个 Skill 做什么、以及何时应当使用它。

应避免的反模式

避免 Windows 风格的路径

在文件路径中始终使用正斜杠，即便是在 Windows 上：

✓ 好： scripts/helper.py、reference/guide.md
✗ 避免： scripts\helper.py、reference\guide.md

Unix 风格的路径在所有平台上都能用，而 Windows 风格的路径在 Unix 系统上会引发错误。

避免提供过多选项

非必要时，不要呈现多种做法：

**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
\`\`\`

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

进阶：含可执行代码的 Skill

下面几节聚焦于包含可执行脚本的 Skill。如果你的 Skill 只用到 Markdown 指令，可以直接跳到有效 Skill 检查清单。

解决问题，别甩锅

为 Skill 编写脚本时，要处理好错误情况，而不是把问题甩给 Claude。

正面示例：显式处理错误：

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ""

反面示例：甩锅给 Claude：

def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()

配置参数同样应当有理有据并配有文档，以避免「巫毒常量」（Ousterhout 定律）。如果连你都不知道正确的值是多少，Claude 又怎么能确定它呢？

正面示例：自带文档：

# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3

反面示例：魔法数字：

TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 5?

提供工具脚本

即便 Claude 自己也能写出脚本，预先备好的脚本仍有其优势：

工具脚本的好处：

比生成的代码更可靠
节省 token（无需把代码纳入上下文）
节省时间（无需生成代码）
确保多次使用之间的一致性

上面的示意图展示了可执行脚本如何与指令文件协同工作。指令文件（forms.md）引用了脚本，Claude 可以执行它，而无需把它的内容加载进上下文。

重要区别： 在你的指令中要讲清楚，Claude 应该：

执行该脚本（最常见）：「运行 analyze_form.py 来提取字段」
把它当作参考来阅读（针对复杂逻辑）：「关于字段提取算法，参见 analyze_form.py」

对于大多数工具脚本，执行是更可取的，因为它更可靠、更高效。关于脚本执行如何运作的细节，参见下文的运行时环境一节。

示例：

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

\`\`\`bash
python scripts/analyze_form.py input.pdf > fields.json
\`\`\`

Output format:
\`\`\`json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
\`\`\`

**validate_boxes.py**: Check for overlapping bounding boxes

\`\`\`bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
\`\`\`

**fill_form.py**: Apply field values to PDF

\`\`\`bash
python scripts/fill_form.py input.pdf fields.json output.pdf
\`\`\`

使用视觉分析

当输入可以被渲染成图像时，让 Claude 去分析它们：

## Form layout analysis

1. Convert PDF to images:
   \`\`\`bash
   python scripts/pdf_to_images.py form.pdf
   \`\`\`

2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

在这个示例中，你需要自己编写 pdf_to_images.py 脚本。

Claude 的视觉能力有助于理解版式和结构。

创建可验证的中间产物

当 Claude 执行复杂、开放式的任务时，它可能会出错。「计划-校验-执行」模式能尽早捕获错误：让 Claude 先以结构化格式创建一份计划，再用脚本校验这份计划，然后才执行它。

示例： 设想你让 Claude 根据一份电子表格更新某个 PDF 中的 50 个表单字段。没有校验，Claude 可能会引用不存在的字段、产生相互冲突的值、漏掉必填字段，或者错误地施加更新。

解决办法： 使用上文展示过的工作流模式（PDF 表单填写），但额外加入一个 changes.json 中间文件，在施加改动前先对它做校验。工作流就变成了：分析 → 创建计划文件 → 校验计划 → 执行 → 验证。

这一模式为何有效：

尽早捕获错误： 校验会在改动被施加之前发现问题
机器可验证： 脚本提供客观的验证
计划可回退： Claude 可以在不触碰原件的情况下反复打磨计划
调试清晰： 错误信息直指具体问题

何时使用： 批量操作、破坏性改动、复杂的校验规则、高风险操作。

实现提示： 让校验脚本详细一些，给出具体的错误信息，比如「Field ‘signature_date’ not found. Available fields: customer_name, order_total, signature_date_signed」，以帮助 Claude 修复问题。

包依赖

Skill 运行在代码执行环境中，并带有平台特有的限制：

claude.ai： 可以从 npm 和 PyPI 安装包，也可以从 GitHub 仓库拉取
Claude API： 没有网络访问，也不能在运行时安装包

在你的 SKILL.md 中列出所需的包，并对照代码执行工具文档核实它们是否可用。

运行时环境

Skill 运行在一个具备文件系统访问、bash 命令和代码执行能力的代码执行环境中。关于这一架构的概念性解释，参见概览中的 Skill 架构。

这对你的编写有何影响：

Claude 如何访问 Skill：

元数据预加载： 启动时，所有 Skill 的 YAML frontmatter 中的 name 和 description 会被加载进系统提示词
文件按需读取： 需要时，Claude 通过 bash、用 Read 工具从文件系统访问 SKILL.md 和其它文件
脚本高效执行： 工具脚本可以通过 bash 执行，而无需把它们的完整内容加载进上下文。只有脚本的输出会消耗 token
大文件没有上下文代价： 引用文件、数据或文档在被真正读取之前，不会消耗上下文 token

文件路径很重要： Claude 像浏览文件系统一样浏览你的 Skill 目录。使用正斜杠（reference/guide.md），而不是反斜杠
给文件取描述性的名字： 使用能指明内容的名字，比如 form_validation_rules.md，而不是 doc2.md
让结构便于发现： 按领域或功能来组织目录结构
- 好：reference/finance.md、reference/sales.md
  - 坏：docs/file1.md、docs/file2.md
捆绑详尽的资源： 纳入完整的 API 文档、大量示例、大型数据集；在被访问之前不消耗上下文
确定性操作优先用脚本： 写一个 validate_form.py，而不是让 Claude 去生成校验代码
讲清执行意图：
- 「运行 analyze_form.py 来提取字段」（执行）
  - 「关于提取算法，参见 analyze_form.py」（当作参考来阅读）
测试文件访问模式： 通过真实请求来测试，验证 Claude 能够浏览你的目录结构

示例：

bigquery-skill/
├── SKILL.md (overview, points to reference files)
└── reference/
    ├── finance.md (revenue metrics)
    ├── sales.md (pipeline data)
    └── product.md (usage analytics)

当用户询问营收时，Claude 读取 SKILL.md，看到对 reference/finance.md 的引用，于是调用 bash 只读取那个文件。sales.md 和 product.md 文件仍留在文件系统上，在被需要之前消耗的上下文 token 为零。正是这种基于文件系统的模型，让渐进式披露成为可能。Claude 可以浏览并有选择地恰好加载每个任务所需的内容。

关于技术架构的完整细节，参见 Skills 概览中的 Skill 工作原理。

MCP 工具引用

如果你的 Skill 用到 MCP（Model Context Protocol）工具，请始终使用完全限定的工具名，以避免「tool not found」错误。

格式： ServerName:tool_name

示例：

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

其中：

BigQuery 和 GitHub 是 MCP 服务器的名称
bigquery_schema 和 create_issue 是这些服务器内的工具名

少了服务器前缀，Claude 可能就定位不到工具，尤其是在有多个 MCP 服务器可用时。

不要假设工具已经安装

不要假定包是现成可用的：

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: \`pip install pypdf\`

Then use it:
\`\`\`python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
\`\`\`"

技术说明

SKILL.md 的 frontmatter 需要 name 和 description 字段，并带有特定的校验规则：

name：最多 64 个字符，仅限小写字母/数字/连字符，不含 XML 标签，不含保留词
description：最多 1024 个字符，不能为空，不含 XML 标签

关于结构的完整细节，参见 Skills 概览。

token 预算

让 SKILL.md 正文保持在 500 行以内，以获得最佳性能。如果你的内容超过了这个数，就用前文描述的渐进式披露模式把它拆分到独立文件中。关于架构细节，参见 Skills 概览。

有效 Skill 检查清单

在分享一个 Skill 之前，请核实：

核心质量

description 具体，且包含关键术语
description 同时包含这个 Skill 做什么、以及何时使用它
SKILL.md 正文在 500 行以内
额外细节放在独立文件中（如有需要）
没有时效性信息（或已放进「旧模式」小节）
全文术语一致
示例具体，而非抽象
文件引用只有一层深
恰当地运用了渐进式披露
工作流有清晰的步骤

代码与脚本

脚本解决问题，而不是甩锅给 Claude
错误处理显式且有帮助
没有「巫毒常量」（所有取值都有理有据）
所需的包已在指令中列出，并已核实可用
脚本配有清晰的文档
没有 Windows 风格的路径（全部使用正斜杠）
关键操作有校验/验证步骤
质量攸关的任务包含反馈循环

description	Anthropic 官方 Skill 编写指南：用简洁、恰当自由度、渐进式披露三原则，加上「先建评估、Claude A 设计 / Claude B 测试」的迭代循环，写出 Claude 能发现并用好的 Skill。
tags	clippings, ai/skill, ai/claude, ai/工程实践
aliases	Skill authoring best practices, 编写高质量 Claude Skill 指南

AI 知识库

探索

Skill 编写最佳实践

核心原则

简洁是关键

设定恰当的自由度

用你计划使用的所有模型测试

Skill 结构

命名约定

编写有效的 description

直观概览：从简单到复杂

模式 1：高层指南配引用文件

模式 2：按领域组织

模式 3：条件式细节

避免深层嵌套引用

对复杂任务使用工作流

内容指南

避免时效性信息

使用一致的术语

常见模式

模板模式

示例模式

条件式工作流模式

评估与迭代

先构建评估

与 Claude 协作迭代式地开发 Skill

应避免的反模式

避免 Windows 风格的路径

避免提供过多选项

进阶：含可执行代码的 Skill

解决问题，别甩锅

提供工具脚本

使用视觉分析

创建可验证的中间产物

包依赖

运行时环境

MCP 工具引用

不要假设工具已经安装

技术说明

token 预算

有效 Skill 检查清单

核心质量

代码与脚本

相关笔记

目录

反向链接