Agent Skills 实战：用 Claude Code 打造可复用 AI 技能包

Agent Skills 是近两年 Agent 类开发工具里讨论热度上升最快的概念之一。很多人第一次接触它是在 Claude Code、Cursor 这类 AI 编程工具的配置界面里或者在某个标题写着“从会用到会造”的入门教程里。但真正常看下来会发现Skill 并不是一个神秘的高级功能它本质上是一套把“可复用的工作流程、判断标准和配套资源”打包成标准文件夹的机制让 AI 在合适的场景下自动读取并执行。这篇文章不按视频节奏讲而是按工程落地的方式拆解先弄清 Agent Skills 到底是什么再准备好运行环境接着从“用”到“造”完成一个能直接工作的技能最后给出排错链路和团队落地建议。1. Agent Skills 是什么先去掉神秘感再看清技术边界1.1 一句话理解 Agent Skills以及它解决什么问题在没有 Skill 之前你让 AI 干活时每次都要重新描述一遍流程和标准。比如让 AI 写提交信息你得说“结合 diff 总结改动、按类型前缀、不要超过 80 字、不要提文件数量”等等。这些约定每次都打一遍很累而且不同人打的版本不一致AI 的表现就飘忽不定。Agent Skills 解决的问题就是把这些约定固化下来。一个 Skill 是一个包含SKILL.md主体文件和可选资源文件脚本、模板、参考文档的目录。AI 运行时会根据描述判断“当前任务是否需要这个技能”需要时就读取这套步骤按固定流程执行。你可以把它理解成给 AI 写的一本岗位操作手册什么情况用、分几步做、做到什么标准、哪些事不能做。1.2 Skill 的标准载体SKILL.md 和技能目录一个最常见、也最标准的 Skill 目录是这样的~/.claude/skills/code-review/ ├── SKILL.md ├── templates/ │ └── review-template.md └── scripts/ └── parse_diff.py核心文件是SKILL.md。它的头部是 YAML frontmatter里面至少要包含name和description。name是这个技能的唯一标识description则决定了 AI 什么时候调用它。下面的正文部分是 Markdown用来写这个技能的完整操作手册。SKILL.md旁边的资源文件不是装饰。脚本可以帮你预处理数据模板可以统一输出格式参考资料可以补充领域知识。Skill 和普通提示词模板最大的区别就在这里它不是一个“提示词文本”而是一套可携带脚本和资源的完整能力包。1.3 Agent Skills 与 Agent 的核心区别“AI skills 和 agent 的区别”是很多人刚接触这个概念时最容易混淆的地方。二者是不同层次的东西对比维度Agent智能体Agent Skills技能定位一个能自主规划并执行多步任务的执行者一份可复用的操作手册和资源包形态程序、会话、工具链的调度者目录 SKILL.md 可选脚本执行方式自己决定先做什么、后做什么被 Agent 按需读取按固定步骤执行创建成本高涉及工具、记忆、循环控制低写一份 Markdown 和少量脚本即可复用对象一个任务实例所有同类任务典型用途独立完成一次“从需求到交付”的工程让每次代码评审、日志排查、报告生成都保持一致在 Claude Code 这类工具里Agent 是主体Skill 是它的“工具箱”。Agent 判断当前任务需要某个技能就加载对应SKILL.md并执行。所以学习顺序也应该反过来先会用一个 Skill再理解 Agent 怎么调度它最后才谈自己造 Skill。2. 环境准备把 Claude Code 装好Skills 才有运行载体2.1 环境要求清单要实践 Agent Skills需要一个能运行 Claude Code 的环境。这里给出一份在学习和开发阶段通用的检查清单项目要求检查命令Node.js一般要求 18 及以上版本具体以官方说明为准node -vnpm随 Node.js 安装用于全局安装 Claude Codenpm -v终端Windows PowerShell / macOS Terminal / Linux Shell直接打开终端即可网络能正常访问 Claude 官方服务连接稳定安装后执行claude观察是否提示登录登录认证拥有可用的 Claude 账号并能完成官方认证流程首次运行claude时按提示操作IDE 插件可选VS Code 中可安装 Claude Code 扩展便于在编辑器内使用VS Code 扩展市场搜索 Claude Code如果原始材料没有给出明确版本落地前要先确认依赖版本。不同版本的 Claude Code 在命令和功能上会有差异建议先执行claude --version确认当前版本再对照该版本文档操作。2.2 安装 Claude Code 并完成首次登录Claude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后先验证命令是否可用claude --version能输出版本号说明安装成功。接下来在项目目录下直接执行claude首次运行会进入登录认证流程一般是在终端里打开一个授权链接登录你的 Claude 账号并授权。认证通过后就能进入交互式会话界面。如果你使用 VS Code也可以在扩展市场安装 Claude Code 扩展。安装后编辑器内会出现对应的面板可以在不离开编辑器的前提下启动会话。需要注意扩展只是入口接入方式不同底层的账号认证和 Skill 加载机制与终端版一致。2.3 Windows 下“claude 无法识别”的修复很多人在安装后遇到这类报错claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。或者claude 不是内部或外部命令也不是可运行的程序或批处理文件。这个现象的本质是系统在 PATH 环境变量里没有找到claude可执行文件。常见原因和检查顺序如下Node.js 没有安装或者安装后没有重开终端。npm 全局安装目录不在 PATH 中。安装过程被中断命令文件没有生成。先用node -v确认 Node.js 可用。然后执行npm config get prefix拿到 npm 全局安装目录后把它加到用户环境变量的 PATH 中保存后重新打开终端再执行claude --version。如果依然不行重新执行一次npm install -g anthropic-ai/claude-code观察是否出现了 npm 错误。注意修改 PATH 后必须重开终端窗口旧窗口的环境变量不会自动刷新。2.4 登录、订阅、组织策略和模型配置问题登录阶段还会遇到几类高频问题这里单独说明。第一类是账号或订阅限制。如果看到your organization has disabled claude subscription access for claude code说明当前组织策略关闭了 Claude Code 的订阅访问需要联系组织管理员在后台开启而不是自己试图绕过。第二类是区域可用性提示。比如Claude is not available to new users right now这通常是官方在当前地区或当前时间段暂停了新增用户访问。遇到这类提示请以官方渠道的信息为准不要尝试任何非官方方式耐心等待或改用官方支持的地区和服务。第三类是模型配置错误。如果你在配置中手动指定了模型标识而当前版本的 Claude Code 不认识它会看到类似这样的报错some-model-id is not a model this version of claude code recognizes这类问题通常是模型 ID 写错或者 Claude Code 版本过旧。处理方式是先执行claude --version确认版本再检查配置文件里的模型字段。示例配置如下{ model: some-model-id }如果确认配置不存在于当前版本支持的模型列表中删除或更正模型字段或者升级 Claude Code 后再试。这里不建议为了兼容旧版去强制锁定某个不存在的模型 ID。2.5 网络中断和限流问题运行过程中常见的连接类报错是connection dropped (econnreset) · retrying in 3s · attempt 4/1这表示会话连接被中断通常是网络不稳定、公司防火墙策略严格或服务端临时断连导致的。处理方式是先确认当前网络能否正常访问 Claude 官方服务然后重试。如果是在公司网络环境可以先换一个稳定的网络环境排查如果是家庭网络检查路由器和网络波动。另一类是限流错误最典型的是529。这表示服务端负载较高暂时无法处理请求。看到 529 不要反复高频重试建议等待一段时间降低请求频率后再继续。区分方法是ECONNRESET 是连接层问题529 是服务端繁忙问题排查方向不同。3. 先会“用”Skill 从哪里加载又是怎样被调用的3.1 三种技能存放位置以及优先级关系在 Claude Code 中自定义 Skill 可以放在三个不同位置位置示例路径作用范围适用场景个人全局~/.claude/skills/skill-name/SKILL.md所有项目可用个人常用技能项目级project/.claude/skills/skill-name/SKILL.md当前项目目录内可用随项目通过 Git 共享插件目录.claude-plugin/skills/...跟随插件分发团队级、跨项目分发Skill 的名字建议统一使用小写字母和连字符例如code-review、commit-message不要用空格或中文目录名。路径写错、大小写不一致是技能加载失败最常见的原因之一。3.2SKILL.md的 frontmatter 是“什么时候触发”的关键一个 Skill 能否被正确调用description几乎决定了一大半。它的作用不是给人看的说明书而是给 AI 的“触发条件”。描述越模糊AI 越难判断什么时候该用这个技能。来看一个反面例子--- name: log-analyzer description: 分析日志。 ---这种描述等于没写。AI 不知道这个技能处理什么格式的日志、输出什么结果、在什么任务下调用。合理的description应该包含三个信息做什么、什么时候用、输出什么。示例--- name: log-analyzer description: 分析后端服务错误日志。当用户要求排查日志、查找报错原因、统计错误类型时使用。先归类错误关键字再按出现次数排序最后输出问题摘要和排查建议。 ---正文部分则写具体步骤。一个原则是frontmatter 负责“触发”正文负责“执行”。3.3 用一次实际会话体验 Skill 触发安装好环境、放好 Skill 后怎么确认它真的会被调用推荐用下面的流程在一个测试项目里启动claude。提出一个明确命中了技能描述的任务比如“请评审一下当前分支的代码变更”。观察 Claude 的行为它是否读取了SKILL.md是否按技能里的步骤和输出格式执行。如果版本支持可以在会话中输入/查看当前支持的斜杠命令部分版本会展示与技能相关的入口具体以你安装版本的帮助信息为准。判断的标准不是“它提到了技能名字”而是“它的执行流程是否符合SKILL.md里的步骤”。如果 Claude 没有读取技能直接自由发挥说明触发判断出了问题需要回到排查环节。3.4 初次使用容易误会的三个点第一Skill 不等于普通提示词模板。提示词模板只是文本Skill 是带目录、脚本、资源文件的完整包。第二Skill 不等于 MCP。MCP 解决的是“让 AI 连接外部工具和数据”的问题Skill 解决的是“让 AI 按固定流程处理一类任务”的问题。二者可以配合但不能互相替代。第三Skill 不是 Agent。Agent 是执行者Skill 是执行者手里的操作手册二者是不同层级的对象。4. 再学“造”从需求拆解到一个可运行的 Skill4.1 动手前先拆解四件事要自己造一个 Skill不需要先学复杂的框架。先想清楚四件事name这个技能叫什么最好一眼能看出用途。description它什么时候被调用输入是什么输出是什么。steps它按什么顺序执行每一步做到什么标准。resources它需要哪些脚本、模板、参考资料。设计原则是“一个技能只干一类事”。不要把代码评审、日志排查、文档生成塞进同一个 Skill。技能越小触发越准越容易被复用。4.2 完整示例手写一个结构化代码评审 Skill下面创建一个code-reviewSkill目标是让代码评审输出稳定、可执行而不是空泛评价。先创建目录mkdir -p ~/.claude/skills/code-review然后创建SKILL.md--- name: code-review description: 对代码变更执行结构化评审。当用户要求“评审代码”“review 一下这个分支”“看看这个改动有没有问题”或者给出 MR/PR、diff、变更文件列表时使用。输出按 P0/P1/P2 分级的评审表和具体修改建议。 --- # Code Review ## 目标 把代码评审变成固定流程避免遗漏和空泛评价。 ## 步骤 1. 确认变更范围。没有明确 diff 时先执行 git status 和 git diff 获取。 2. 按固定顺序检查 - 可读性与命名 - 正确性与边界条件 - 异常处理 - 安全和敏感信息 - 性能与资源占用 3. 每个问题标记 P0 / P1 / P2 - P0会导致崩溃、数据错误或安全漏洞必须修复。 - P1明显缺陷建议修复。 - P2优化建议可延后。 4. 每个问题给出定位、原因、修改建议尽量附代码片段。 5. 如果没有发现问题明确写“未发现 P0/P1 问题”不要写空话。 ## 约束 - 只输出评审意见不直接修改源代码。 - 不确定的行为标注“需确认”不要替作者假设。 - 如果变更涉及数据库迁移或密钥优先检查回滚与泄漏风险。 ## 输出格式 先输出一张汇总表文件 / 问题等级 / 问题摘要 / 建议。之后按问题等级从高到低展开。这个例子里description写清了触发场景和输出承诺正文写清了步骤、等级定义、约束和输出格式。它的核心价值是稳定不管谁调用这个技能评审结果都会按同一套标准产出。4.3 给 Skill 添加脚本和模板让它处理更复杂的输入纯 Markdown 能解决的只是流程问题。如果技能需要处理文件就得配脚本。这里给code-review加一个获取变更文件列表的脚本#!/usr/bin/env python3 # scripts/parse_diff.py import subprocess result subprocess.run( [git, diff, --name-only], capture_outputTrue, textTrue, ) for path in result.stdout.splitlines(): print(path)然后在SKILL.md中追加一个“参考”小节告诉 Claude 如何调用它## 参考 - 获取变更文件列表python scripts/parse_diff.py在技能目录内脚本、模板和SKILL.md同属一个包Claude 会读取这些资源。这样设计的好处是技能可以在不同项目中复用只要该项目是 Git 仓库。脚本写错或者依赖缺失时Claude 也能根据报错信息反馈问题。4.4 让 Claude Code 帮你生成 Skill再人工检查自己写SKILL.md还不熟悉时可以直接让 Claude 生成。在会话中输入这样一段话请帮我在 ~/.claude/skills 下创建一个名为 commit-message 的 Skill。 它要根据 git diff 生成符合团队规范的 Git 提交信息。 SKILL.md 要包含 name、description 和完整步骤。Claude 会创建 Skill 目录并写入文件。生成之后要做两件事打开SKILL.md检查description是否写清了触发场景再实际运行一次确认能按预期输出。AI 生成的内容只是初稿是否可用以人工验证结果为准。注意不要把自动生成的 Skill 直接交给团队使用至少要在两个不同项目里各验证一次。5. 验证、排错和常见坑Skill 不生效时按这条链路查5.1 如何确认一个 Skill 已经被正确加载当你要判断 Skill 是否被加载可以从这些现象入手文件路径是否正确、文件名是否严格为SKILL.md。name是否唯一是否与其他技能冲突。frontmatter 中的 YAML 是否合法比如少了---结束符。会话是否重启。Claude Code 在会话中可能缓存技能信息修改文件后最好重启会话。手动触发描述中的示例任务观察 Claude 是否按技能步骤执行。一个最直接的检查命令ls -la ~/.claude/skills/code-review cat ~/.claude/skills/code-review/SKILL.md确认文件存在且内容正确后再进入运行验证。5.2 常见问题对照表问题现象常见原因检查方式处理建议Skill 从未被触发description太宽泛AI 判断不准查看 frontmatter 中的描述重写描述写明场景、输入和输出读取到的是旧内容会话缓存未刷新检查文件保存时间重启会话重新打开 Claude Code 再试技能执行一半卡住脚本依赖不存在或路径错误在终端手动运行脚本在SKILL.md里写清依赖和运行命令总是被错误地触发描述没有写清边界检查描述是否有排除场景增加“不要用于……”的说明中文内容乱码文件编码不是 UTF-8用编辑器查看编码统一保存为 UTF-8 无 BOM模型相关报错模型 ID 不受当前版本支持执行claude --version查看版本更新版本或更正模型配置5.3 排查顺序从输入到日志遇到 Skill 不生效不要先怀疑是工具坏了。按下面的顺序排查先确认输入任务是否真的命中了描述里的场景。再检查技能目录路径、文件夹名、SKILL.md文件名大小写。检查 frontmatter 的 YAML 是否合法name和description是否存在。检查description是否写清了触发词和边界。检查技能依赖的脚本、模板是否齐全能否在终端手动运行。确认当前版本是否支持该功能必要时升级 Claude Code。最后再看日志和网络是否出现 ECONNRESET、529 等连接类错误。这七步基本能覆盖 90% 的问题。最容易被忽略的是第 1 步很多人没意识到自己的任务描述和技能的触发场景根本不匹配。5.4 制作 Skill 的四个高频坑坑一把SKILL.md当成普通提示词写没有结构。结果就是步骤散乱Claude 无法稳定执行。正确做法是参照“目标、步骤、约束、输出格式”分层组织。坑二description写得太短。比如只写“用于日志分析”AI 永远找不到触发它的时机。应该写清楚“当用户要求排查日志、看到错误堆栈、统计异常类型时使用”。坑三技能过重。一个技能里塞了几十个步骤、七八个脚本出问题后很难定位。应该保持技能小而专一个技能解决一类任务。坑四忽略权限和安全。技能如果包含删除文件、执行数据库操作等高风险命令必须写明约束和确认环节避免 AI 在无人确认的情况下执行破坏性操作。6. 从会用到会造的进阶练习与工程落地建议6.1 一周练习路径按天拆解把“从会用到会造”落成可执行计划可以参考下面的练习顺序天数练习内容完成标准第 1 天安装 Claude Code完成登录跑通一次会话能进入交互界面并完成一次问答第 2 天使用现成技能处理文档、生成提交信息、解析日志能说出触发场景和输出结果第 3 天手写一个 20 行内的简单SKILL.md技能能在一个任务中被触发第 4 天为技能添加脚本和模板处理真实输入脚本能配合技能完成预处理第 5 天把技能放进项目 Git 仓库写清文档其他成员能拉取并直接使用第 6 天统计技能触发率和输出质量调整描述描述更精准误触发减少第 7 天制定团队命名和评审规范每个新技能都有人评审和记录6.2 团队化落地把 Skills 当成代码来管Skill 不是个人玩具团队使用时要把它当成代码一样管理。推荐做法所有项目级 Skill 放入.claude/skills/目录随 Git 仓库提交。每次新技能或修改技能都走 Pull Request由至少一名同事评审。统一命名规范例如模块-动作避免命名混乱。版本记录写在SKILL.md底部变更后更新说明。PR 描述中写明这个技能的触发场景、输出格式和依赖脚本。这样做的收益是团队的经验被沉淀成文件而不是存在每个人脑子里。新人加入后直接读一遍.claude/skills/就能理解团队的默认工作方式。6.3 什么场景不适合使用 SkillsSkills 不是万能的。遇到以下几类任务不建议强行做成 Skill一次性临时任务只做一次没有复用价值写 Skill 反而增加维护负担。需要大量实时外部数据的任务Skill 是相对静态的操作手册如果需要频繁查询实时数据应该配合 MCP 工具而不是塞进 Skill 里。涉及敏感凭据的操作不要在 Skill 中写入密码、Token 或私钥。技能文件会进入 Git 历史泄露风险极高。高风险且需要人肉审批的流程比如生产环境的数据变更应该保留人工确认环节不要让技能自动执行。6.4 上线前检查清单无论是个人使用还是团队共享一个 Skill 发布前建议过一遍下面的检查清单检查项说明文件路径和命名目录名小写连字符SKILL.md严格匹配frontmatter 合法YAML 能正确解析name、description存在触发描述明确包含场景、输入、输出必要时写排除场景脚本可运行在干净环境下手动执行无报错输出格式可消费下游流程能直接使用输出结果无绝对路径和密钥不写死本机路径不包含敏感信息权限最小化不请求不必要的高风险操作多会话验证至少两个项目或两个会话验证通过文档完整记录版本、变更内容和运行依赖最后给你一条最实用的练习建议从你每天都重复做三次的那件小事开始。无论是写提交信息、整理日志、生成周报还是评审代码选一个 20 分钟内能写完的 Skill先让它在自己的项目里跑通再逐渐扩大使用范围。Agent Skills 的收益来自复利技能库积累得越多AI 对你的工作越了解效率提升才越明显。不要一开始就追求复杂技能先把最简单、最高频的那一个做成标准。