构建 Claude Code 的经验之谈：我们如何使用 Skills

朝阳区靓仔_James

189人浏览 · 2026-07-26 10:45:00

朝阳区靓仔_James · 2026-07-26 10:45:00 发布

Skills 已经成为 Claude Code 中最常用的扩展点之一。它们灵活、易编写、易分发。

但这种灵活性也让人难以把握"怎么做才最好"。哪些类型的 Skills 值得做？一个 Skill 该怎么组织结构？什么时候应该分享给别人？

在 Anthropic，我们在 Claude Code 中大量使用 Skills，目前活跃使用的有数百个。以下是我们用 Skills 加速开发过程中总结出的经验。

一、什么是 Skills？

Skills 是一个个文件夹，里面装着指令、脚本和资源，Agent 可以发现并使用它们，从而更准确、更高效地完成任务。本文假设你已经了解 Skills 的基础概念；如果是新手，建议先学习我们在 Skilljar 上的《Agent Skills 入门》课程。

关于 Skills，我们常听到一个误解，“不就是 Markdown 文件嘛”。实际上它们是文件夹，里面可以包含脚本、资产、数据等，Agent 能够发现、探索并操作这些内容。

在 Claude Code 中，Skills 还有丰富的配置选项，包括注册动态钩子（hooks）等。

我们发现，Claude Code 中最高效的一些 Skills，正是把这些配置选项和文件夹结构用得非常充分的那些。

二、Skills 的九大类型

在盘点完 Anthropic 内部所有的 Skills 之后，我们发现它们可以归为九大类。最好的 Skills 都能干净利落地归入其中一类；而那些想"什么都干"的 Skills 往往横跨好几类，反而会让 Agent 困惑。这个清单并非权威定义，但它是一个有用的框架，可以帮你发现自己 Skills 库里的空白。

（配图说明：Claude Code 团队对内部 Skills 做了分类，发现它们可以归入九个截然不同的类别。经得起时间考验的 Skills，都能干净地落入单一类别。）

库与 API 参考（Library & API Reference）

这类 Skills 讲解如何正确使用某个库、CLI 或 SDK。既可以是内部库，也可以是 Claude Code 有时处理不好的常见库。这类 Skills 通常会附带一个参考代码片段文件夹，以及一份 Claude 在写脚本时应当避开的"坑"清单。

典型例子：

billing-lib 内部计费库：边界情况、易踩的坑（footguns）等。
internal-platform-cli 内部 CLI 封装工具的每个子命令，附带使用场景示例。
sandbox-proxy 配置组织的开发出口网关：哪些主机可达、如何排查"connection refused"错误、如何添加白名单条目。

产品验证（Product Verification）

这类 Skills 描述如何测试或验证你的代码是否真正工作。它们常与 Playwright、tmux 或其他外部验证工具搭配使用。

在 Anthropic 内部，验证类 Skills 对 Claude 输出质量的提升是最可量化的。让一名工程师专门花一周时间把验证类 Skills 打磨到极致，是完全值得的。

可以考虑的技巧包括：让 Claude 录屏记录它的操作过程，这样你能精确看到它测试了什么；或者在每一步强制执行程序化的状态断言。这些通常通过在 Skill 中内置多种脚本来实现。

典型例子：

signup-flow-driver 在无头浏览器中跑通"注册 → 邮箱验证 → 新手引导"全流程，并在每一步挂载状态断言钩子。
checkout-verifier 用 Stripe 测试卡驱动结账 UI，验证发票确实落入正确的状态。
tmux-cli-driver 用于交互式 CLI 测试：当你要验证的东西需要一个 TTY 终端时。

数据获取与分析（Data & Analysis）

这类 Skills 连接你的数据与监控技术栈。它们可能包含带凭证的数据拉取库、特定的仪表盘 ID 等，以及常见工作流或取数方式的说明。

典型例子：

funnel-query “要看到注册 → 激活 → 付费，我需要关联哪些事件”，外加真正存有权威 user_id 的那张表。
cohort-compare 比较两个用户群的留存或转化，标记出统计显著的差异，并链接到分群定义。
grafana 数据源 UID、集群名称、"问题 → 仪表盘"速查表。
datadog 字段参考（@request_id 与 trace_id 的区别）、服务列表、指标前缀约定。

