Claude Code SKILLS编写最佳实践：从零打造高可用 AI 助手

Claude Code SKILLS编写最佳实践从零打造高可用 AI 助手本文翻译整理自 Anthropic 官方技能编写指南结合中文开发者实际场景进行优化帮助你编写出 Claude 能够高效发现和使用的技能Skills。一、为什么技能编写如此重要Claude Code 的技能系统本质上是一种上下文增强机制。你的技能与系统提示词、对话历史、其他技能元数据共享同一个上下文窗口。一个设计良好的技能能让 Claude 在需要时精准加载关键信息避免 token 浪费而设计糟糕的技能则会导致上下文膨胀、响应质量下降。核心认知Claude 本身已经非常聪明你的技能只需补充它不知道的领域知识而非重复基础常识。二、三大核心原则2.1 简洁是最高美德好例子约 50 token## 提取 PDF 文本 使用 pdfplumber 提取文本 python import pdfplumber with pdfplumber.open(file.pdf) as pdf: text pdf.pages[0].extract_text()**坏例子约 150 token** markdown ## 提取 PDF 文本 PDF便携式文档格式是一种常见文件格式包含文本、图像等内容。要提取文本你需要使用库。有很多 PDF 处理库可用pdfplumber 被推荐因为它易于使用...关键区别简洁版本假设 Claude 知道什么是 PDF 和 Python 库只提供它不知道的具体实现细节。2.2 设置适当的自由度将 Claude 想象成一个探索路径的机器人场景类比自由度级别适用场景示例两侧悬崖的窄桥低自由度操作脆弱、一致性关键、必须按序执行数据库迁移脚本必须精确执行--verify --backup有路标的公路中自由度存在首选模式、允许一定变化报告生成模板可自定义格式和图表选项无障碍的旷野高自由度多种方法有效、依赖上下文判断代码审查根据项目规范灵活建议2.3 跨模型测试不同模型的能力差异显著Claude Haiku快速/经济需要更详细的指导不能假设太多背景知识Claude Sonnet平衡标准参考基准Claude Opus强推理避免过度解释否则会产生冗余建议如果计划跨模型使用以 Sonnet 为基准编写确保 Haiku 能理解、Opus 不嫌啰嗦。三、技能结构详解3.1 YAML 前置元数据规范---name:pdf-processing# 必须小写字母/数字/连字符最多64字符description:从PDF提取文本和表格填写表单合并文档。处理PDF文件或用户提及PDF、表单、文档提取时使用。---命名规范推荐动名词形式processing-pdfs、analyzing-spreadsheets可接受pdf-processing名词短语、process-pdfs动作式严禁helper、utils、tools太模糊anthropic-helper保留词描述编写要点始终使用第三人称“处理 Excel 文件并生成报告”避免“我可以帮你…” 或 “你可以用这个…”必须同时包含功能定义和触发条件好描述description:分析Excel电子表格创建数据透视表生成图表。在分析Excel文件、电子表格、表格数据或.xlsx文件时使用。坏描述description:帮助处理文档# 太模糊无触发条件description:处理数据# 无法判断何时激活3.2 渐进式披露架构SKILL.md 应该像目录页只在需要时指向详细内容。基础结构pdf/ ├── SKILL.md # 主入口触发时加载 ├── FORMS.md # 表单指南按需加载 ├── reference.md # API参考按需加载 ├── examples.md # 示例按需加载 └── scripts/ # 可执行脚本 ├── analyze_form.py └── fill_form.py三种组织模式模式一高级指南 引用# PDF 处理 ## 快速开始 使用 pdfplumber 提取文本... ## 高级功能 **表单填写**完整指南请参阅 [FORMS.md](FORMS.md) **API参考**所有方法请参阅 [REFERENCE.md](REFERENCE.md)模式二按领域拆分bigquery-skill/ ├── SKILL.md └── reference/ ├── finance.md # 收入、ARR、账单 ├── sales.md # 机会、管道 ├── product.md # API使用、功能 └── marketing.md # 活动、归因# BigQuery 数据分析 ## 可用数据集 **财务**收入、ARR → 请参阅 [reference/finance.md](reference/finance.md) **销售**机会、管道 → 请参阅 [reference/sales.md](reference/sales.md) ## 快速搜索 bash grep -i revenue reference/finance.md模式三条件详情# DOCX 处理 ## 创建文档 使用 docx-js。请参阅 [DOCX-JS.md](DOCX-JS.md)。 ## 编辑文档 简单编辑直接修改XML **修订追踪**请参阅 [REDLINING.md](REDLINING.md) **OOXML详情**请参阅 [OOXML.md](OOXML.md)3.3 引用深度控制致命错误嵌套引用# SKILL.md → 请参阅 advanced.md # advanced.md → 请参阅 details.md # details.md → 实际信息在这里Claude 遇到嵌套引用时可能只读取前 100 行导致信息缺失。正确做法全部从 SKILL.md 一层直达# SKILL.md **基础用法**本文档内 **高级功能**请参阅 [advanced.md](advanced.md) **API参考**请参阅 [reference.md](reference.md) **示例**请参阅 [examples.md](examples.md)长文件处理超过 100 行的参考文件顶部必须加目录# API 参考 ## 目录 - 认证和设置 - 核心方法CRUD - 高级功能批处理、Webhook - 错误处理模式 - 代码示例四、工作流程与反馈循环4.1 复杂任务清单化研究综合工作流程示例## 研究综合工作流程 复制此清单并跟踪进度研究进度步骤1阅读所有源文档步骤2识别关键主题步骤3交叉验证声明步骤4创建结构化摘要步骤5验证引用**步骤1阅读所有源文档** 查看 sources/ 目录记录主要论点... **步骤2识别关键主题** 寻找跨来源的模式... 后续步骤详细说明...PDF 表单填写工作流程示例## PDF 表单填写工作流程任务进度步骤1分析表单运行 analyze_form.py步骤2创建字段映射编辑 fields.json步骤3验证映射运行 validate_fields.py步骤4填写表单运行 fill_form.py步骤5验证输出运行 verify_output.py**步骤1分析表单** 运行python scripts/analyze_form.py input.pdf 提取表单字段保存到 fields.json... 后续步骤详细说明...4.2 验证循环模式核心公式运行验证器 → 修复错误 → 重复无代码场景风格指南合规## 内容审查流程 1. 按照 STYLE_GUIDE.md 起草内容 2. 对照清单审查 - 术语一致性 - 示例格式标准 - 必需部分完整性 3. 如果发现问题 - 记录具体问题位置 - 修订内容 - 再次审查清单 4. 仅当全部通过时继续有代码场景文档编辑## 文档编辑流程 1. 编辑 word/document.xml 2. **立即验证**python scripts/validate.py unpacked/ 3. 如果失败 - 查看错误消息 - 修复 XML - 再次验证 4. **仅验证通过后继续** 5. 重建python scripts/pack.py unpacked/ output.docx五、内容编写规范5.1 避免时效性信息错误写法如果你在今年8月前做这个使用旧API。之后使用新API。正确写法## 当前方法 使用 v2 APIapi.example.com/v2/messages ## 旧模式 details summary旧版 v1 API2025-08弃用/summary v1 API 已停止支持。 /details5.2 术语一致性好一致坏混用始终 “API endpoint”混用 “endpoint”/“URL”/“route”/“path”始终 “field”混用 “field”/“box”/“element”/“control”始终 “extract”混用 “extract”/“pull”/“get”/“retrieve”5.3 模板与示例严格模板API响应等## 报告结构 始终使用此精确模板 markdown # [分析标题] ## 执行摘要 [一段概述] ## 关键发现 - 发现1带数据 - 发现2带数据 ## 建议 1. 具体可操作建议 2. 具体可操作建议**灵活模板需要适应性时** markdown ## 报告结构 默认格式如下但根据分析灵活调整 markdown # [标题] ## 执行摘要 ## 关键发现 [根据发现调整章节] ## 建议 [针对情境定制]**示例模式输入/输出对** markdown ## 提交消息格式 **示例1** 输入添加JWT用户认证 输出feat(auth): 实现JWT认证添加登录端点和令牌验证中间件**示例2** 输入修复报告日期显示bug 输出fix(reports): 修正时区转换日期格式统一使用UTC时间戳六、评估驱动开发6.1 先写评估再写文档五步法识别差距不用技能跑代表性任务记录具体失败点创建评估构建3个测试场景建立基线测量无技能时的表现编写最小指令刚好足够解决差距迭代优化执行评估对比基线持续改进评估结构示例{skills:[pdf-processing],query:从PDF提取所有文本保存到output.txt,files:[test-files/document.pdf],expected_behavior:[使用适当库成功读取PDF,提取所有页面文本不遗漏,保存到output.txt格式清晰可读]}6.2 双 Claude 迭代法Claude A设计者 Claude B测试者循环无技能完成任务与 Claude A 正常对话注意反复提供的上下文识别可重用模式提取表名、字段定义、过滤规则等要求 Claude A 创建技能“创建一个捕捉这个 BigQuery 分析模式的技能”审查简洁性“删除胜率含义的解释Claude 已经知道”改进架构“把表模式放到单独参考文件”Claude B 实测新实例加载技能后执行真实任务观察反馈“Claude B 忘记了过滤测试账户需要更突出”返回 Claude A 优化基于观察调整而非假设七、高级技巧可执行代码7.1 解决不要推脱好代码显式处理错误defprocess_file(path):try:withopen(path)asf:returnf.read()exceptFileNotFoundError:print(f文件未找到创建默认)withopen(path,w)asf:f.write()returnexceptPermissionError:print(f无法访问使用默认)return坏代码推给 Claudedefprocess_file(path):returnopen(path).read()# 直接失败让 Claude 解决7.2 自文档化常数好# HTTP请求通常30秒内完成更长超时考虑慢连接REQUEST_TIMEOUT30# 3次重试平衡可靠性与速度大多数间歇故障第二次重试解决MAX_RETRIES3坏魔法数字TIMEOUT47# 为什么是47RETRIES5# 为什么是57.3 实用脚本优先脚本比生成代码更可靠、省 token、省时间、保证一致性。明确执行意图执行“运行analyze_form.py提取字段”参考“查看analyze_form.py了解提取算法”示例## 实用脚本 **analyze_form.py**提取PDF表单字段 bash python scripts/analyze_form.py input.pdf fields.json输出格式{field_name:{type:text,x:100,y:200}}validate_boxes.py检查重叠边界框python scripts/validate_boxes.py fields.json# 返回OK 或列出冲突### 7.4 计划-验证-执行模式 高风险操作如批量更新50个PDF字段的中间验证分析 → 创建 changes.json → 验证计划 → 执行 → 验证结果**验证脚本要详细** python # 错误示例Field signature_date not found. # Available: customer_name, order_total, signature_date_signed7.5 依赖管理平台能力限制claude.ai可从 npm/PyPI 安装可拉取 GitHub无Claude API无网络访问无运行时安装必须预装必须在 SKILL.md 列出所需包并验证可用性。7.6 运行时环境要点路径始终使用正斜杠scripts/helper.py即使在 Windows命名form_validation_rules.md而非doc2.md组织reference/finance.md而非docs/file1.mdMCP 工具始终使用完全限定名BigQuery:bigquery_schema八、发布前检查清单核心质量描述具体包含功能定义和触发条件SKILL.md 正文控制在 500 行以内超出的内容拆分到单独文件无时效性信息或在折叠的旧模式中全文术语一致示例具体而非抽象文件引用只有一层深度工作流程步骤清晰代码与脚本脚本显式处理错误不推给 Claude无魔法数字所有常数有解释所需包已列出并验证可用无 Windows 风格路径关键操作有验证步骤质量关键任务有反馈循环测试验证至少 3 个评估场景跨 Haiku / Sonnet / Opus 测试真实使用场景验证团队反馈已纳入如适用九、总结编写高质量 Claude Code 技能的核心在于精准补充 Claude 不知道的信息以最小 token 成本实现最大上下文价值。遵循简洁、分层、可验证三大原则通过评估驱动开发和双 Claude 迭代法持续优化你的技能将成为团队中不可或缺的效率倍增器。本文基于 Anthropic 官方文档翻译整理结合中文开发者实践场景优化。如有疑问欢迎在评论区交流讨论。