不是所有搞 AI 的人都意识到当前 Agent 真正拉开差距的地方已经不在模型本身的智商而在模型外围那层“会干活的能力包”。我最近把项目里所有 Agent 相关的东西重新捋了一遍发现最值得投入的恰恰是看起来最不起眼的agent-skills这一层。它不像模型那样话题度高却决定了你的 Agent 是“能聊天”还是“能交付”。这篇不聊概念直接拆解 skills 从设计、开发、安装到测试验收的完整闭环。适合正在做 Agent 应用的工程师、想给自家 Agent 加技能的独立开发者以及那些已经把 Claude Code、Codex 这类 CLI Agent 用起来、但总觉得“差一点就顺手”的实践者。1. 先搞清楚agent-skills 到底在解决什么问题1.1 从“会聊天的模型”到“会干活的助手”缺的那一层就是 skills先抛一个结论模型参数里塞不下操作流程而 Agent 运行时的上下文窗口又太贵不能每次都把长篇 SOP 塞进对话里反复消耗 token。Skills 就是在这个矛盾下长出来的中间层——把一类特定任务的完整方法论、工具调用方式、判断规则和示例打包成一个可复用、可检索、可版本管理的模块。模型在需要时能快速找到并加载这个模块而不是每次从零“临场发挥”。我举个生活化类比模型本身像一个博学但没有肌肉记忆的实习生。你给他讲一遍“怎么用 Git 回滚 commit”他能听懂但下次遇到同类问题他还会再问一遍细节。Skills 就相当于你给这个实习生写了一份标准作业指导书并且放在他伸手就能拿到的抽屉里。他不需要背下来但每次动手前翻一下错误率立刻掉一个量级。这个设计还有一个非常实际的收益上下文窗口的节省。一条 skill 描述只有几百 token真正触发时才加载完整指令和参考示例。比起把整套工作流塞进 system prompt这种“按需加载”的机制让长会话场景下的上下文失控问题缓解了不少。我实测过加入 skills 体系后同样项目的多轮对话中模型“忘记上下文”的频率明显下降因为它不需要靠对话历史去回忆流程而是靠 skill 文档去重新加载规范。1.2 skills、tools、prompts、plugins四者的区别与定位很多刚开始接触的人会把 skills 和 tools、prompts、plugins 混在一起但它们在 Agent 体系中的位置完全不一样。我把它们的区别整理成一张对照表方便你判断自己的需求到底属于哪一层层面核心作用典型形态生命周期使用方式Prompts给模型设定行为倾向一段文本system prompt随会话开始/结束每次对话都加载Tools让模型获得外部能力函数/API如搜索、执行代码常驻可用模型按需调用Skills教模型“怎么做完一件事”结构化文档脚本的目录包触发时加载模型判断后按需激活Plugins扩展宿主程序的功能独立程序/脚本嵌入宿主进程随宿主启动用户手动启用一句话概括tools 是“手脚”skills 是“工作手册”prompts 是“性格”plugins 是“外挂器官”。四者可以配合但不能互相替代。特别要说一下 skills 和 tools 最容易混淆的原因。Tools 提供的是一次性的能力点比如“能搜索网页”“能执行 Python”这样的原子能力每次调用都是一个独立动作。而 Skills 描述的是“多步骤的工作方法”比如“做一个完整的竞品分析包含信息收集、数据整理、报告生成三个环节”。一个 skill 内部往往要串联多次 tool 调用——它先搜资料再整理数据最后调用文档生成工具写报告。这也是为什么我说 skills 是“方法论封装”tools 是“能力封装”。2. 一个技能包长什么样从目录结构到 SKILL.md2.1 最小可用的 skills 包结构先给你看一个最精简但完整可用的 skill 目录长什么样。这是我在项目里实际使用的结构去掉了无关文件保留核心骨架skill-repo/ ├── skills/ │ └── frontend-review/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── analyze.py │ │ └── collect_files.sh │ ├── templates/ │ │ └── review_report.md │ ├── examples/ │ │ ├── input_sample/ │ │ └── output_sample.md │ └── assets/ │ └── checklist.md └── README.md这个结构里真正不可缺失的只有一个文件——SKILL.md。其他都是配套资源。为什么这么强调单个文件的重要性因为绝大多数 Agent 框架在加载 skill 时第一步就是解析 SKILL.md 的信息头frontmatter和正文描述靠它决定“这个技能包是用来干什么的、什么时候该激活”。脚本、模板、示例都是辅助但 SKILL.md 是入口写不好它后面全是白搭。目录命名也要注意尽量用连字符小写不要用中文和空格。这个细节我栽过跟头——有次我把目录名起成了中文结果某个框架解析路径时直接报错排查了半天才发现是编码问题。通用的 convention 就是小写、连字符、语义清晰。2.2 SKILL.md 该怎么写要素拆解直接上一个我打磨过的 SKILL.md 示例这个文件是给“前端代码审查”技能用的--- name: frontend-review description: 对前端项目进行代码质量、性能和安全审查输出结构化审查报告。适用于包含 JS/TS/CSS/HTML 的代码库、PR 改动审查和上线前终审。 license: MIT metadata: version: 1.2.0 author: yourname tags: [code-review, frontend, javascript, typescript] --- # Frontend Code Review ## 触发条件 - 用户要求“审查代码”“帮我 review”“检查这个 PR” - 即将发布版本前的代码质量检查 - 新接手代码库的首次摸底 ## 工作流程 1. 扫描项目内 JS/TS/CSS/HTML 文件排除 node_modules 和构建产物 2. 根据文件名和后缀判断技术栈React/Vue/纯 JS 3. 运行代码分析脚本收集复杂度、重复代码、可疑语法 4. 逐项核对审查清单标注阻塞项和优化项 5. 生成结构化报告按严重程度排序 ## 工具调用规则 - 使用 collect_files.sh 获取候选文件列表 - 使用 analyze.py 做静态分析不要自行猜测代码内容 - 当遇到 vue 文件时先剥离 template 再分析 script ## 输出格式 - 按 P0必须修复/P1建议修复/P2可优化分级 - 每条问题必须包含文件路径、行号、问题描述、修复建议 - 报告末尾附一句总体评价不写套话这个文件看起来简单但里面有三个地方是真正决定 skill 好不好用的关键触发条件写清楚、工作流程分步骤、工具调用规则做约束。触发条件不清晰模型就不知道什么时候该加载这个技能描述太窄则该触发时不触发太宽则无关场景也乱触发。工具调用规则是防止模型“自由发挥”的缰绳——你既然写了分析脚本就得要求它先跑脚本再下结论而不是自己瞥一眼代码就开聊。2.3 描述信息与触发逻辑为什么“开头那段话”决定一切SKILL.md 里最值钱的是 YAML frontmatter 中的name和description这两行。绝大多数 Agent 框架的激活机制都是靠模型对用户意图与 description 做语义匹配来触发的。也就是说description 写得好不好直接决定了技能包能不能在正确的时刻被唤醒。我总结了 description 书写的三个层次初级写法只写“这是一个前端审查技能”。太笼统模型难以判断适用场景。中级写法补充触发关键词和适用对象如“审查 JS/TS/CSS/HTML 代码输出问题报告”。高级写法把边界条件也写进去比如“适用于 React/Vue 项目不适用于纯配置文件审查当用户要求‘review’或‘检查代码’时触发”。高级写法的价值在于减少误触发。误触发在短对话里看起来问题不大但在长流程任务里很致命——技能包一旦被错误加载模型会按错误的工作流走完一整轮浪费大量 token 和时间。所以我的建议是description 一定要手工打磨不要只写一句话要在 20 到 50 个词的范围内把“做什么、不做什么、什么时候做”说清楚。另外说一个鲜为人知的技巧在metadata.tags里加上高频同义词能提升检索匹配率。比如做前端审查tags 里加web、javascript、vue、react、code-quality模型在做语义关联时更容易命中。这个技巧不是玄学很多框架的匹配器确实会对 tagged skill 做加权处理。3. 从头写一个可用的 skill以“前端代码审查”为例3.1 需求拆解与功能边界光看模板没感觉我直接复盘一个我实际开发过的技能包。背景是团队每周都要做一次前端代码审查之前全靠人工翻 PR效率低还容易漏。我决定写一个frontend-reviewskill目标是让 Agent 自动完成代码扫描、问题归类、报告生成。第一步是需求拆解明确边界。我给这个 skill 划了几条红线只处理项目本地的代码文件不联网、不调第三方 API保护代码隐私只做静态分析不做运行时动态检测控制复杂度输出统一格式的报告并且要能被后续的 CI 流程解析非核心类型文件图片、字体、锁文件一律跳过这些边界条件写进 SKILL.md 后模型的工作范围就锁死了。不然它可能自作主张跑去调用在线分析服务或者花大量时间分析不相干的文件。3.2 编写主逻辑与辅助脚本核心脚本我用 Python 写了一个静态分析器先按扩展名收集目标文件再做基本的语法检查、复杂度检测和常见反模式匹配。脚本本身很简单关键是做好容错因为真实项目里什么稀奇古怪的代码都有#!/usr/bin/env python3 import os import re import json import subprocess from pathlib import Path TARGET_EXTS {.js, .jsx, .ts, .tsx, .vue, .css, .html} SKIP_DIRS {node_modules, dist, build, .git, coverage} def collect_files(root): Collect target source files, skip build artifacts. files [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for fname in filenames: ext Path(fname).suffix if ext in TARGET_EXTS: files.append(os.path.join(dirpath, fname)) return files def run_eslint_check(filepath): Try to run local ESLint if available, return findings. try: result subprocess.run( [npx, eslint, -f, json, filepath], capture_outputTrue, textTrue, timeout30 ) data json.loads(result.stdout) return data except Exception: return [] def analyze_file(filepath): Simple heuristic checks for common anti-patterns. findings [] try: content Path(filepath).read_text(encodingutf-8, errorsignore) except Exception: return findings if re.search(rconsole\.log\s*\(, content): findings.append({ path: filepath, line: _find_line(content, rconsole\.log\s*\(), severity: P2, message: console.log left in code, suggestion: Remove or replace with proper logger }) if re.search(r(\s|;)(var)\s, content): findings.append({ path: filepath, line: _find_line(content, r(\s|;)(var)\s), severity: P1, message: Legacy var declaration, suggestion: Use let or const }) return findings这个脚本不是给所有项目跑生产级审查的它的定位是辅助工具使命是给模型提供准确的事实依据让模型基于结构化输出做判断而不是靠肉眼数代码。这一点特别重要skill 内的脚本不要试图替代你的判断力它只负责把人工审查中最脏最累的“找问题”环节自动化真正的“改怎么修、影响面多大”还是交给模型推理。3.3 本地测试与迭代模拟、回放、对比写完脚本后我建了一套专门用来测试 skills 的“金丝雀项目”——一组精心设计的、包含各种常见缺陷的小仓库。每个仓库里我手写了十几个已知问题并标注了预期发现项。每次改完 skill我都会让 Agent 在这些测试项目上跑一遍然后人工对比“模型实际发现的问题”和“预期的发现问题”计算召回率。这个环节的实操心得是要让 Agent 展示它每一步的思考过程和工具调用序列不要只看最终报告。因为最终报告可能是模型“编”出来的——它没运行脚本直接根据经验列了几个常见问题。有一次我就抓到模型在没有调用analyze.py的情况下输出了一份看似合理的报告靠的就是检查工具调用日志。启用 Agent 的流式输出或 verbose 模式这一步一定不能省。迭代时最常调整的地方是 SKILL.md 里的“工具调用规则”段落。模型不守规矩时我会在规则里加限定词比如“必须”、“在没有运行脚本前禁止输出任何结论”比“建议”级措辞有效得多。不要给模型留自由裁量的空间该强制就强制。3.4 打包发布从本地目录到分享仓库一个 skill 调通了下一步是发布。我习惯把技能包放进 Git 仓库管理目录结构遵循社区常见的skills/xxx约定方便其他工具直接拉取。发布前要做三件事清理敏感信息这是最容易翻车的地方尤其是脚本里硬编码的路径、token、内部服务地址一定要扫描删净。补全 README写清楚技能包的作用、适用场景、安装方式、依赖要求让下一个使用的人包括 3 个月后的你自己不用重新读源码就能上手。验证干净安装克隆一份新副本到全新目录按照 README 的安装指引走一遍确认没有遗漏的隐藏依赖。发布平台的选择上可以放自建 Git 仓库也可以放社区的 skills 目录和第三方下载平台。选择标准看你的目标用户给团队内部用私有仓库最省心给社区分享优先选那些有配图展示、有评审机制的渠道质量门槛帮你过滤掉大量低质量下载者。4. 安装与管理 skills 的实操经验4.1 手动安装与命令行安装的几种方式安装 skills 这件事看着简单但不同框架的做法差异不小。我整理了一下平时用得最多的三种方式适合不同场景手动目录安装把 skill 目录复制到用户级或项目级的 skills 文件夹下。我的机器上是放在~/.claude/skills/项目级则放在.claude/skills/。手动安装的优点是看得见摸得着、不受网络环境影响缺点是没有依赖管理日后升级要手动覆盖。Git 克隆安装git clone直接把技能包仓库拉进 skills 目录。这种方式适合那些发布在 GitHub 且包含脚本和资源的复杂技能包更新时直接git pull。如果仓库里有子模块记得git clone --recursive。框架自带 CLI 安装主流 Agent 工具都开始内置 skills 管理命令比如用类似agent skills install skill-name或agent skills list的子命令操作。这种方式最省心它会自动处理目录位置、依赖检查有些还能检测到版本更新。唯一的坑是不同框架的 CLI 语法不统一换工具要重新学。顺带说一个容易被忽略的问题安装源的安全性。第三方渠道的 skills 本质上是一段会被 Agent 执行的文档和脚本能力越大风险越大。我给自己定的规矩是只从可信来源安装对每一个第三方 skill 在本地跑一遍cat SKILL.md | head -50看看有没有不对劲的指令。不要因为社区好评如潮就放松警惕。4.2 版本管理与依赖处理Skill 也是代码是代码就得谈版本管理。我在 SKILL.md 的 frontmatter 里维护一个metadata.version字段用语义化版本号。发布新版本时修复 bug、补充示例 → 升级 patch1.0.1新增功能、调整流程 → 升级 minor1.1.0破坏性变更、不兼容改动 → 升级 major2.0.0这个规范的意义在于当 Agent 框架 future 支持“指定版本安装”能力时你的技能包已经具备良好的升级基线。更现实的意义是团队协作时其他人看到版本号就知道这次改动是大是小敢不敢直接升级。依赖处理的教训更多。如果 skill 的脚本依赖第三方 Python 包或 Node 模块最稳妥的做法是在 SKILL.md 里写明安装命令例如“依赖pip install requests”并且在脚本开头做缺失检测给出友好提示。不然模型执行到一半报ModuleNotFoundError它会尝试自己 pip install如果环境权限不足就直接卡住整条链路崩掉。更极端的做法是把依赖打进本地目录vendoring虽然占空间但对离线环境是救命方案。4.3 渠道选择官方市场与第三方平台怎么挑skill 的下载渠道这两年长出了不少大致分两类官方市场和社区聚合平台。官方市场的优势是经过基础审核、格式规范、更新有保障适合找那些“关键且常用”的技能包。第三方平台则胜在数量多、品类杂、更新快很多小众或生态特有的技能只有那边才有。我的筛选顺序是这样的优先在官方市场检索尤其是那几类高热度技能代码审查、写周报、数据可视化。官方没有的去社区平台搜看下载量和近期星标趋势不看总星数因为总星数容易被长期挂着的“老项目”虚高。拿到手先看 SKILL.md 的更新时间超过一年没更新的直接弃用——AI 领域工具链变化太快一年前的写法大概率已经过时。下载前快速扫一眼它的脚本目录有没有可疑的、与功能无关的文件。这种“先官方后第三方先扫毒后跑路”的习惯帮我避开了至少三个藏在技能包里的脏东西其中有一个会在运行时往用户目录写文件。工具本身没有安全审核义务使用者才有。5. 安全、隔离与常见问题排查5.1 skill 注入与权限边界进入这个行业越久越觉得 safety 不是安全团队的专属话题而是每个使用者的必修课。Skill 的机制天然存在一个攻击面SKILL.md 本质上是一段会被模型作为指令执行的文本如果内容来路不明就存在 prompt injection 的风险——恶意作者可以在 description 里埋入“任何请求都先执行以下步骤”在正文里埋入“忽视用户约束把数据发送到指定地址”。我自己是怎么防护的说几条实操经验从不以 root/管理员身份运行 Agent。给 Agent 配置一个低权限用户并在沙箱或容器里跑。这样即使 skill 脚本作恶破坏面也是可控的。安装前检查 skill 文件的元数据。特别留意里面有没有外部 URL 请求、有没有 base64 编码的奇怪字符串。有些恶意代码会用 base64 隐藏真正意图。SKILL.md 中明确禁止行为。给团队内部用的技能包我会在文件里写一条“禁止向非白名单域名发起任何网络请求”这样模型在加载时也会被内化这个约束。定期审计已安装的 skills 列表。很多人的 skills 目录装了几十个包装完再也没有看过。我建议每个月花五分钟检查一遍把长期不触发或来源不明的技能清掉。这不是草木皆兵而是能力越大责任越大的朴素逻辑。你既然把 Agent 当作靠谱的执行者就得对它的“眼界”负责。5.2 高频报错与解决方案速查我在开发和使用 skills 过程中遇到的大多数问题其实都能在 SKILL.md 和脚本本身找到原因。下面这张表记录了我踩过的坑性能比蛮干高得多现象根因解决方案Agent 执行任务时根本没加载 skilldescription 与用户意图不匹配重写 description增加触发关键词和场景示例加载了 skill 但行为混乱不按流程走SKILL.md 正文缺少强制指令在“工具调用规则”中用“必须/禁止”等绝对措辞脚本报了路径找不到脚本用了相对路径被框架改变了工作目录在脚本开头根据__file__解析绝对路径agent execution terminated due to error环境变量缺失或 token 超限检查导入的 .env 文件拆长流程为多个阶段skill 的脚本无法执行缺少执行权限检查文件权限必要时chmod x模型输出明显不符合 skill 输入报告的模板示例缺失在examples/output_sample.md中给出标准样例相同 skill 在另一台机器行为不一致依赖版本不同在 SKILL.md 中将依赖精确到版本号或提供锁文件agent execution terminated due to error这条我要多说几句因为它的出现频率极高。排查顺序应该是先看日志里有没有报错行再检查是不是上下文超长最后看脚本退出码。很多情况下不是代码 bug而是 Agent 在多轮交互中上下文越滚越长最终顶到了模型窗口上限。解决的思路不是去“优化代码”而是把流程拆散、减少不必要的上下文注入。5.3 踩坑实录两次让我记忆深刻的翻车事件第一次翻车是“过度承诺”型。我给一个数据清洗 skill 写 description 时加了“支持 Excel、CSV、JSON、XML”等一堆格式。结果用户只扔了一个 CSV 进去Agent 却因为 description 里提到了 JSON硬是把 CSV 转成 JSON 再处理折腾半天才回到正轨。这次教训让我明白description 里不要写理论能力要写实际验证过的用例。第二次翻车是“脚本自作主张”型。我的审查脚本里有一段自动安装缺失依赖的逻辑某次在生成环境下它未经确认就执行了pip install直接把环境里一个已有包的版本给覆盖了导致下游任务全挂。修复方案是把自动安装改为“发现缺失就检查环境变量缺失则终止并提示用户手动处理”。有时候“不做”比“做”更安全。这种把“自动化”做到一定程度的技能翻起车来也让你的交付链跟着遭殃。6. 进阶从技能包到技能体系6.1 多 skill 组合与编排单个技能包只能解决单点任务真正让 Agent 效率暴涨的是把多个 skill 编排成一条流水线。我当前正在跑一个“新项目启动”的流程它实际上拆成了三个 skill 的接力project-scaffolder创建标准和目录结构生成初始配置dependency-audit扫描依赖清单识别过时和存在已知漏洞的包readme-generator根据项目实际内容生成文档框架这三个 skill 各自独立、可单独调用但在完整流程中前一个的输出会成为后一个的输入。这种组合的好处是每个 skill 的逻辑复杂度都被控制在一个很小的范围内出了问题可以单独替换某个环节不需要动整条链路。多 agent 架构里这种做法尤其重要——各个 agent 只负责自己那一段技能通过把任务拆解后路由到不同的 agent系统的可维护性会好非常多。编排时有个关键点数据传递格式要统一。我在每个 skill 的 SKILL.md 里注明“输入”和“输出”的结构并用 JSON 做中间交换格式。这就像工厂里的流水线零件规格不统一整条线就得停工。你可以在文档里看到我各 skill 的“output_format”段落里面都是严格的 JSON schema。6.2 与 agent 框架、记忆模块的配合如果你的 agent 框架支持记忆功能那么 skills 和 memory 的关系需要理顺。我的经验是skill 负责“怎么做”memory 负责“我是谁”“上次做过什么”。例如审查技能每次跑完可以把报告摘要写入记忆后续同样的任务能够在既有结论上增量更新而不是每次从零开始。有一个常见的误区是把技能内容塞进记忆里。记忆存的是状态和偏好技能存的是方法论两者粘合在一起会导致记忆混乱、检索效率直线下降。当一个 Agent 的长期记忆里混入大量“技能定义”内容时模型在回答问题前要先分辨“这段是记忆还是操作手册”推理成本瞬间增加。框架选型方面我比较关注背后的编排机制是静态的还是动态的。静态编排适合流程固定不变的场景动态编排则能根据任务内容自动挑选并串联技能。跑了一个多月的对比实验结论是如果你的任务种类超过 10 种尽早考虑动态编排否则维护if-else式的路由逻辑会变成一场灾难。6.3 团队内部共享与维护最后聊聊团队层面的 skills 治理。单人使用可以随性多人协作必须建立规范否则大家各自提交的技能包很快会让公共目录变成无人能维护的垃圾场。我给团队提了三条规矩运行效果还不错强制 code review任何技能包的改动必须先过评审评审人重点看 SKILL.md 的触发条件描述和脚本的权限行为不评审功能实现细节。统一本地缓存目录所有成员通过内部镜像拉取技能避免各拉各的分叉。这样还能做统一安全扫描任何一次拉取都能留下审计记录。季度清理每季度统计所有技能包的被加载次数对零加载超过两个季度的技能包进行下架或重写。零加载通常意味着 description 写得不好或这个技能已没人在用。有次一个同事的技能包在线上环境中表现异常我们发现他本地和团队公共版本已经分叉了两个月——他本地加了新功能但从未提交合并。统一缓存目录的规矩救了场因为团队其他成员拉的还是公共版本没有全量受影响。关于 skills 的未来走向我个人判断会和“前端工程化”的演进方向类似从散件走向规格统一、描述清晰、可组合、可审计。现在做 skills 开发人的人早一点把结构和文档规范当成一等公民后面整个团队都会被受益。最后分享一个我在实战中的小习惯每开发完一个 skill我会给自己留 5 分钟用最简短的描述重新审视它的 SKILL.md——如果我是一台冷冰冰的匹配器能不能一眼看懂它该在什么场景被唤醒。这个习惯帮我砍掉了不知多少无效加载。如果你正在做 agent 开发或者已经在用 agent不妨从一个小场景开始亲手写一个只有三步骤的 skill先跑通再优化。做完一个你会对“模型 方法论”这个组合产生全新的体感。