Claude Code Skill开发实战：从基础应用到高效进阶

最近，Anthropic工程师Thariq分享了一篇关于Claude Skill的深度实践指南，其中有一个核心观点颠覆了许多开发者的认知：Skill并非一个简单的提示词模板，而是一个能够容纳脚本、数据和配置的完整文件夹。

这个定义与大多数人的使用习惯截然不同。许多开发者初次接触Skill的路径是：创建一个Markdown文件，编写几段提示词，通过/my-skill命令调用，然后可能觉得“功能有限”。但事实上，Anthropic内部有数百个Skill在日常工作中高效运行，它们的形态远比单个Markdown文件要丰富和强大得多。

本文面向已经使用过Claude Code、并编写过一两个基础Skill的工程师，旨在系统性地整理一套将Skill从“能用”提升到“好用”的实战方法论。

核心要点速览

1. Skill的本质是文件夹，而非单一文件。脚本、模板、配置文件均可放入其中，Claude会自动发现并调用。
2. Anthropic内部将Skill归纳为九大类别：知识库、验证测试、数据观测、工作流自动化、代码脚手架、代码质量、DevOps、问题排查、运维维护。
3. Skill中最有价值的部分往往是“Gotchas”（常见陷阱），Claude踩过的坑比正面指令更具指导意义。
4. 采用渐进式披露管理上下文：主文件提供方向指引，子文件按需提供细节。
5. 编写Skill需保持灵活性，为Claude留出适应空间，清晰说明意图和执行顺序即可。
6. 利用config.json存储用户个性化配置，使Skill能灵活适配不同开发环境。
7. 为Skill配备脚本和函数库，让Claude专注于工作流编排，而非重复编写样板代码。
8. Skill可以注册作用域内的Hooks，仅在调用时激活，实现精准的防护或模式切换。
9. 团队共享Skill有两条路径：提交至代码仓库的.claude/skills/目录，或通过插件市场进行分发。
10. Skill需要持续维护与迭代，模型升级、工具链变化、团队实践演进都需要相应的适配更新。

重新认识Skill：超越Markdown文件

多数人编写Skill的方式是：新建一个.md文件，填入提示词，然后用/my-skill调用。这种方式虽然能运行，但远未发挥Skill的全部潜力。

Skill的真正载体是一个文件夹。除了核心指令文件，你还可以在其中放置参考文档、代码模板、验证脚本、用户配置文件等。Claude会自动扫描并索引这些资源，在需要时智能读取。

一个结构清晰、功能完备的Skill目录示例如下：

.claude/skills/my-skill/
├── SKILL.md          # 主指令文件
├── references/
│   └── api.md        # 详细的API参考文档（支持按需加载）
├── assets/
│   └── template.tsx  # 可复用的代码模板文件
├── scripts/
│   └── validate.sh  # 自动化验证脚本
└── config.json       # 用户个性化配置（可选）

Claude启动时会扫描所有Skill的description字段来建立索引。当你调用某个Skill时，它会优先加载主指令文件，然后根据任务需求，智能探索并加载文件夹中的其他相关文件。

Thariq将这种设计哲学称为“渐进式披露”：主文件勾勒框架与目标，子文件承载具体细节，由Claude自主判断在何时、需要何种信息。

九大分类体系：构建你的Skill能力矩阵

Anthropic内部对所有在用Skill进行了梳理，发现它们自然地聚合成了九个核心类别。一个优秀的Skill通常能清晰地归属于某一类，而那些令人困惑的Skill往往试图跨越多类职责。

这虽然不是官方标准，但完全可以作为一份团队自检清单，帮助你识别在哪些方向上还存在能力空白。

1. 知识库类（Knowledge Skills）

这类Skill主要解释如何正确使用特定的库、CLI工具或SDK。可以是内部私有库，也可以是Claude容易误用的公共库。

它们通常包含一个参考代码片段库和一份详细的“常见陷阱”清单。

.claude/skills/billing-lib/
├── SKILL.md          # 核心使用说明与常见误区
├── references/
│   ├── api.md        # 完整的API签名与说明
│   └── examples.md   # 最佳实践示例代码
└── gotchas.md        # 关键踩坑记录与避坑指南