业务流程与团队自动化（Business Automation）

这类 Skills 把重复性工作流压缩成一条命令。它们本身通常是相当简单的指令，但可能对其它 Skills 或 MCP 有较复杂的依赖。对于这类 Skills，把历次执行结果保存到日志文件中，可以帮助模型保持一致性，并对之前的工作流执行情况进行"反思"。

典型例子：

standup-post 聚合你的工单系统、GitHub 活动和此前的 Slack 记录 → 生成格式化的日报，只写增量部分。
create–ticket 强制遵守 Schema（合法的枚举值、必填字段），外加建单后的流程（提醒评审人、在 Slack 中贴链接）。
weekly-recap 已合并的 PR + 已关闭的工单 + 发布记录 → 格式化的周报。

代码脚手架与模板（Scaffolding & Templates）

这类 Skills 为代码库中的特定功能生成框架样板代码。你可以把它们与可组合的脚本结合起来。当脚手架中包含纯代码无法覆盖的自然语言要求时，这类 Skills 尤其有用。

典型例子：

new–workflow 按照你们的注解规范，脚手架出一个新的 service/workflow/handler。
new-migration 你们的迁移文件模板 + 常见坑。
create-app 新建内部应用，预装好你们的鉴权、日志和部署配置。

代码质量与评审（Code Quality & Review）

这类 Skills 在组织内部强制执行代码质量标准、辅助代码评审。为了最大的确定性，它们可以包含确定性的脚本或工具。你可能希望把它们作为 hooks 或 GitHub Action 的一部分自动运行。

典型例子：

adversarial-review 派生一个"新鲜视角"的子 Agent 来挑刺，实施修复，迭代直到评审意见退化为无关痛痒的小问题。
code-style 强制执行代码风格，尤其是 Claude 默认做不好的那些风格。
testing-practices 关于如何写测试、测什么的指引。

CI/CD 与部署（CI/CD & Deployment）

这类 Skills 帮你在代码库中拉取、推送和部署代码。它们可能会引用其它 Skills 来收集数据。

典型例子：

babysit-pr 盯着一个 PR → 重试不稳定的 CI → 解决合并冲突 → 开启自动合并。
deploy- 构建 → 冒烟测试 → 带错误率对比的渐进式流量放量 → 出现退化时自动回滚。
cherry-pick-prod 隔离的 worktree → cherry-pick → 冲突解决 → 按模板提 PR。

故障处置手册（Incident Runbooks）

这类 Skills 接收一个症状（比如一个 Slack 讨论串、一条告警或一个错误特征），走完一套多工具排查流程，并产出一份结构化报告。

典型例子：

-debugging 为你们流量最高的服务建立"症状 → 工具 → 查询模式"的映射。
oncall-runner 拉取告警 → 排查常见嫌疑对象 → 格式化输出结论。
log-correlator 给定一个请求 ID，从所有可能经手过它的系统中拉出匹配的日志。

基础设施运维（Infrastructure Ops）

这类 Skills 执行例行维护和操作程序，其中一些涉及破坏性操作，需要防护栏（guardrails）的加持。它们让工程师在关键操作中更容易遵循最佳实践。

典型例子：

-orphans 找出孤儿 Pod/存储卷 → 发到 Slack → 观察期 → 用户确认 → 级联清理。
dependency-management 你们组织的依赖审批工作流。
cost-investigation “我们的存储/出口流量账单为什么暴涨”，附带具体的存储桶和查询模式。

三、编写 Skills 的实用技巧

决定了要做什么 Skill 之后，该怎么写？以下是 Claude Code 团队总结的最佳实践、技巧和窍门。

不要陈述显而易见的事

Claude 本来就会写代码，也能读懂你的代码库。一个只是复述 Claude 默认行为的 Skill，增加了上下文却没有增加价值。如果你发布的 Skill 主要是知识型的，请聚焦在那些能把 Claude 推出其惯性思维的信息上。

