Anthropic 的工程师 Thariq 近日在社区分享了一篇长文，系统性地总结了 Anthropic 内部在构建和使用 Claude Code Skills 方面积累的数百条实战经验。这篇文章的价值在于，它并非简单的功能介绍，而是深入探讨了如何设计出真正高效、可维护的技能。
这篇文章由 Thariq 耗时一周半打磨完成。他表示，尽管 Claude 协助他进行了大量的前期调研和初稿撰写，但最终的文案几乎全由他本人重写，只保留了 Claude 生成的配图。他强调，写作是一个迫使你思考和提炼想法的过程，他只愿意发布那些包含真知灼见的内容。
那么，这些经过深度思考的见解究竟是什么呢？
重新定义：Skill 远不止于一个 Markdown 文件
一个普遍的误解是，Skill 不过是一个 .md 文件。实际上，这种认知限制了 Skill 的可能性。
一个 Skill 是一个完整的文件夹。 它可以包含脚本、配置文件、资源模板、数据文件和动态钩子。在 Claude Code 中，Skill 是一个完整的能力单元，Agent 能够自行探索和操作文件夹内的所有资源，而不仅仅是读取一份静态文档。
Anthropic 内部的经验表明，最强大、最值得研究的 Skill，恰恰是那些充分利用了这种“文件夹即工具箱”特性的实例。
九大类型：好的 Skill 归属清晰
通过对内部大量 Skill 的梳理，Thariq 发现它们会自然地聚合为九个清晰的类别。一个优秀的、易于理解的 Skill 通常能干净利落地归属于某一类别；而那些让人困惑的，往往是目标模糊、横跨多个类型的。
- 库和 API 参考：帮助 Claude 正确使用内部或第三方库、CLI 工具及 SDK。这类 Skill 的核心是 Gotchas（踩坑记录） 和代码片段。例如，一个针对内部计费库（billing-lib）的 Skill，会详细列出像“按比例计费向下取整而非四舍五入到分”这样的边界情况。
- 产品验证：描述如何测试和验证某项功能是否正常工作。通常会整合 Playwright 等外部工具。一个高投入的验证类 Skill 能极大提升测试效率。
- 数据查询与分析：连接数据源和监控系统，提供数据库凭证、看板 ID 和常用查询模式。例如，一个分析用户漏斗的 Skill 会明确告知 Claude 需要联接哪些事件表，以及标准的用户 ID 字段在哪里。
- 业务流程自动化：将涉及多个工具、步骤的重复性工作流浓缩为一条命令。例如，一个
standup-post Skill 可以自动从 Jira、GitHub、Slack 聚合信息，生成格式化的每日站会报告。
- 代码脚手架：为特定功能生成符合代码库规范的框架代码。当需求涉及自然语言描述的复杂逻辑（无法用纯代码模板覆盖）时，这类 Skill 尤其有用。
- 代码质量与审查：在组织内部强制执行代码规范。一个有趣的实践是
adversarial-review Skill：它会启动一个全新的子 Agent 来专门“挑刺”，修复问题后继续迭代，直到找不到实质性缺陷。
- CI/CD 与部署：安全地执行拉取、推送和部署代码的操作。经典例子是
babysit-pr：监控一个 PR，在 CI 失败时重试，解决合并冲突，并最终完成合并。
- 事故排查手册：给定一个症状（如错误日志签名），引导 Claude 走完多工具调查流程，并输出结构化的排查报告。
- 基础设施运维：执行日常维护和清理等运维操作。由于常涉及危险操作，这类 Skill 必须内置安全护栏，例如执行清理前必须等待确认期。
九条写作技巧：打造高价值 Skill
知道了“写什么”，下一步是“怎么写”。Thariq 总结了九条核心写作原则。
1. 跳过显而易见的内容
Claude 对编程和你的代码库已有相当程度的了解。你的 Skill 应聚焦于那些能将 Claude 推出其默认思维模式的关键信息。例如，Anthropic 的 frontend-design Skill 专门用于纠正 Claude 在 UI 设计上的一些默认偏好（如过度使用特定字体和渐变）。
2. Gotchas 部分是灵魂
一个 Skill 中信息密度最高、价值最大的部分就是 Gotchas（踩坑记录）。这部分内容应该随着 Claude 的实际使用而持续积累和更新。
上图展示了一个 billing-lib Skill 的演化：从第一天的简单说明，到第二周加入一条 Gotcha，再到第三个月积累四条关键注意事项。每当你发现 Claude 因某个细节出错时，就为它添加一行 Gotcha。 这是 Skill 保持生命力的关键。
3. 利用文件夹结构实现信息分层
既然 Skill 是一个文件夹，就应该将整个文件系统用作信息工程和渐进式披露的工具。简单做法是将详细的 API 说明拆到 references/api.md，将输出模板放在 assets/ 目录。
如上图的 queue-debugging Skill：主文件 SKILL.md 仅约30行，作为“调度中心”，根据用户描述的症状（如“任务卡住”、“死信队列堆积”），指引 Claude 去读取对应的详细排查文件（如 stuck-jobs.md）。
4. 别把 Claude 管得太死
Skill 是为复用设计的，因此指令应保持灵活性，让 Claude 能根据具体上下文做出最佳判断。
对比上图的 Cherry-pick 场景：左边“过于死板”的版本将每一步都写成固定指令；右边“更好”的版本仅说明意图：“将提交拣选到干净分支。解决冲突时保留原意。如果无法干净地应用，请解释原因。” 讲清意图，将方法的选择权交给 Claude。
5. 设计首次运行配置
对于需要用户特定上下文（如 Slack 频道、API 密钥）的 Skill，一个优雅的模式是将配置存储在 Skill 目录下的 config.json 中。
如上图 standup-post Skill 的做法：SKILL.md 通过一行 shell 命令检查 config.json 是否存在。如果不存在，Claude 会主动引导用户完成初始配置（询问频道、示例格式等），并将答案写入配置文件。
6. Description 是写给模型看的触发器
Claude Code 通过扫描所有 Skill 的 description 字段来决定是否触发某个 Skill。因此，这个字段的重点应是触发条件，而非功能描述。
- 反面：“一个用于监控PR状态的综合工具。”（过于宽泛，无触发信息）
- 正面：“监控一个PR直到它合并。触发词：‘babysit’，‘watch CI’，‘确保这个能合进去’。”（明确了用户会怎么“说”）
7. 为 Skill 赋予“记忆”能力
通过持久化存储数据，Skill 可以实现简单的“记忆”。这可以是一个追加日志，也可以是一个 SQLite 数据库。
例如，standup-post Skill 每次运行后，将站会内容追加到持久化的 standups.log 中。下次运行时，Claude 可以读取历史日志，自动对比“从昨天到今天发生了什么变化”。
注意：Skill 目录本身可能在升级时被重置。应使用 Claude Code 提供的 ${CLAUDE_PLUGIN_DATA} 环境变量所指向的稳定路径来存储数据。
8. 提供代码库，而非冗长指令
你能给 Claude 最强大的工具就是代码。 提供精心设计的函数库和脚本，让 Claude 将精力花在“组合”与“决策”上，而不是每次都从头开始构造逻辑。
例如，一个数据分析 Skill 可以提供 lib/signups.py：
def fetch(day):
“”“Signups from events.raw for one day.
- event='signup_completed', NOT 'signup_started'
- dedupe by anonymous_id
- user_id is null until after signup”“”
def by_referrer(df):
“”“Group by traffic source.
- '(direct)' and '' and None all mean organic”“”
def by_landing_page(df):
“”“Group by entry page.
- '/'，'/index'，'/home' are all the homepage
- strips query params so UTM'd links collapse”“”
当用户询问“周二发生了什么？”，Claude 可以轻松组合这些函数，生成简短的调查脚本：
from lib.signups import fetch, by_referrer, by_landing_page
mon, tue = fetch(“2024-03-11”), fetch(“2024-03-12”)
print(by_referrer(tue) - by_referrer(mon)) # organic -60%， paid flat
print(by_landing_page(tue) - by_landing_page(mon)) # homepage specifically
# → something broke on / on Tuesday
9. 使用按需激活的 Hooks
Claude Code Skill 支持注册只在当前会话中被调用时才激活的钩子。这非常适合那些“不总是需要，但关键时刻是救命稻草”的防护措施。
/careful：手动触发后，会拦截 rm -rf、DROP TABLE、kubectl delete 等危险命令。/freeze：锁定特定目录外的所有文件修改，防止在调试时“顺手”改动了无关代码。
分享、度量与核心理念
分享机制：小团队可将 Skill 直接提交到代码仓库的 .claude/skills/ 目录下。规模扩大后，内部插件市场是更好的选择。Anthropic 内部采用“自然浮现”策略：作者先将 Skill 放到沙箱区供同事试用，获得足够认可后再正式提交到市场。
度量方式：通过 PreToolUse 钩子记录 Skill 的触发和使用情况，分析哪些 Skill 最受欢迎，哪些未被充分利用。
核心理念：Thariq 强调，这些经验更像一个“锦囊集”，而非权威指南。最好的学习方式是动手实践。Anthropic 内部大多数优秀的 Skill 都始于寥寥数行，其价值是在长期使用和持续添加“踩坑记录”的过程中“生长”出来的。
这揭示了软件工程的一个普适真理：优秀的文档从来不是一蹴而就的，它是在反复实践中迭代和丰富的。 每一个 Gotcha 背后，都是一个具体的问题或教训。从“Day 1”的三行简介，到“Month 3”的团队知识宝藏，其间的差距就是那些被识别和记录下来的“坑”。
因此，行动指南很简单：
- 立刻动手写一个，哪怕它只有三行说明。
- 坚持使用它，每当 Claude 因此犯错或遇到障碍，就添加一条 Gotcha。
- 三个月后回顾，你会发现它已悄然成为团队不可或缺的资产。
对于希望深入探索 DevOps 自动化与 AI 助手的开发者而言，这种基于实践的、持续迭代的技能构建方法论，在 云栈社区 等开发者平台中总能引发共鸣和深入讨论。
相关链接：
发表于 3 小时前
|
查看: 2|
回复: 0