典型应用场景包括：

• billing-lib —— 内部计费库的边界情况处理与易错点详解
• internal-platform-cli —— 内部CLI每个子命令的使用场景与参数解析
• frontend-design —— 指导Claude正确理解与应用团队的设计系统规范

2. 验证测试类（Verification Skills）

这类Skill描述如何测试或验证代码功能是否正常工作，通常与Playwright、tmux等外部测试工具结合使用。

按照Thariq的经验，打磨一个优秀的验证类Skill值得投入一整周时间。你可以让Claude录制测试过程的视频，或在每一步执行程序化的状态断言。

典型场景：

• signup-flow-driver —— 在无头浏览器中自动化执行注册、邮箱验证、用户引导全流程，并对每一步进行状态断言
• checkout-verifier —— 使用Stripe测试卡驱动结账UI，验证订单状态与支付回调
• tmux-cli-driver —— 针对需要TTY交互的CLI工具进行自动化测试

3. 数据与观测类（Data & Observability Skills）

这类Skill连接你的数据源与监控栈，包含数据获取脚本、Dashboard ID、常用查询模式与工作流。

典型场景：

• funnel-query —— 明确“从用户注册到激活再到付费”需要关联哪些数据表与事件，并指明规范的用户ID字段所在位置
• grafana —— 封装数据源UID、集群名称、以及从问题现象到对应Dashboard的快速映射关系

4. 工作流自动化类（Workflow Automation Skills）

将重复性的手动工作流打包成一条自动化命令。指令本身可能不复杂，但通常会依赖其他Skill或MCP（模型上下文协议）工具。

一个实用技巧：让Skill将每次执行的关键结果写入日志文件，这样Claude在后续执行时可以参考历史记录，保持输出格式与逻辑的一致性。

典型场景：

• standup-post —— 自动聚合Jira Ticket、GitHub活动记录和Slack相关消息，生成格式化的每日站会汇报
• weekly-recap —— 合并PR列表、关闭的Ticket、部署记录，自动生成项目周报

5. 脚手架类（Scaffolding Skills）

为代码库中的特定功能或模块生成标准化的框架代码。当你的脚手架需求包含无法用纯代码模板覆盖的自然语言描述时，这类Skill特别有用。

典型场景：

• new-migration —— 数据库迁移文件模板 + 常见陷阱提醒（如锁表风险）
• create-app —— 预装了认证、日志、监控和部署配置的新应用项目模板

6. 代码质量类（Code Quality Skills）

在组织内强制执行统一的代码质量标准。可以包含确定性的检查脚本以确保最大稳健性，也可以作为Git Hooks或GitHub Action的一部分自动运行。

典型场景：

• adversarial-review —— 生成一个“挑剔的审阅者”子Agent来寻找代码缺陷，修复后迭代审阅，直到只剩下细微建议
• code-style —— 强制执行Claude默认处理不佳的特定代码风格（如导入顺序、命名约定）
• testing-practices —— 定义如何编写测试、测试哪些边界条件、以及测试的组织规范

7. DevOps类

协助完成代码的拉取、推送、构建与部署等CI/CD相关操作。

典型场景：

• babysit-pr —— 监控Pull Request状态，自动重试不稳定的CI构建，解决合并冲突，并在条件满足时启用自动合并
• deploy-service —— 标准化构建、冒烟测试、灰度发布、错误率对比与自动回滚流程
• cherry-pick-prod —— 自动化隔离worktree、执行cherry-pick、解决冲突、并按模板创建PR

8. 问题排查类（Triage & Debugging Skills）

接收一个症状描述（如Slack线程、监控告警、错误堆栈），引导Claude走完多工具联合调查的标准化流程，最终输出结构化的排查报告。

典型场景：

• service-debugging —— 建立从症状（如高延迟、5xx错误）到排查工具（如日志、指标、链路追踪）再到具体查询模式的映射关系
• oncall-runner —— 拉取当前告警，检查常见嫌疑项（如近期部署、依赖服务状态），格式化输出发现结果
• log-correlator —— 给定一个请求ID，自动从所有相关微服务或系统中拉取匹配的日志条目

9. 运维维护类（Maintenance & Operations Skills）

