别把Skills当插件

AI 工程化 · 原理拆解

别把Skills当插件

上周有个读者在群里抱怨，说 Claude Code 的 Skills 功能太鸡肋，写了半天不生效。我看了他发出来的目录截图，发现他把 Skill 文件当 Cursor Rules 那种全局配置去写了。这个误解太常见了。

01 / 为什么我要认真研究 Skills

用传统 AI 编程工具时，我们总在做重复劳动：写完代码，切到聊天框，输入’帮我检查一下这段代码有没有安全问题’，再输入’顺便写个单测’。

这些操作本质上是在手动管理上下文。你其实是在充当人肉路由器，把不同的提示词在不同时机塞给大模型。

这种碎片化操作极度打断心流。写完一个接口，切到浏览器开 ChatGPT，复制代码，等它吐完单测，再复制回 IDE。如果单测没过，又要切回去重来一轮。

Claude Code 的 Skills 解决的不是’怎么写’的问题，而是’什么时候写’的问题。它把触发条件和指令绑定在了一起。

02 / Skills 不是插件，是文件即提示词

Cursor Rules 是一个大而全的文本块，每次开项目全量加载，项目越大，前面垫的废话越多。VS Code 插件是一套有生命周期的 JS API，能弹窗、改 UI、监听文件变动。

Claude Code 的 Skills 两者都不是。

它是一堆放在特定目录下的 Markdown 文件。Claude 启动时不去读它们，只有当你触发了某个条件，它才把对应的文件内容塞进当前的对话上下文里。

这种’文件即提示词’的设计，让你可以把复杂的规范拆散，按需加载。没有 UI 渲染，没有生命周期钩子，你只需要建个文件夹，按规矩放文件就行。

03 / Claude Code 内部怎么处理这些文件

很多人以为把文件丢进 `.claude/skills/` 目录，Claude 就会自动全盘吸收。实测下来并不是这样。

它的内部流程是：扫描目录建立索引 → 接收你的指令 → 匹配指令与 Skill 的触发词或元数据 → 将匹配到的 Skill 内容注入当前上下文 → 执行。

注意那个’建立索引’的环节。Claude Code 启动时，会扫一遍 skills 目录，解析所有 `.md` 文件的 YAML 头部，建一个轻量级的索引表。这个时候，它完全不读 Markdown 正文。

这套机制的核心是懒加载。如果你的项目里有 20 个 Skill，每次对话它不会傻乎乎地把 20 个文件全读一遍，那会瞬间撑爆 Token 预算。只有当你输入了 `/skill code-review`，或者你的提问里命中了 YAML 里定义的 trigger，它才去磁盘上把那个特定文件的正文捞出来。

04 / 创建你的第一个 Skill

创建 Skill 不需要学新语法，本质就是写 Markdown。先在项目根目录执行 `mkdir -p .claude/skills` 建好目录，然后创建一个 `.md` 文件。

文件开头必须是一段 YAML frontmatter，用来告诉 Claude 这个 Skill 叫什么、干什么、什么时候触发。下面是一个完整的代码审查 Skill 示例：

写好文件后，直接在 Claude Code 里输入 `/skill code-review 检查 src/auth.py 的变更` 就能显式调用。如果你在 frontmatter 的 `triggers` 里配了’审查’，哪怕不输斜杠命令，只要你的对话里带这两个字，它也会自动匹配。

05 / 写好 Skill 的几个心得

很多人写的 Skill 不生效，问题出在指令太抽象。

如果你在 Skill 里写’要求写干净的代码’，Claude 会按它自己的理解去凑。但如果你把’什么是干净’拆解成具体的规则，比如’禁止使用 var 声明’、’函数参数超过两个必须用对象解构’，产出质量会有质的飞跃。

除了指令具体，还要给输出格式打样。不要只说’输出审查结果’，要告诉它’用红黄绿圆标标注严重程度，并给出代码示例’。大模型是模仿大师，你给它什么格式的模板，它就吐什么格式的砖。

