1. 从装完就吃灰说起agent-skills 到底解决了什么问题如果你最近半年在折腾 AI coding agents大概率经历过这个循环兴冲冲装好 Claude Code配好 API打开终端然后……不知道让它干什么。问它写个快排它写得挺好但你本地项目里那些真正烦人的活儿——批量改配置、按规范生成组件、跑一遍检查再提交——它一样没帮你干。问题不在模型在于你从来没告诉过它在这个项目里活儿该怎么干。agent-skills就是冲着这个痛点来的。它是一套给 AI coding agents 用的技能包规范与配套 CLI核心思路非常朴素把你希望 agent 怎么干活从你脑子里、从聊天记录里沉淀成项目里可版本化、可复用、可分享的文件。装完之后你的 Claude Code、以及任何支持 skills 协议的 agent都能自动识别这些技能在合适的时机调用它们而不是每次都要你重新解释一遍。我把它理解成给 agent 写的岗位说明书 操作手册。以前你招个新人得口头带他两周现在你把 SOP 写进skills/目录agent 一进项目就自动读到了。这个类比我觉得挺准的——skills 不是提示词模板那么简单它包含触发条件、执行步骤、可用工具、注意事项是一份结构化的作业指导书。适合谁看三类人最该关注。第一类是已经在用 Claude Code 或类似 agent、但只停留在问答阶段的开发者你会发现自己浪费了大量重复沟通成本。第二类是团队里负责工程规范的人skills 是把团队约定固化下来的绝佳载体。第三类是想做 agent 工具链的开发者skills CLI 的设计思路值得研究。至于完全没接触过 AI coding agent 的朋友建议先跑通基础流程再回来看不然容易一头雾水。下面我会从设计思路、核心机制、实操落地、踩坑排查四个层面把 agent-skills 这套东西拆开讲透。所有命令和目录结构我都会给到可直接抄的程度参数选择也会说明为什么这么定。2. agent-skills 的整体设计与核心机制拆解2.1 为什么是技能文件而不是更长的提示词很多人第一反应是我直接把要求写进CLAUDE.md或者系统提示词不就行了为什么要搞一套 skills我一开始也这么想实际用下来发现两者定位完全不同。系统提示词和CLAUDE.md是常驻上下文每次对话都会加载写多了会挤占宝贵的上下文窗口而且它是全局生效的——你写一条生成组件要用函数式写法那不管当前在改后端还是写脚本这条规则都挂在那儿属于噪音。skills 则是按需加载agent 判断当前任务匹配某个 skill 的触发条件时才把这个技能的内容读进来。这就像公司里贴在墙上的员工守则常驻和抽屉里的专项操作手册按需取用的区别。另一个关键差异是可组合性。提示词是一坨文本skills 是带元数据的结构化单元。每个 skill 有自己的名字、描述、触发场景、依赖工具agent 可以精确地挑一个来用而不是在一大段文字里自己找重点。这对复杂项目特别重要——一个前端项目可能有生成 React 组件写单元测试更新 changelog三个技能它们互不干扰各自独立演进。提示不要把 skills 当成提示词的替代品两者是互补关系。全局的编码风格、项目背景放CLAUDE.md具体任务的执行流程放 skills。2.2 skills 的目录结构与元数据设计一个标准的 skill 在文件系统里长这样这是我在多个项目里验证过的最小可用结构your-project/ ├── .claude/ │ └── skills/ │ ├── gen-component/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── component.tsx.tpl │ └── run-checks/ │ └── SKILL.md ├── CLAUDE.md └── src/核心是每个技能目录下的SKILL.md。它的开头是一段 YAML frontmatter用来声明元数据后面是 Markdown 正文写具体执行逻辑。一个真实可用的例子--- name: gen-component description: 按项目规范生成 React 函数式组件包含类型定义、样式文件和测试骨架。当用户要求新建组件生成组件时使用。 allowed-tools: Read, Write, Bash --- # 生成 React 组件 ## 触发条件 用户提到新建/生成/创建组件且指定了组件名。 ## 执行步骤 1. 读取 src/components/ 下最近修改的 2 个组件学习当前写法风格。 2. 在 src/components/Name/ 下创建三个文件 - index.tsx函数式组件props 用 interface 定义 - styles.module.cssCSS Modules - index.test.tsx至少一个渲染测试 3. 组件名使用 PascalCase文件名与目录名一致。 4. 完成后运行 pnpm lint 校验。 ## 注意事项 - 不要引入新的第三方依赖除非用户明确要求。 - 样式优先用 CSS Modules禁止内联 style。这里有几个设计决策值得说清楚。description字段是触发匹配的关键agent 主要靠它判断当前任务该不该用这个技能所以要把用户可能说的原话新建组件生成组件都写进去而不是写成用于组件生成功能这种抽象描述。allowed-tools是权限边界声明这个技能最多能用哪些工具避免一个生成组件的技能偷偷去删文件。正文里的步骤要写成可执行的动作序列而不是应该注意代码质量这种没法落地的空话。2.3 skills CLI 的角色与工作流skills CLI 是配套的命令行工具负责技能的安装、分发和校验。它的价值在于让技能可以像 npm 包一样被分享——你写好一套团队规范技能同事一条命令就能装到本地。常见的工作流是这样的# 从仓库安装技能到当前项目 skills install github:your-org/frontend-skills # 列出当前项目已安装的技能 skills list # 校验技能文件格式是否合法 skills validate # 把本地技能发布出去 skills publish我实测下来skills validate这个命令最容易被忽略但最有用。它会在你写错 frontmatter 字段、description 缺失、目录结构不对时直接报错省得你装进 agent 之后发现技能死活不触发然后花半小时排查。养成写完就 validate 的习惯能省很多事。注意不同 agent 对 skills 目录的默认扫描路径可能不同。Claude Code 默认读.claude/skills/如果你用的是别的 agent先确认它认哪个路径别写完发现根本没被加载。2.4 与 slash commands 的关系和边界热词里出现了 slash commands这里必须澄清一下因为很多人会把两者搞混。slash commands斜杠命令是用户主动触发的你敲/gen-component Button它才执行。skills 是agent 自主判断的你说帮我加个按钮组件agent 自己决定调用 gen-component 技能。实际项目里两者经常配合把高频、需要精确控制的操作用 slash command 暴露给用户把需要 agent 智能判断的流程做成 skill。比如发布版本这种一步都不能错的操作用/release命令而根据改动生成 changelog这种需要理解代码的活儿交给 skill。理解这个边界你的技能体系才不会乱。3. 核心细节解析与实操要点3.1 写好 description决定技能能否被触发的关键我踩过最大的坑就在 description 上。第一版我写的是用于生成符合项目规范的组件结果 agent 十次有八次不触发我手动喊它才用。后来改成把用户真实会说的话塞进去触发率立刻上来了。判断标准很简单把 description 当成用户在什么情况下会需要这个技能的答案来写。好的 description 包含三要素——做什么、什么时候用、关键词覆盖。对比一下写法示例触发效果抽象功能描述用于组件生成差agent 难以匹配场景化描述当用户要求新建、生成、创建 React 组件时使用好覆盖多种说法带关键词堆叠新建组件/生成组件/创建组件/加个组件时使用最好但别过度堆砌我的经验是控制在 2-3 句话把最常用的 3-5 种用户说法列进去就够了。堆太多反而会让 agent 判断时犹豫。3.2 步骤拆解把专家直觉翻译成可执行动作写技能正文最难的是把你自己做这件事时的隐性判断显性化。比如你生成组件时会下意识看一眼现有代码风格这个动作如果不写出来agent 就不会做生成的东西风格跟项目格格不入。我的方法是边做边录真的手动做一遍这个任务把每一步操作和判断都记下来然后整理成步骤。以生成组件为例我录下来的原始记录是这样的先看 components 目录找最近的组件参考确认命名规范发现是 PascalCase建目录、建三个文件类型定义用 interface 不用 type项目约定跑 lint整理成技能步骤后就变成了前面 2.2 节那个样子。关键是每一步都要是 agent 能执行的动作参考现有风格要具体到读取最近修改的 2 个组件否则 agent 不知道读几个、读哪些。3.3 allowed-tools 的权限设计原则allowed-tools是安全边界设计原则是最小必要。一个只读分析类技能就只给Read, Grep, Glob一个生成文件的技能给Read, Write只有确实需要跑命令的才给Bash。我见过有人图省事所有技能都写allowed-tools: Read, Write, Bash, Edit这等于没设边界。一旦某个技能逻辑写歪了agent 可能执行破坏性命令。特别是团队共享的技能权限收紧是对所有人的保护。提示如果某个技能确实需要 Bash尽量在正文里把允许执行的命令范围写清楚比如只允许运行 pnpm lint 和 pnpm test给 agent 一个明确的约束。3.4 技能粒度多大算合适粒度太粗一个技能干十件事agent 判断时容易误触发粒度太细一个技能只干一件小事维护成本高还容易互相干扰。我的经验法则是一个技能对应一个用户能一句话说清的任务。生成组件是一个合适粒度。生成组件并写测试并更新文档并提交就太粗了应该拆成三个技能让 agent 按需组合。给组件加一行注释又太细不值得单独建技能。判断方法如果你没法用一句话向同事描述这个技能是干嘛的那它粒度就不对。4. 实操过程与核心环节实现4.1 环境准备与目录初始化先把基础环境跑通。假设你已经在用 Claude Code第一步是确认 skills 目录位置。在项目根目录执行mkdir -p .claude/skills然后创建第一个技能。我建议从最简单的开始别一上来就搞复杂的。先做一个项目结构速查技能让 agent 快速了解项目布局mkdir -p .claude/skills/project-overview创建.claude/skills/project-overview/SKILL.md--- name: project-overview description: 当用户询问项目结构、目录用途、某个文件在哪、项目怎么组织时使用。 allowed-tools: Read, Glob, Grep --- # 项目结构速查 ## 执行步骤 1. 读取根目录的 package.json 和 README.md。 2. 用 Glob 列出 src/ 下两层目录结构。 3. 总结技术栈、主要目录职责、入口文件位置。 4. 如果用户问的是具体文件用 Grep 定位后给出路径。 ## 输出格式 用简洁的列表说明不要贴大段代码。写完跑一下校验skills validate如果 CLI 没装先按官方文档装好。校验通过后重启 Claude Code 会话技能是启动时扫描的然后问它这个项目结构是怎样的看它是否自动调用了这个技能。这一步验证通过说明你的 skills 机制跑通了。4.2 从零写一个提交前检查技能这是我觉得最实用的技能之一。每次提交前手动跑 lint、test、类型检查很烦交给 agent 自动做。创建.claude/skills/pre-commit-check/SKILL.md--- name: pre-commit-check description: 当用户要求提交代码、检查代码、准备 commit、跑测试时使用。 allowed-tools: Read, Bash, Grep --- # 提交前检查 ## 执行步骤 1. 运行 git status 和 git diff --stat了解改动范围。 2. 按顺序执行以下检查任一失败就停止并报告 - pnpm lint - pnpm typecheck - pnpm test --run 3. 全部通过后总结改动文件数量和检查结果。 4. 如果用户要求生成 commit message按 Conventional Commits 规范生成。 ## 注意事项 - 不要自动执行 git commit只做检查和建议。 - 如果某个命令不存在跳过并说明不要报错中断。 - 测试失败时把失败用例的完整输出贴出来。这里有个关键设计不自动提交。我试过让 agent 自动 commit结果它把一堆临时文件也提交了。检查和建议可以自动化最终提交动作留给人工确认这是安全底线。4.3 参数与触发条件的调优过程技能写完后触发准确率需要调优。我的做法是准备一组测试语句反复验证。比如针对 pre-commit-check我准备了这些帮我提交一下 → 应该触发跑下测试 → 应该触发检查代码 → 应该触发这个函数怎么写 → 不应该触发实测发现检查代码这个说法有时会被理解成代码审查而不是提交前检查于是我在 description 里补了提交前这个限定词误触发就少了。这个调优过程没有捷径就是多试、多改 description。注意调优时改的是 description不是正文。正文是执行逻辑description 才是触发匹配的依据别改错地方。4.4 团队共享与版本管理技能写好后放进 git 仓库团队共享。我的目录组织方式是把技能和项目代码放同一个仓库.claude/skills/跟着项目走这样每个人 checkout 下来就自动有了。如果技能要跨项目复用就单独建一个 skills 仓库用 CLI 安装skills install github:your-org/shared-skills版本管理上技能文件也要走 code review。我见过有人随手改技能导致整个团队的 agent 行为异常所以技能变更应该像代码一样被审查。特别是allowed-tools的变更扩大权限的改动必须有人把关。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序我整理成了一张表现象可能原因排查方法完全不触发目录路径不对确认 agent 扫描的是.claude/skills/完全不触发frontmatter 格式错误跑skills validate偶尔触发description 不够具体补充用户常用说法触发但用错技能多个技能 description 重叠给每个技能加区分性关键词改了没生效会话未重启重启 agent 会话我遇到最多的是最后一条。技能是会话启动时加载的你改了文件不重启agent 用的还是旧版本。这个坑我踩过不止一次改完技能记得重启。5.2 技能执行到一半失败常见于 Bash 命令失败或文件路径不对。排查思路是先看 agent 报的错再手动复现那条命令。如果手动跑没问题那多半是 agent 执行时的工作目录不对或者命令里的路径是相对的、依赖了错误的 cwd。解决方法是在技能正文里把路径写绝对或者明确说明在项目根目录执行。我现在的习惯是凡是涉及文件路径的步骤都写清楚相对于哪里。5.3 技能之间互相干扰当技能多了之后可能出现 A 技能被 B 技能抢触发的情况。根因是 description 语义重叠。解决办法是给每个技能加一个独占关键词。比如生成组件和生成页面两个技能前者加组件/component后者加页面/page让 agent 有明确的区分依据。如果实在分不开考虑合并成一个技能在正文里用条件分支处理两种情况。粒度不是越细越好能清晰区分才是好粒度。5.4 权限相关的报错如果技能里用了allowed-tools没声明的工具agent 会拒绝执行。报错信息通常会说某个工具不可用。这时候检查两处frontmatter 里有没有声明这个工具工具名拼写对不对大小写敏感是Read不是read。我建议一开始把可能用到的工具都列上跑通之后再逐步收紧到最小集合。先能用再安全这个顺序比较符合实际。5.5 独家避坑清单最后分享几条文档里不会写、但实际很要命的经验技能正文别写太长。超过 200 行的技能agent 执行时容易漏步骤。长流程拆成多个技能串联。别在技能里写死具体业务值。比如别写组件名用 Button要写组件名用 PascalCase否则技能没法复用。技能要能独立测试。写完先手动模拟一遍 agent 的执行路径确认每步都能落地再交给 agent。给技能加个失败时怎么办。比如检查失败时是停止还是继续写清楚否则 agent 会自己瞎猜。定期清理不用的技能。技能越多agent 判断成本越高误触发概率越大。季度清一次。这套东西我用了几个月最大的感受是agent 的能力上限取决于你给它多少结构化的上下文。skills 就是把这个上下文工程化的手段。刚开始写会觉得麻烦但一旦积累起来你会发现 agent 从什么都要问变成了自己就知道该干嘛这个转变带来的效率提升是实打实的。