Anthropic 官方技能编写最佳实践

核心原则

1. 简洁是关键

上下文窗口（Context Window）是公共资源。你的技能与系统提示、对话历史、其他技能元数据共享上下文窗口。

默认假设： Claude 已经非常聪明。只添加 Claude 尚不知道的上下文。

2. 设定适当的自由度

根据任务的脆弱性和可变性匹配具体程度：

• 高自由度（文字指令）：多种方法都有效时
• 中等自由度（伪代码/带参数脚本）：有首选模式时
• 低自由度（特定脚本）：操作脆弱且易出错时

类比： 把 Claude 想象成在路上探索的机器人——两侧有悬崖的窄桥需要精确护栏（低自由度），没有危险的开阔场地给出大方向即可（高自由度）。

3. 使用所有计划使用的模型测试

• Haiku（快速、经济）：技能是否提供了足够的指导？
• Sonnet（平衡）：技能是否清晰高效？
• Opus（强推理）：技能是否过度解释？

技能结构

命名约定

推荐动名词形式：

• ✅ "Processing PDFs"、"Analyzing spreadsheets"
• ❌ "Helper"、"Utils"、"Tools"

编写有效描述

• 始终用第三人称
• 包含技能做什么和何时使用
• 具体且包含关键术语

渐进式披露模式

SKILL.md 作为概述指向详细材料：

• SKILL.md 正文保持 500 行以内
• 接近限制时拆分到单独文件
• 保持引用一层深度（不要嵌套引用）

工作流和反馈循环

复杂任务使用工作流

分解为清晰的顺序步骤，提供检查清单。

实现反馈循环

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

内容指南

• 避免时效性信息
• 使用一致的术语
• 提供默认选择，不要给太多选项

评估和迭代

先建立评估

评估驱动开发：

1. 识别差距：无技能时运行 Claude，记录失败
2. 创建评估：3 个测试场景
3. 建立基线
4. 写最少的指令
5. 迭代

与 Claude 迭代开发技能

• Claude A（专家）帮助完善技能
• Claude B（代理）使用技能执行真实任务
• 观察 Claude B 的行为，反馈给 Claude A

高级：带可执行代码的技能

• 解决，不推卸 — 脚本应处理错误而非推给 Claude
• 提供实用脚本 — 比生成代码更可靠
• 使用视觉分析 — 利用 Claude 的视觉能力
• 创建可验证中间输出 — 计划-验证-执行模式
• 明确 MCP 工具引用 — 使用完全限定名称：ServerName:tool_name

有效技能检查清单

核心质量

• 描述具体且包含关键术语
• SKILL.md 正文 500 行以内
• 无时效性信息
• 术语一致
• 示例具体非抽象
• 文件引用一层深度
• 工作流步骤清晰

代码和脚本

• 脚本解决问题而非推卸给 Claude
• 错误处理明确且有帮助
• 无"巫术常量"
• 所需包已列出并验证可用

测试

• 至少三个评估场景
• 用 Haiku、Sonnet、Opus 测试
• 用真实场景测试