06 / 我实际在用的几个 Skill

理论讲多了没意思，直接分享我日常高频用的三个模板。这些你复制过去改改就能用。

测试生成 Skill 是我最省心的一个。它规范了 pytest 的写法，强制要求用 fixtures 管理测试数据，杜绝在用例里硬编码。而且它规定了测试函数名必须描述预期行为，比如 `test_user_login_with_wrong_password_raises_error`，谁敢写 `test_1` 这种垃圾命名，它会在输出里直接报错。这个 Skill 把我写单测的时间缩短了一大半，因为我不需要再花时间去纠正它的格式了。

提交信息 Skill 解决了我的词穷问题。以前每次 `git commit` 都要想半天怎么写。现在这个 Skill 会自动分析 `git diff` 的内容，按 Conventional Commits 规范输出中文描述。如果它发现你这次提交里混杂了前端样式调整和后端接口改动，它会拒绝生成提交信息，提醒你拆分 commit。这就相当于在本地套了一层 CR。

部署前检查 Skill 是我的发版保险。以前发版前总是手忙脚乱，怕漏了什么。这个 Skill 被触发后，会按固定顺序跑测试、查 `.env` 文件有没有多加未在文档里声明的变量、对齐锁文件版本。任何一步失败，它都会直接中止流程并报错，绝不带着隐患上线。

生成单测 强制覆盖边界条件和异常情况，Mock 所有外部依赖，文件必须放 tests/ 目录

提交信息 自动分析 git diff，按 Conventional Commits 规范输出中文描述，发现不相关变更会提醒拆分 commit

部署前检查 按固定顺序跑测试、查 .env 变更、对齐锁文件，任何一步失败直接中止

07 / 踩了几个月坑之后的经验

用 Skill 这几个月，掉进过几个很耗时间的坑。这里直接列出来，你们遇到问题时可以对照排查。

很多人一上来就把公司几百行的开发规范全贴进一个 Skill 里。结果就是 Token 预算直接爆掉，或者关键指令被淹没在废话里，Claude 开始胡言乱语。Skill 最好控制在 50 行以内，超过的一定要按职责拆分。安全规范归安全规范，命名规范归命名规范。

触发词容易冲突也是个暗坑。别用 ‘fix’、’bug’ 这种太泛的词当 trigger。我有次配了个触发词叫 ‘api’，结果只要对话里提到 API，不管是在聊天气还是在查文档，这个 Skill 都会被拉出来，把上下文搞得一团糟。触发词要尽量长、尽量具体，最好是一句完整的话。

还要认清一点：Skill 只是’嘴’不是’手’。它不能直接帮你执行部署脚本，它只能输出检查结果。它本质上只是一段被条件触发的提示词。真正执行命令，还得靠 Claude Code 本身的工具调用能力，或者你自己手动敲。别指望写个 Skill 就能完全自动化一切。

Token 预算是硬约束 不要把整个团队规范塞进一个 Skill，按职责拆成多个小文件

触发词容易冲突 别用 ‘fix’、’bug’ 这种太泛的词当 trigger，会导致完全无关的对话也加载这个 Skill

Skill 只是’嘴’不是’手’ 它不能直接帮你执行部署脚本，它只能输出检查结果，执行还是得靠你或者 Claude 的其他工具调用能力

08 / 你的工作流里，什么最值得封装成 Skill

不要为了封装而封装。那些需要你频繁切换上下文、且格式要求高度固定的重复动作，才是 Skill 的最佳猎物。

怎么找？打开你的终端，敲下 `history | awk ‘{print $2}’ | sort | uniq -c | sort -rn | head`。看看哪些命令你每天在重复敲。

找出你每天在终端里重复敲的第三件事，那就是你的第一个 Skill。

LAST WORD

留给你的问题

你平时最烦哪个重复性动作？是写 CRUD 的样板代码，还是每次发版前手动核对配置？

在评论区说说你的痛点，我帮你看看能不能用 Skill 解决。