前端设计 Skill（frontend design skill）就是个很好的例子：它由 Anthropic 的一名工程师与客户反复迭代打磨而成，目的是提升 Claude 的设计品味，避免落入"Inter 字体 + 紫色渐变"这类经典俗套。

建立"避坑指南"（Gotchas）章节

任何 Skill 中信号密度最高的内容，都是 Gotchas（避坑指南）章节。这些章节应当从 Claude 在使用你的 Skill 时实际踩到的常见失败点中积累而来。理想情况下，你要随时间不断更新 Skill，把这些坑捕获进去。

例如：

“subscriptions 表是只追加（append-only）的。你要找的行是 version 最高的那一行，而不是created_at最新的那一行。”
“这个字段在 API 网关中叫 @request_id，在计费服务中叫 trace_id。它们是同一个值。”
“即使 Stripe webhook 实际上没有处理成功，预发环境也会返回 200。要查payment_events才能看到真实状态。”

（配图说明：第 1 天的 billing-lib Skill 只有简介，第 2 周加了一条 Gotcha，第 3 个月已经积累了四条，每当 Claude 被什么东西绊倒一次，就加一行。）

善用文件系统与渐进式披露

如前文所说，Skill 是一个文件夹，而不仅仅是一个 Markdown 文件。你应当把整个文件系统视为上下文工程（context engineering）和渐进式披露（progressive disclosure）的一种形式。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时机去读取它们。

渐进式披露最简单的形式，是指向其它 Markdown 文件供 Claude 使用。比如，你可以把详细的函数签名和用法示例拆到references/api.md中。

再举个例子：如果你的最终输出物是一个 Markdown 文件，你可以在assets/目录里放一个模板文件供复制使用。

你可以放入参考资料、脚本、示例等各种文件夹，帮助 Claude 更高效地工作。

（配图说明：queue-debugging/SKILL.md 是"枢纽"，里面只有约 30 行，一张"症状 → 阅读哪个文件"的对照表：任务卡住读 stuck-jobs.md，消息进了死信队列读 dead-letters.md，同一任务循环重试读 retry-storms.md，队列深度持续上涨读 consumer-lag.md。枢纽负责分发，辐条文件负责干活。）

避免把 Claude “框死”

Claude 通常会努力遵守你的指令，而正因为 Skills 复用性极强，你要格外小心别把指令写得过于具体。给 Claude 提供它需要的信息，但也要留出让它根据实际情况灵活调整的空间。

例如：

【过于死板】

第一步：运行 git log 找到提交。
第二步：运行 git cherry-pick
第三步：如果有冲突，运行 git status 列出它们。
第四步：打开每个冲突文件。
第五步：对每个 <<< 标记，决定保留哪一边。
第六步：对每个解决完的文件运行 git add，然后……

【更好的写法】

把这个提交 cherry-pick 到一个干净的分支上。解决冲突时保留原意图。如果无法干净落地，解释原因。

想清楚初始化配置

有些 Skills 需要用户提供上下文才能完成配置。比如你在做一个把日报发到 Slack 的 Skill，你可能希望 Claude 主动询问要发到哪个 Slack 频道。

一个好的模式是：像上面的例子那样，把这些配置信息存到 Skill 目录下的 config.json 文件里。如果配置尚未设置，Agent 就可以向用户询问这些信息。

如果你希望 Agent 以结构化的多选题形式提问，可以指示 Claude 使用 AskUserQuestion 工具。

（配图说明：standup-post/SKILL.md 中有一行!cat ${CLAUDE_SKILL_DIR}/config.json，这行会在 Claude 读取提示词之前作为 shell 命令执行，若输出 NOT_CONFIGURED，就问用户"发到哪个 Slack 频道？贴一份你喜欢的日报样例"，然后把答案写进 config.json。）

描述是写给模型看的，不是写给人看的

Claude Code 启动会话时，会为每个可用 Skill 及其描述（description）生成一份清单。Claude 正是扫描这份清单来判断"这个请求有没有对应的 Skill？"。这意味着 description 字段不是一段简介，而是对"何时该触发这个 Skill"的说明。

