Ru果你Yi经习惯了每天打开 Claude Code，敲几行指令，kan着它帮你生成代码、跑测试，甚至帮你修 Bug，那你可NengYi经体会到了 AI 辅助编程的甜头。但不知道你有没有这种感觉：有时候 Claude 像个刚入职的实习生，虽然听话，但总得盯着，生怕它走偏；而有时候，它又像个配合多年的老搭档，你只需给个眼神，它就知道该干什么。

这中间的差别，往往不在于模型本身，而在于你如何定义和打磨你的 Skill。

Zui近，我深入研读了 Anthropic 工程师 Thariq 分享的一篇关于 Skill 的实战感触颇深。这篇文章不是写给新手的入门指南，而是面向那些Yi经写过一两个 Skill，却总觉得差点意思的资深开发者。我们今天要聊的，就是如何把一个“Neng用”的 Skill，通过系统化的重构和细节打磨，变成一个“好用”的利器。

别把 Skill 仅仅当成 Prompt 模板

这是hen多人Zui容易陷入的误区。大多数人的起步方式douhen简单：新建一个 .md 文件，写几段提示词，然后用 /my-skill 调用。这确实Neng跑，但这就像是用记事本写代码，完全没用到 IDE 的强大功Neng。

本质上，Skill 不是一个简单的文本文件，而是一个Ke以携带脚本、数据和配置的文件夹。当你把 Skill 视为一个容器时思路就打开了。在这个文件夹里你Ke以放参考文档、放代码模板、放验证脚本，甚至放配置文件。Claude 会像人类工程师浏览项目目录一样，自动发现这些文件，并在需要的时候读取它们。

这种结构化的好处在于，Claude Ke以把精力花在geng高层次的“编排”和“决策”上，而不是每次dou从头开始写那些枯燥的样板代码。你给它提供了工具库，它自然就Neng造出geng精密的机器。

九大分类：找到你的 Skill 归属

Anthropic 内部曾把所有在用的 Skill 梳理了一遍，发现它们自然而然地聚成了九个类别。这其实是一个hen有意思的现象：好的 Skill 总是干净利落地落在某一类里而那些让人困惑、不好用的 Skill，往往试图横跨好几类，结果什么douZuo不好。

虽然这不是绝对的标准，但你Ke以把它当作一份自检清单，kankan你的团队在哪些方向上还是空白：

脚手架生成为代码库中的特定功Neng生成框架样板。特别是当你的需求包含自然语言描述，纯代码模板覆盖不了时这类 Skill 尤其好用。

库用法指南解释如何正确使用某个库、CLI 或 SDK。这Ke以是你们内部自研的库，也Ke以是那些 Claude 经常用错的公共库。

工作流打包把重复性的工作流打包成一条命令。指令通常不复杂，但往往会依赖其他 Skill 或 MCP。

测试与验证描述如何测试或验证代码是否正常工作。通常搭配 Playwright、tmux 等外部工具。Thariq 甚至认为，验证类 Skill 值得一个工程师花一整周来打磨，比如让 Claude 录制测试过程的视频，或者在每一步Zuo程序化断言。

部署运维帮你拉取、推送和部署代码。

事故调查接收一个症状，走完多工具调查流程，Zui后输出一份结构化的报告。

数据与监控连接你的数据和监控栈，里面包含数据获取脚本、Dashboard ID、常用查询工作流等。

维护操作执行例行维护和运维操作。其中一些涉及破坏性操作，需要特别加上护栏。

代码质量在组织内强制执行代码质量标准。Ke以包含确定性脚本以获得Zui大稳健性，也Ke以作为 Hooks 或 GitHub Action 的一部分自动运行。

核心心法：渐进式披露

写 Skill 和写代码有一个共通点：你不可Neng一次写完就完美收官。模型在升级，工具链在变，团队的工程实践也在调整。今天好用的 Skill，过几个月可Neng就需要改。

Thariq 提到了一个非常精彩的概念，叫“渐进式披露”。这不仅是写 Skill 的技巧，geng是信息架构的艺术。

简单来说主文件给方向，子文件给细节。Claude 非常聪明，它知道什么时候需要kan什么。你不需要在主指令文件里事无巨细地塞进所有 API 文档，那样只会让 Signal被 Noise淹没。

Zuo法其实hen简单：在主文件里列出子文件的路径和用途，Claude 会在合适的时机自己去读。比如你Ke以把完整的 API 签名放在 references/api.md，把正确用法示例放在 references/examples.md。主文件只需要告诉 Claude：“嘿，遇到不懂的 API 去kan那个文件夹。”

这种结构不仅清晰，而且极大地提高了 Skill 的可维护性。

Zui有价值的部分：Gotchas

Ru果问我 Skill 里哪一部分含金量Zui高，那绝对是 Gotchas。

这些不是从教科书上抄来的，而是从 Claude 实际踩坑中积累下来的血泪经验。每次 Claude 在某个 Skill 上犯错，就把这个错误加到 Gotchas 里。时间一长，Gotchas 会变成 Skill 里Zui有用的部分，信号密度极高。

