Agent Skills 实战指南：从零构建 Claude Code 专家级工作流

如果你这段时间正在用 Claude Code 写代码应该会有同感这个跑在终端里的 AI 助手写代码、查报错、改 bug 都很顺手可一旦碰到“特定领域的固定流程”它就开始自由发挥。比如你让它生成一次 PR 描述它今天给你写个长段落明天给你列三个要点你让它做一次代码审查它有时候真能揪出并发问题有时候又只会夸你代码写得不错。问题不在于 Claude 笨而是你没有给它一套“该领域的专家操作手册”。Agent Skills 要解决的就是这件事——把某一类任务的执行规范、模板、检查清单、示例打包成独立模块让 Claude Code 在识别到对应需求时按专家流程工作而不是凭感觉发挥。这篇文章我会从零开始讲清楚 Agent Skills 到底是什么、和 MCP 跟 CLAUDE.md 有什么区别、目录结构怎么摆、SKILL.md 怎么写再手把手带你把“代码审查”“PR 描述生成”“数据库 Schema 转 TypeScript 类型”三个实用技能做成专家模块。最后把我踩过的坑、排查方法和省 token 的技巧一并放出来。适合这几类人看刚把 Claude Code 装好但觉得它不够贴合自己工作流的想搞懂 Skills、MCP、CLAUDE.md 三者关系的以及准备在团队里统一 AI 工作流的同学。1. 先把概念盘清楚Agent Skills 到底是什么解决什么问题1.1 一个通才 AI 的尴尬和 Skills 的解题思路你让 Claude Code 解一道 LeetCode 题它很稳让它帮你重构一个函数它也很稳。但一旦任务变成“按你们团队的规范生成一条 Git 提交信息”或者“按照公司模板输出一份故障复盘报告”它就容易翻车。为什么因为这些任务是“约定大于能力”的领域的规范性、输出格式的固定性比模型本身的推理能力更关键。而 Claude Code 默认只带了一套通用的行为准则并不会自动知道你们团队的规范是什么。Agent Skills 就是用来补这块短板的。它在 Claude Code 里表现为一组可被按需调用的“技能包”每个技能包以一个文件夹存在里面有一份核心说明文件SKILL.md还可以附带脚本、模板、参考资料。当你在对话中提出的请求命中了某个技能的描述Claude 就会去读取这个技能包按里面的规则执行任务。没命中就不加载不影响普通对话。你可以把它理解成给一个全能实习生配了一整套岗位 SOP实习生本来就聪明缺的不是智商而是“咱们公司都是这么干的”那部分信息。Skills 就是把这些信息固化下来让 AI 每次做同类工作都稳定在一个水平线上不会今天超常发挥明天状态低迷。1.2 Skills 不是 MCP也不是 CLAUDE.md这三个概念放在一起最容易混。MCP 我记得以前解释起来要说半天现在一句话也能说清MCP 是给 AI 接外部工具和数据源的通道比如连数据库、读 GitHub Issue、调浏览器。Skills 不一样它不是连接外部世界而是给 AI 装上“内部专家手册”。一个管数据流通一个管行为规范。CLAUDE.md 则是另一个维度。它是 Claude Code 长期记忆的载体写在里面的内容会一直待在上下文里相当于全局配置。Skill 则是按需加载的局部配置只在触发时进入上下文。为了直观对比我给你列个表格维度CLAUDE.mdAgent SkillsMCP存放内容项目说明、通用约束、用户偏好特定任务的执行规范、模板、示例外部服务地址、工具定义、鉴权信息加载时机每次会话常驻上下文请求命中 description 时按需加载会话中持续可用调用时才发起请求典型用途“这个项目用 pnpm 不要用 npm”“生成 PR 描述时按模块列出改动”“读取 PostgreSQL 里的订单表结构”修改成本改一次影响所有对话改一个技能只影响对应场景需要调试服务端与鉴权我自己的比喻是这样CLAUDE.md 是入职手册Skills 是每个细分岗位的操作指南MCP 是员工手里的螺丝刀和电钻。入职手册你天天带身上操作指南要用的时候才翻电动工具是要接电才转的。三类东西解决三类问题不是替代关系是配合关系。2. 从 0 到 1先把 Claude Code 环境装明白2.1 安装前要准备什么虽然标题重点是 Skills但整个链路的地基还是 Claude Code 本身。很多人在这一步就卡住了所以我把环境准备也讲细一点。Claude Code 目前对 Node.js 版本有要求实测下来建议 Node 18 以上否则会遇到一些奇怪的报错。安装之前先确认环境node -v npm -v如果没装 Node先去 Node 官网装 LTS 版本这个不用我多说。装好之后安装 Claude Code 本身的方式很简单官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完以后没法直接确认版本可以跑一下claude --version能输出版本号就说明装上了。接下来是登录鉴权第一次在终端里输入claude会走一个浏览器登录流程登录你的 Anthropic 账号授权后终端就能直接调用。如果你的场景是团队协作或者接统一的 API 通道也可以设置环境变量ANTHROPIC_API_KEY跳过登录。这里多说一句很多人会用第三方兼容接口或本地模型来跑 Claude Code比如配置ANTHROPIC_BASE_URL指向 Ollama 或者 DeepSeek 这类服务。可行但注意版本兼容性。Claude Code 对底层模型的指令遵循能力要求很高本地小模型跑通用对话没问题跑复杂的 Skill 流程可能会“读懂了但不照着做”所以如果你一开始体验不好可以先换回官方模型把 Skills 机制跑顺了再接回你自己的模型通道。2.2 进入交互模式找到放 Skills 的目录安装完成后最基础的用法有两种。一种是直接在终端里带参数运行claude 帮我看一下这个项目里有没有未处理的 Promise另一种是敲claude进入交互式 REPL边聊边改代码。我日常工作基本都待在交互模式里因为要频繁让 AI 改文件、跑命令交互模式效率更高。进入项目目录后Claude Code 会自动感知当前工程。如果你想验证 CLI 是否正常工作可以先问它一句“当前项目用的什么技术栈”它应该会扫一下根目录的文件再回答你。Skills 的存放目录有两级用户级目录在~/.claude/skills/作用于你所有项目项目级目录在.claude/skills/只作用于当前仓库。我的建议是通用型技能放用户级比如“生成 Conventional Commits 提交信息”业务型技能放项目级比如“按本项目的数据字典生成 Service 层代码”。这样换项目时通用技能还在项目特定技能不会污染其他仓库。3. Agent Skills 的官方机制与目录结构先看标准答案3.1 一个 Skill 到底由什么组成第一次接触 Agent Skills 的人最容易犯的错是把它当成一个“提示词文件”。不是的一个 Skill 在文件系统里是一个独立的文件夹里面可以包含多个文件。官方约定的入口文件叫SKILL.md放在技能文件夹的根目录。一个最小可用的技能包长这样~/.claude/skills/ └── pr-description/ ├── SKILL.md └── references/ └── examples.md稍微复杂一点的可以带脚本.claude/skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ └── check_todo.py └── references/ └── security-checklist.mdClaude Code 启动的时候会去扫描这些目录把每个技能包的name和description记录下来形成一个“技能列表”。这个列表很小不会占用太多上下文。当你的提问命中某个技能包的描述时Claude 才会去读取完整的SKILL.md再按里面的步骤执行。这个按需加载的机制很关键你放几十个技能在目录里也不会把上下文撑爆。3.2 SKILL.md 的 frontmatter 怎么写才能触发准确SKILL.md 本质上是一份 Markdown 文件但开头必须带 YAML frontmatter用来声明技能的名称和触发描述。我见过不少人在这里翻车要么忘写 frontmatter要么 description 写得太抽象结果技能永远不被触发。一个标准写法是这样的--- name: pr-description-generator description: 当用户要求生成 PR 描述、Commit 提交信息或 Changelog 时使用。适用于 git diff 已完成、需要整理成结构化文本的场景。不要用于编写代码本身。 ---写 description 有几个原则。第一要写“当……时使用”的场景触发式语言不要写“这是一个生成 PR 描述的工具”这种名词解释式语言。第二要包含至少两三个同义触发词比如“PR”“Pull Request”“提交信息”“改动说明”。第三建议写一条“不要用于什么场景”的负向约束可以减少误触发。frontmatter 后面就是正文。正文是 Claude 执行这个技能时要遵守的操作说明你可以写步骤列表、输出模板、禁止事项、示例片段。这部分的自由度很高Claude 会把它当作在特定任务下的最高优先级指令去执行。4. 实操环节三个“专家模块”从零手写4.1 专家模块一代码审查助手Code Review Skill先说我自己用得最多的代码审查。以前我没做这个技能时让 Claude 做 review它给的反馈经常是“建议增加错误处理”“考虑边界条件”这种正确的废话。后来我写了一个 Code Review Skill强制规定了输出结构按严重程度分级、必须给文件路径和行号、必须给出具体修改建议还要把“只夸代码不挑问题”的行为直接禁止。SKILL.md 正文大概长这样当你执行代码审查时按以下清单逐项检查 1. 安全性注入风险、敏感信息硬编码、权限校验缺失 2. 正确性并发冲突、空指针、资源未释放 3. 可维护性重复代码、魔法数字、函数过长 4. 测试覆盖新增逻辑是否有对应测试 输出格式必须为 - 严重程度[P0/P1/P2] - 位置文件路径:行号 - 问题描述 - 修改建议 禁止输出“代码不错”“整体良好”之类的空泛评价。找不到问题时直接输出“未发现问题”不要硬凑。这个技能有没有用实测非常有用。Claude 在拿掉“礼貌性夸奖”的选项后会真的去尝试发现问题审查质量高了一个档次。你甚至可以再加一个脚本让它自动抓取 git diff 里改到的文件只针对增量代码做审查对应的命令放在 SKILL.md 里让 Claude 自己决定何时执行。4.2 专家模块二提交信息与 PR 描述生成器第二个技能解决的是我在开头提到的痛点PR 描述格式不稳定。我写过一阵子 Conventional Commits但每次让 AI 生成的时候它不是把范围写错就是漏掉 breaking change 的说明。后来我把团队模板写进了 Skill让它必须先运行git diff --stat再运行git diff然后按模板输出。这个技能的设计思路是“流程先行”。SKILL.md 里第一条就规定先执行 git diff --stat 了解改动范围。 再执行 git diff --unified200 获取详细代码变更。 基于 diff 输出以下格式 ## 变更类型 - [feat/fix/refactor/docs/chore] 一句话描述 ## 主要改动 - 按模块列表每条不超过一行 ## 测试影响 - 是否需要新增测试 / 回归测试范围 ## Breaking Changes - 无 / 有说明兼容性方案这里有个细节我特意写了“基于 diff 输出”而不是让它凭记忆猜功能点。因为 Claude 有时候会根据文件名脑补改动内容等你看 PR 才发现它描述的功能跟代码对不上。强制它先看 diff再写描述准确率会大幅提升。4.3 专家模块三数据库 Schema 翻译成 TypeScript 类型第三个技能偏后端工程。我经常要拿着数据库表结构去写 TypeScript 类型定义以前都是自己手动敲字段一多就容易漏 nullable。后来我写了一个 Skill让它读取建表 SQL然后按照我预设的映射规则输出类型。SKILL.md 里的核心规则是根据输入的 CREATE TABLE 语句生成 TypeScript 类型定义。 映射规则 - VARCHAR, CHAR, TEXT - string - INT, BIGINT, SMALLINT - number - DECIMAL, FLOAT, DOUBLE - number - BOOLEAN, TINYINT(1) - boolean - DATETIME, TIMESTAMP, DATE - Date - 所有字段默认生成可选属性?除非有 NOT NULL 约束 - 枚举字段提取所有值生成字符串字面量联合类型 输出格式 export interface TableName { id: number; createdAt?: Date; }这个技能纯靠规则驱动不需要看项目上下文所以我把它放到了用户级~/.claude/skills/里。你如果也有类似的“格式转换”需求完全可以照这个思路做一个。关键是把你平时手工转换时默认遵守的规则显式写出来AI 才能真正做到和你一致。5. 怎么让 Skill 真正被“主动调用”老手才知道的优化细节5.1 调整技能目录搞清用户级和项目级优先级技能写好了不代表万事大吉真正难的是让它在恰当的时候被触发。我见过不少人把 Skill 文件放在项目目录里但当前会话是在另一个目录启动的Claude 根本扫不到。所以先确认你对目录的选择用户级~/.claude/skills/适合放通用技能项目级.claude/skills/适合放和当前仓库绑定的技能。当技能同名时项目级会覆盖用户级这个优先级规则是查文档能看到的实际用起来也确实这样。我的建议是不要在两个层级放同名技能容易把自己绕晕。5.2 触发词、负向描述与“动词优先”的写法技巧触发机制很大程度依赖 description 的匹配质量。我用一句话总结description 是给模型看的“检索标签”不是给人看的“功能简介”。所以写描述的时候把用户可能会用的说法尽量都放进去尤其是动词。下面我列一组对比同样是“生成提交信息”的描述写得太泛description: 生成 git commit 信息写得好用的description: 当用户要求生成提交信息、PR 描述、commit message、改动说明、发行说明时使用。需要先读取 git diff 再输出结构化结果。不要用于生成代码。后者明显更容易被命中。因为实际用户说话千奇百怪有人直接说“帮我把这次提交信息写了”有人说“帮我整个 PR summary”还有人会说“这个 commit 该怎么写”。描述里覆盖的动词越多技能被调用的概率越大。我还发现一个技巧可以在 description 里加一句“如果用户没有明确要求但任务本质符合上述场景也可以使用本技能”。这是我在试了很多次之后摸索出来的能让 Claude 在模糊请求下主动套用专家规范而不是走通用流程。5.3 给 Skill 挂载脚本的正确姿势Skill 的另一个杀手级能力是带脚本。你可以让 Claude 在特定步骤运行一段 Python、Bash 或 Node 脚本把脚本输出当作后续决策的基础。但脚本不是往文件夹里一扔就能用的有几个坑必须先排掉。第一路径问题。Claude 默认是在当前项目目录执行命令的不是在你的 skill 目录里。所以 SKILL.md 里写执行脚本的命令时最好写成绝对路径或者指定$(pwd)相关的相对路径。我通常会在 SKILL.md 里写一句“运行以下命令时请先 cd 到脚本所在目录”然后附上完整命令。第二可执行权限。Bash 脚本要记得chmod x不然 Claude 大概率会报 Permission denied。Python 脚本用python3显式指定解释器不要只写python因为有些环境里python指向的是 Python 2 或者压根不存在。第三输出要克制。脚本输出会被 Claude 当成上下文内容如果你让它打印一大堆日志浪费 token 不说还可能干扰模型判断。我一般在脚本末尾用print(json.dumps(result, ensure_asciiFalse))输出精简的 JSONClaude 拿到结构化数据后处理效率最高。6. 实测下来最容易踩的坑和排查方法6.1 高频问题速查表从“不触发”到“脚本崩溃”我把过去这段时间遇到的典型问题按现象和解决方案整理了一下方便你直接对照现象可能原因解决办法Skill 完全没有被触发Claude 走通用流程回答description 写得太抽象没有场景触发词在 description 里增加“当用户要求……”“适用于……”句式加入更多同义词技能文件夹存在但列表里看不到放错了目录或者文件夹命名不规范检查是否在.claude/skills/或~/.claude/skills/下目录名使用小写连字符Skill 能触发但行为不符合预期SKILL.md 正文约束不够具体给模型留了太多自由发挥空间把输出格式写成固定模板用“必须”“禁止”强约束附带脚本运行报错找不到命令脚本依赖未安装或解释器路径不对用绝对路径调用解释器确保 python3/node 在 PATH 中同一问题同时命中多个 Skill两个技能描述重叠给其中一个添加负向描述明确“不要处理某类请求”上下文被 Skills 占满对话越来越慢references 目录文件过大或技能数量过多精简 references只放按需读取的核心资料6.2 一个典型案例为什么我的 PR 技能三次都没触发说个真实的排查过程。我之前写了一个 PR description 生成器放到了~/.claude/skills/结果连着三次对话里它都没被调用。我一开始怀疑是 Claude Code 版本太老不支持新目录结构查了版本发现没问题。后来我打印当前会话能看到的技能描述才发现问题出在 description 上。我当时写的是“这是一个生成 PR 描述的工具”整句话没有出现“提交信息”“Pull Request”“改动说明”这些用户视角的触发词。而我在对话中的真实提法是“帮我总结一下这次的改动写个 PR”。语义没对上模型当然不会调它。改法很简单把 description 改成“当用户要求生成 PR 描述、Pull Request 说明、commit message、提交信息时使用”下一次对话立刻生效。这个案例让我记住了一句话写 description 时不要站在开发者角度描述“我是谁”要站在用户角度描述“用户会怎么说”。6.3 关注上下文占用与 token 消耗最后说一个很多人忽略的问题Skill 也会消耗上下文只是它消耗得比较聪明。当 Claude 判断需要某个 Skill 时它会读取完整的 SKILL.md 以及你让它引用的 references 文件这些内容都会进入上下文占用 token。如果你的 SKILL.md 写了五千字那一次触发就要吃掉不少上下文。我的经验是把 SKILL.md 当成“操作指令”而不是“知识库”。真正的长文档、公司规范、示例代码放去 references 目录需要时才让 Claude 读取。比如 SKILL.md 里写“安全审查规则见 references/security-checklist.md”Claude 只有在执行到这个步骤时才会去读那个文件。这样既保证了专业性又不至于所有内容一次性塞进上下文。另外别在同一个目录里放几十个技能。技能的描述列表本身也要被 Claude 读取放太多会让它在每次会话都花一定 token 去扫描。我建议控制在 5~8 个高频技能低频任务用的时候再临时加用完删掉保持列表干净。7. 收个尾几个扩展玩法和我个人的使用习惯写到这里Agent Skills 的核心玩法已经讲得差不多了。最后分享一个我现在的主力工作流我在用户级目录下放了一个叫team-standards的技能专门负责在接到新需求时把团队规范落地到代码里。它会先读取.claude/skills/team-standards/references/team-conventions.md然后根据当前项目类型选择对应的模板生成代码。团队里其他人如果想用同一套规范直接把技能文件夹拉下来放进自己用户目录就行。我还尝试过用 Skill 配合 MCP 一起用让 Skill 负责定义“查完数据之后怎么输出结论”让 MCP 负责真正去数据库里执行查询。两者分工明确一个管纪律一个管数据体验很顺。个人的一个体会是Agent Skills 最大的价值不是让 AI 变得更聪明而是让我们这些老开发者的“经验”第一次可以被文件化、版本化、复用化。过去我带新人要把规范一遍遍地讲现在我把规范写进 SkillClaude Code 每次都按同一套标准执行新人也看着 AI 的输出慢慢学会套路。这套东西后续还可以往团队知识库、自动生成 CHANGELOG、自动补测试用例这些方向继续扩展也就是同一套机制反复加技能包的事。你先从一两个最痛的高频场景入手跑通一次完整的“写 Skill、触发生效、看效果”循环后面的复利效应会超出你的预期。