最佳实践

优秀的 Skills 应当简洁、结构清晰，并经过真实场景验证。本指南提供实用的写作建议，帮助你构建 Claude 能高效调用的技能。

想了解技能工作原理，请先阅读 Skills 概览。

核心原则

精炼优先

Context window 是公共资源，你的技能需与以下内容共享上下文：

• 系统提示词
• 对话历史
• 其他技能的元数据
• 当前用户请求

技能并非所有 token 都会立即加载。启动时仅加载元数据（name 与 description），SKILL.md 及其引用文件会按需读取。但一旦进入上下文，就会与其他内容竞争空间，因此 SKILL.md 仍需足够精炼。

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

仅补充 Claude 不具备的背景。逐条审视每段话：

• “Claude 真的需要这段解释吗？”
• “我能否假设 Claude 已了解？”
• “这段话的 token 成本是否划算？”

优例：简洁（约 50 tokens）：

## 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 tokens）：

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content...

精简版本假设 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 想象成探索路径的机器人。

• 悬崖峭壁上的窄桥：只有一条安全道路，提供精确指令（低自由度），例如数据库迁移。
• 开阔草地：多条路径都能成功，给出大致方向即可（高自由度），例如代码审查。

使用全部目标模型进行测试

技能相当于对模型的附加能力，效果取决于底层模型。务必在计划部署的所有模型（如 Haiku、Sonnet、Opus）上测试技能表现。

优先真实评测

真实用户请求 最能衡量技能效果。请在开发过程中：

1. 收集真实任务示例并记录预期结果
2. 快速迭代技能内容
3. 再次测试直到输出符合预期

最有效的反馈来自“技能未被触发”或“触发后没有遵循指令”的案例，可用于改进描述与指令。

先写人类可读的指令

技能准备阶段，先撰写文本流程，再决定是否需要脚本。Ask yourself：

• 这段流程是否可以直接交给 Claude 手动执行？
• 如果需要脚本，是因为需要确定性还是效率？

建议先写出一份详细流程，再视情况补充脚本或资源。

明确技能触发条件

技能描述是 Claude 判断是否调用的关键信号，应满足：

• 清晰描述技能能力与使用场景
• 包含关键术语与输入类型
• 使用用户会提到的词汇
• 说明适用边界

描述模板：

Use when [触发条件/关键词] to [目标行动] by [核心操作] while [重要限制或保障]。

示例：

Use when users mention PowerPoint to generate `.pptx` presentations using the
Anthropic slide generation pipeline. Focus on corporate tone, use brand templates,
and export the file to share back.

对照标准：

使用渐进式披露

合理分层可以避免上下文拥堵：

1. SKILL.md：包含触发逻辑、关键流程、短代码片段
2. 参考文件：存放详尽模板、长示例、API 说明
3. 脚本：处理重复或易错操作

技能目录范例：