比如你Ke以专门建一个 gotchas.md，里面记录那些 Claude 容易混淆的边缘情况、特定的参数组合陷阱，或者是你们团队特有的“反直觉”约定。这就像是一个老工程师给新人的“防坑指南”，让 Claude 少走弯路。

技巧一：Description 是触发器，不是摘要

hen多人习惯把 description 字段当成摘要来写，这其实是个误区。在 Claude 的逻辑里这个字段geng像是“触发条件”。

Claude Code 启动时会用 description 字段建索引。它不是在这个 Skill 是什么而是在告诉 Claude：“什么场景下该用这个 Skill？”

kankan这个对比：

---
# 当摘要写——太模糊，Claude 不知道什么时候该触发
description: "一个用于处理数据库迁移的工具"
# 当触发条件写——明确场景，Claude Neng准确匹配
description: "当需要创建、修改或回滚数据库迁移文件时使用。适用于 schema 变geng、数据迁移和索引操作。"
---

后者明确指出了“创建、修改、回滚”以及“schema 变geng”这些关键词，Claude 在识别到这些意图时就Neng精准地激活对应的 Skill。

技巧二：用 Config 文件Zuo初始化

有些 Skill 需要用户提供上下文才Neng工作，比如数据库连接串、服务名称、Slack 频道等。Ru果每次调用dou让用户手动输入，那体验就太糟糕了。

一个实用的技巧是在 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 第一次运行时会引导用户完成配置，之后就变成了“开箱即用”的状态。

技巧三：善用 Hooks 实现模式切换

你有没有遇到过这种情况：为了防止 Claude 犯错，你在全局配置里加了一堆防护规则，结果平时正常用的时候也束手束脚？

Skill 提供了一个geng优雅的解决方案：Hooks。Skill Ke以注册只在被调用时激活、持续到会话结束的 Hooks。这意味着你Ke以Zuo“模式切换”类的 Skill。

这些 Hooks 只在你主动调用对应 Skill 时才启动，比全局配置里加一堆规则干净得多。需要的时候开，不需要的时候不碍事。这种“按需加载”的哲学，让系统geng加清爽可控。

实战案例：Signup Verifier

光说不练假把式，我们来kan一个具体的例子。假设我们要写一个用于验证注册流程的 Skill，它可Neng长这样：

.claude/skills/signup-verifier/
├── SKILL.md              # 主指令文件
├── scripts/
│   ├── run-flow.ts        # 封装好的 Playwright 测试流程
│   ├── assert-state.ts    # 状态断言工具
│   └── capture-video.ts   # 录制测试视频
└── lib/
    └── test-helpers.ts    # 公共测试辅助函数

在这个结构里Claude 拿到这些脚本后只需要决定什么时候调用哪个、传什么参数，不用每次从零写测试代码。执行的稳定性和一致性dou会好hen多。你甚至Ke以加一个脚本，让测试失败时自动录制视频，方便你回放排查。

关键在于意图，而非键盘操作

在编写 Skill 指令时有一个原则需要时刻铭记：不需要事无巨细地说明使用什么命令、如何Zuo具体某个操作。

Claude 毕竟是个编程专家，它知道怎么执行。你要告诉它的是“Zuo什么”和“按什么顺序Zuo”，而不是“怎么敲键盘”。比如不要告诉 Claude “怎么写 React 组件”，而是告诉它“我们的 React 组件有哪些不走寻常路的约定”。

Skill 会被反复使用，过于具体的指令反而成为限制。给 Claude 足够的信息，同时留出适应空间，它才Neng发挥出Zui大的潜力。

维护与分发：让 Skill 活起来

不管你走哪条路，Skill 应该像代码一样被维护。有人用、有人改、有人加 Gotchas，它才会越来越好。Anthropic 内部大部分 Skill dou是从几行文字和一条 Gotcha 开始的，因为不断有人在 Claude 踩坑后往里面加东西，才变成了现在的样子。

写好了 Skill，怎么让团队用上？通常有两条路：

1. 提交到仓库把 Skill 放在 .claude/skills/ 目录下随代码一起版本管理。适合小团队，简单直接。

2. 插件市场Zuo成 Claude Code Plugin，通过内部插件市场分发。适合需要跨团队分发的大型组织。

此外有些 Skill Ke以在目录内存储数据来实现“记忆”。简单的Ke以用追加写入的文本日志，复杂的Ke以用 SQLite。一个实用技巧是：让 Skill 把每次执行结果写入日志文件，Claude 后续执行时Ke以参考历史记录，保持一致性。不过要注意，Skill 目录内的数据在升级时可Neng被删除，稳定的存储路径应该用 ${CLAUDE_PLUGIN_DATA}。

从“Neng用”到“好用”，中间隔着的是对细节的极致追求和对 AI 认知模式的深刻理解。不要指望一次性Neng写出完美的 Skill，从你Zui痛的那个重复性工作开始，写一个Zui小的 Skill，跑起来每次 Claude 犯错或执行遇到问题就加一条 Gotcha。

慢慢地，你会发现，Claude 不再只是一个简单的聊天机器人，而是一个真正懂你业务、懂你代码库的超级工程师。这才是 Skill 的真正魅力所在。

---