执行例行的系统维护和运维操作。其中一些操作可能具有破坏性，因此需要内置安全护栏和确认机制。

典型场景：

• orphan-cleaner —— 自动发现孤立的Kubernetes Pod或云存储Volume，将列表发送至Slack等待确认，确认后进行级联清理
• dependency-management —— 标准化组织内部的依赖升级、漏洞修复审批工作流
• cost-investigation —— 调查“为何存储或出口带宽费用激增”，附带具体的云存储Bucket、查询模式与优化建议

八大实战技巧：打造高可用Skill

了解分类只是方向，决定Skill是否好用的关键在于具体的编写实践。以下是Anthropic内部总结的核心经验。

技巧一：聚焦于非默认知识

Claude对你的代码库已有基础认知，对通用编程概念更是熟悉。因此，知识类Skill应重点传递那些Claude不知道的、你们团队特有的“隐性知识”。

换言之，不要花费篇幅解释“如何编写一个React组件”，而应着重说明“我们团队的React组件有哪些与众不同的约定或反模式”。

技巧二：持续积累“Gotchas”

Skill中信息密度最高、最实用的部分，往往是记录踩坑经验的“Gotchas”。这些内容应从Claude的实际错误中持续积累和提炼。

每次Claude在某个Skill相关任务上犯错，就把这个错误案例和解决方案添加到Gotchas中。长此以往，Gotchas将成为Skill中最宝贵的资产。

## 常见陷阱 (Gotchas)
- 切勿使用 `client.query()` 的默认超时设置，我们的数据库集群在业务高峰期需要至少30秒
- `user_id` 字段在events表中实际列名为 `uid`，而非 `user_id`
- 创建数据库迁移文件后，必须先运行 `make generate` 命令，否则ORM类型定义不会自动更新

技巧三：善用渐进式披露管理上下文

既然Skill是一个文件夹，就应充分利用文件系统作为上下文管理的天然工具。

实现方法很简单：在主指令文件中清晰列出子文件的路径和用途，Claude会在合适的时机主动读取。

## 参考资料
- 详细的API签名和用法示例请参阅 `references/api.md`
- 可复用的代码模板位于 `assets/` 目录下，创建新组件时可直接复制使用
- 常见问题排查流程已总结在 `references/troubleshooting.md` 中

这比将所有内容塞进一个庞大的Markdown文件要高效得多，既节省上下文Token，又赋予Claude按需获取信息的灵活性。

技巧四：保持灵活，而非死板规定

Skill会被反复使用，过于具体和僵化的指令反而会成为限制。应为Claude提供足够的背景信息，同时保留适应具体情况的弹性空间。

关键在于：无需事无巨细地规定使用什么精确命令、如何执行每个底层操作。应清晰表明任务意图和需要完成的具体步骤顺序。Claude知道如何执行命令，你需要告诉它的是“做什么”和“按什么顺序做”，而不是“如何敲击键盘”。

# 过于死板（不推荐）
创建组件时必须严格使用以下模板，不得修改任何部分...
执行 mkdir -p src/components/MyComponent
执行 cp template.tsx src/components/MyComponent/index.tsx
执行 sed -i 's/Template/MyComponent/g' ...

# 灵活适应（推荐）
创建组件时请参考 `assets/template.tsx` 的基本结构。可根据具体功能需求进行调整，但请遵循以下团队约定：
- 使用命名导出（named export）
- 将Props类型定义置于组件函数上方
- 组件内部错误使用ErrorBoundary组件进行包裹

技巧五：精心编写Description字段

Claude Code启动时会使用Skill的description字段来建立索引。description不是内容摘要，而是触发条件，它需要清晰地告诉Claude在什么场景下应该启用这个Skill。

---
# 像写摘要一样——过于模糊，Claude无法准确判断触发时机
description: "一个用于处理数据库迁移的工具"

# 像写触发条件一样——明确场景，Claude能精准匹配用户需求
description: "当需要创建、修改或回滚数据库迁移文件时使用。适用于schema变更、数据迁移、索引创建与删除等操作场景。"
---

技巧六：利用Config文件实现个性化初始化