seo-copy-skill/
|-- SKILL.md
|-- reference/
|   |-- tone-guide.md
|   `-- product-faq.md
`-- scripts/
    `-- keyword_analyzer.py

关注版本性信息

• 明确标注过时流程或临时策略
• 如果技能依赖外部系统，写明版本/日期
• 提供 fallback 策略，以免指令失效

为脚本补充注释与提示

脚本应强调“执行什么”与“为何这样做”：

• 顶部注释说明功能、输入输出
• 对关键逻辑添加解释
• 对潜在错误或限制给出提示

示例：

"""Validate form responses and export errors to CSV."""
def validate_form(response):
    """
    response: dict of form fields
    Returns list of validation errors
    """

给出验证步骤

对关键任务，指令中应包含结果核对或质量评估方法。例如：

• “生成完成后检查图表数据是否与源数据一致”
• “若脚本报错，请提示用户并给出修复建议”

编写负面案例

帮助 Claude 避免错误触发：

## When NOT to use this Skill

- User only needs a quick summary (use default summarization instead)
- Request is about generating images (Skill does not support media)
- User asks for live web data (Skill works offline only)

尽早存档旧流程

当流程失效或不再推荐时，将其移动到“Legacy”或“Deprecated”章节，并说明原因与替代方案，避免 Claude 继续使用旧方法。

结构与组织

建议 SKILL.md 采用以下结构：

1. 简介：一段话说明用途
2. 触发条件：列出关键词或适用场景
3. 流程/步骤：主流程拆分为小节
4. 示例：至少一个完整示例
5. 检查与反馈：质量校验、回传方式
6. 附录（可选）：说明附带脚本或参考资料

标注引用文件

在 SKILL.md 中引用其他文件时，使用相对路径，例如：

Refer to [reference/tone-guide.md](reference/tone-guide.md) for voice checklist.

确保目录结构扁平，方便 Claude 读取：

skill/
├─ SKILL.md
├─ reference/
│  ├─ tone-guide.md
│  └─ templates.md
└─ scripts/
   └─ generate_report.py

明确输出格式

告诉 Claude 最终需要以何种方式返回结果：

• “完成后请生成 .pptx 文件并附带下载链接”
• “回复正文需包含 TL;DR 与详细报告两部分”

评测与测试

构建评测集

为每个技能准备至少 3 条真实请求作为评测用例，覆盖：

• 正常流程
• 边缘或复杂场景
• 不适用场景（用于确认技能不会被误触发）

记录每条用例的预期输出，便于回归测试。

多模型验证

至少在 Haiku、Sonnet、Opus 上测试技能，以避免模型间表现差异。观察：

• 是否总能正确触发技能
• 是否严格遵循指令
• 输出是否稳定

收集团队反馈

与同事共享技能并收集使用体验，尤其关注：

• 技能是否容易理解与调用
• 是否存在误判场景
• 是否缺少辅助材料（模板、脚本等）

常见目录结构示例

marketing-email-skill/
├─ SKILL.md
├─ reference/
│  ├─ brand-voice.md
│  └─ subject-line-patterns.md
└─ scripts/
   └─ link_checker.py

• SKILL.md：概述流程、触发条件、校验步骤
• reference/：提供品牌语气、模板、示例
• scripts/：处理链接校验等重复操作

其他技术注意事项

MCP 工具调用

若技能依赖 MCP 工具，必须使用完整命名：ServerName:tool_name。

示例：

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

不要假设依赖已安装

如需额外包，请在指令中明确说明：

**Bad**：Use the pdf library to process the file.

**Good**：Install required package: `pip install pypdf`
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```

YAML frontmatter 限制

SKILL.md 仅支持 name（最多 64 字符）与 description（最多 1024 字符）。结构详情见 Skills 概览。

Token 预算

建议 SKILL.md 主体不超过 500 行。若内容超出，请拆分至其他文件，并利用渐进式披露模式引用。

Skills 检查清单

在分享技能前，请逐项确认：

核心质量

• 描述具体，包含关键术语
• 描述同时说明技能作用与触发条件
• SKILL.md 少于 500 行
• 详细信息放在单独文件
• 无过期或时效信息（或已放入“旧流程”章节）
• 全文术语一致
• 示例具体、有可执行性
• 文件引用路径浅（尽量单层目录）
• 采用渐进式披露组织内容
• 流程步骤清晰

代码与脚本

• 脚本直接解决问题，而非再交给 Claude
• 提供明确错误处理与提示
• 所有常量都有解释
• 说明所需依赖并确认可用
• 脚本包含文档或注释
• 使用正斜杠路径（兼容 bash）
• 关键操作设有验证或回滚步骤
• 包含质量反馈闭环（如回传结果、提醒复核）

测试

• 至少创建三个评测用例
• 在 Haiku、Sonnet、Opus 上完成测试
• 结合真实需求场景验证
• 吸收团队反馈（若适用）

下一步