在描述中带上触发词会很有帮助，比如babysit-pr的描述里就包含"babysit"这样的触发词。

帮助 Claude"记住"事情

有些 Skills 可以通过在自身内部存储数据来获得某种"记忆"。存储形式可以简单到一个只追加的文本日志文件或 JSON 文件，也可以复杂到一个 SQLite 数据库。

比如，一个standup-postSkill 可以维护一个 standups.log，记录它写过的每一篇日报。这样下次运行时，Claude 会读取自己的历史记录，知道昨天以来发生了什么变化。

你可以使用环境变量${CLAUDE_PLUGIN_DATA}来获得一个稳定的目录用于存储数据。

（配图说明：这个文本日志文件帮助 Claude 记住过去的事件，比如"评审过 Sarah 的鉴权 PR"。）

存放脚本，生成代码

你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，可以让它把回合（turns）花在"组合"上，决定下一步做什么，而不是重新构造样板代码。

比如在你的data-scienceSkill 中，可以内置一个从事件源拉取数据的函数库。为了让 Claude 完成复杂分析，你可以给它一组这样的辅助函数。

然后 Claude 就能动态生成脚本，把这些功能组合起来，完成更高级的分析，比如回答"周二那天发生了什么？"

使用按需触发的 Hooks

Skills 可以包含只在该 Skill 被调用时才激活、且仅持续当前会话的 hooks。这适合那些更"有主见"的 hooks，你不想让它一直开着，但有时又极其有用。

例如：

/careful 通过 Bash 的 PreToolUse 匹配器，拦截 rm -rf、DROP TABLE、强制推送、kubectl delete。只有当你明确知道自己在动生产环境时才需要它，一直开着会把你逼疯。
/freeze 拦截任何不在指定目录内的 Edit/Write。调试时很有用：“我只想加日志，但老是忍不住顺手’修复’无关代码。”

四、分发 Skills

Skills 最大的好处之一，就是可以分享给团队里的其他人。

分享 Skills 有两种方式：

把 Skills 提交到你的代码仓库中（放在./.claude/skills目录下）；
制作一个插件（plugin），并搭建一个 Claude Code 插件市场（marketplace），让用户上传和安装插件（详见文档）。

对于跨仓库较少的小团队，直接把 Skills 提交进仓库就很好使。但每个签入的 Skill 都会给模型的上下文增加一点负担。随着规模扩大，一个内部插件市场可以让你分发 Skills，并让团队自行决定安装哪些，同时还能包含一个初始化配置流程。

五、管理 Skills 市场

如何决定哪些 Skills 进入市场？大家又如何提交？

在 Anthropic，我们没有一个中心化团队来做决定；相反，我们尝试让最有用的 Skills 自然地涌现出来。如果有人有一个想让大家试用的 Skill，他们可以把它上传到 GitHub 上的一个沙盒文件夹，然后在 Slack 或其它论坛里推荐大家使用。

一旦某个 Skill 获得了足够的认可度（由 Skill 的所有者自行判断），就可以提一个 PR，把它移入市场。

六、组合 Skills

你可能希望 Skills 之间相互依赖。比如，你可能有一个文件上传 Skill 负责上传文件，还有一个 CSV 生成 Skill 负责生成 CSV 并调用上传。这种依赖管理目前还没有内建到市场或 Skills 机制中，但你只需按名字引用其它 Skills，只要它们已安装，模型就会调用它们。

七、度量 Skills

为了了解一个 Skill 的表现，我们使用一个 PreToolUse hook 来记录公司内部 Skill 的使用情况（示例代码见原文链接）。这意味着我们能发现哪些 Skill 受欢迎，或者哪些 Skill 的触发率低于预期。

八、开始行动

Skills 的最佳实践仍在演进之中。我们最好的 Skills，大多起步时只是寥寥几行加一个避坑点，然后随着 Claude 不断撞见新的边界情况，大家不断往里添砖加瓦，它们才变得越来越好。

理解 Skills 最好的方式就是：动手开始，不断试验，看看什么对你有效。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

在这里插入图片描述

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～