某些Skill需要用户提供特定上下文才能工作，例如数据库连接字符串、服务名称、Slack频道ID等。最佳实践是在Skill目录下放置一个config.json模板文件。当配置缺失时，Claude会主动引导用户输入必要信息并保存。

// .claude/skills/deploy-service/config.json
{
  "service_name": "user-api",
  "staging_url": "https://staging.example.com",
  "slack_channel": "#deploys",
  "rollback_threshold_error_rate": 0.05
}

这样，Skill在首次运行时将引导用户完成一次性配置，后续所有执行都将基于此配置，无需重复输入。

技巧七：为Skill配备脚本与函数库

为Skill配备封装好的脚本和工具库，可以让Claude将精力集中在工作流编排和关键决策上，而不是每次都从头编写样板代码。

例如，对于一个验证类Skill，与其在Markdown中详细描述“如何使用Playwright测试登录流程”，不如直接提供一个封装好的测试脚本：

.claude/skills/signup-verifier/
├── SKILL.md
├── scripts/
│   ├── run-flow.ts      # 封装好的Playwright端到端测试流程
│   ├── assert-state.ts  # 通用的状态断言工具函数
│   └── capture-video.ts # 测试过程录屏功能
└── lib/
    └── test-helpers.ts  # 公共测试辅助函数库

Claude获得这些脚本后，只需要决定在何时调用哪个脚本、传递什么参数，无需每次从零开始编写测试代码。这极大地提升了执行的稳定性、一致性和效率。

技巧八：为Skill添加记忆能力

某些Skill可以通过在目录内存储数据来实现“记忆”功能。简单的可以使用追加写入的文本日志，复杂的可以集成轻量级数据库如SQLite。

需要注意的是，Skill目录本身在升级时可能被覆盖，因此稳定的数据存储路径应使用环境变量${CLAUDE_PLUGIN_DATA}。

## 执行记录与记忆
每次执行后，将结果摘要以JSON Lines格式追加到 `${CLAUDE_PLUGIN_DATA}/execution-log.jsonl` 文件中，记录：
- 执行时间戳
- 输入的参数
- 执行状态（成功/失败）
- 关键输出或错误信息
下次执行时，Claude会先读取最近的5条记录，以保持操作的一致性（例如，避免重复执行相同操作）。

Skill作用域Hooks：按需激活的智能守卫

Skill可以注册一种特殊的Hooks，它仅在Skill被调用时激活，并持续生效直到当前会话结束。这允许你创建“模式切换”类的Skill：

• /careful —— 通过PreToolUse匹配器，拦截可能危险的命令，如rm -rf、DROP TABLE、force-push、kubectl delete等，并请求二次确认。
• /freeze —— 阻止对指定目录之外的任何文件进行编辑或写入操作，保护核心代码。

这些Hooks只在你主动调用对应Skill时才启动，比在全局配置中添加一堆防护规则要清晰、可控得多。需要防护时开启，不需要时则完全无干扰。

团队共享与协作

编写好一个Skill后，如何让团队其他成员也用上？主要有两种共享路径：

提交至代码仓库：将Skill放置在项目根目录的.claude/skills/文件夹中，随代码库一起进行版本管理。这种方式简单直接，适合小团队或项目特定的Skill。

发布至插件市场：将Skill打包为Claude Code Plugin，通过内部或公共的插件市场进行分发。这种方式更适合需要跨团队、跨项目共享的通用型Skill。

无论选择哪条路径，Skill都应该像源代码一样被认真维护。只有被人使用、被人改进、不断积累Gotchas，它才会变得越来越有价值。Anthropic内部大多数优秀的Skill，最初都只是几行简单的指令和一条关键的踩坑记录，正是由于持续有人在使用中发现问题并加以完善，才逐渐演变为现在强大的样子。

归根结底，编写Skill和编写软件一样，不是一劳永逸的事情。大语言模型在持续升级，开发工具链在不断变化，团队的工程实践也在逐步演进。今天好用的Skill，几个月后可能就需要调整。最好的实践是从你最痛的那个重复性工作开始，创建一个最小可用的Skill，让它跑起来，然后每次Claude犯错或执行遇到障碍时，就添加一条Gotcha或优化一个细节，持续迭代，使之日益精进。