我最近把大量精力投在 agent 开发上尤其是 agent-skills 这个方向。说白了它解决的是一个问题AI Agent 怎么才能像老手一样在特定任务里稳定输出而不是每次都要你手把手教。你给它一套打包好的“技能”它就知道该看什么、怎么做、用哪些工具、按什么顺序产出结果。这篇文章适合正在琢磨 AI Agent 开发的人也适合每天用 Claude、Codex 这类工具辅助写代码的开发者。你可以不写一行框架代码先从一个 Skill 开始把经验沉淀成可复用的能力包效果立竿见影。我下面会从概念、原理、实操、选型、踩坑五个角度完整聊一遍所有内容都来自我最近改造一个前端代码审查 Agent 的真实经历。1. Agent Skills 到底是什么先搞清它在解决什么问题1.1 一个让我决定研究 skills 的实际场景上个月我负责一个前端项目代码量不大但审查压力很大。我最初的方案是让 Agent 直接读项目里几个核心文件然后给出一份代码审查报告。结果跑了几轮每次都让人火大第一轮它把“列表渲染缺少 key”当成严重事故第二轮又把“组件拆分过度”和“可读性偏差”混在一类问题里。我一趟趟往 prompt 里补要求补了十几条之后报告质量总算上来了但 prompt 越来越长token 消耗肉眼可见地涨换个项目复用又得重新改一遍。后来我把审查要求、常见问题清单、该看哪些文件、输出格式模板全部整理成一份“技能文件”挂到 Agent 上。同样的项目第一轮输出就基本符合预期后续迭代成本直接砍掉大半。这个对比让我一下子理解了 skills 的价值它不是给 Agent 增加知识而是把“经验”变成了一套可以即插即用的操作流。那段时间我翻遍了社区里的 agent-skills 讨论越看越觉得这事值得系统梳理一遍。1.2 用大白话定义技能包等于岗位 SOP我的理解是Agent Skills 就是把“完成某一类专业任务所需的背景信息、操作步骤、工具调用方式和输出规范”打包成一个独立单元交给 Agent 按需加载。用大白话讲它就像给新同事发的一份岗位 SOP。新同事入职你不会让他自学三个月而是给他一份文档你的职责是什么遇到什么情况怎么做按什么模板输出哪些红线不能碰哪些问题不用管。Agent 也是一样。没有技能时你只能在每次对话里重复教有技能后它自己知道要去翻哪份手册不需要你再唠叨。我见过很多团队把精力放在选模型、调参数上结果 Agent 还是不够“专业”。模型本身的能力再强不知道你的项目规范、输出要求和工作流照样给出通用但没用的结果。技能包解决的就是这个“最后一公里”问题把人的经验转译成 Agent 能稳定执行的动作序列。它通常包含三块内容一是描述信息说明什么场景触发它二是指令主体列出具体步骤和规则三是可选的手册、脚本或参考样本。这决定了它不只是普通的 prompt而是可发现、可复用、可传播的能力模板。1.3 和 Tools、Prompt、Memory 的区别我在网上翻了不少帖子发现很多人把 skills 和 tools、memory 混在一起讨论其实它们干的事完全不同。Tools 是 Agent 能调用的动作比如读文件、执行命令、请求外部接口Skills 是一整套完成任务的思路和操作规范Prompt 是一次性塞给模型的对话话术Memory 是跨会话保存的事实和状态。我做个表方便对照能力单元本质类比Tools工具可执行的动作比如搜索、读文件、跑命令工具箱里的螺丝刀Skills技能完成任务的完整方法包括什么时候用工具、怎么用、按什么顺序操作手册Prompt提示词一次性给模型的话术用完即走口头交代Memory记忆跨会话保存的事实与状态员工档案Tools 回答“能做什么”Skills 回答“怎么做才专业”。你可以给 Agent 装上再强大的工具没有好的技能它依然是新手反过来技能写得好哪怕工具很基础它也能稳定完成任务。这也是我在开发 agent-skills 项目时最强烈的感受工具是 Agent 的手脚技能才是它的大脑。2. 第一性原理为什么 Agent 圈都在谈 Skills2.1 模型的上下文窗口不是无限饭桌先从模型本身说起。大模型的上下文窗口无论多大本质上是一张尺寸有限的餐桌。你要让 Agent 专业就得把专业知识摆上桌但桌上的位置就那么多对话历史、工具返回结果、用户输入全都要占座。你把几十页规范全摆上去别的东西就放不下了任务还没开始上下文先用掉一大半。Skills 的价值在于“按需上菜”。不是所有任务都要加载全部专业规则而是识别到对应场景时再把对应的技能包摆上桌。这样既保证了专业性又不会把上下文撑爆token 成本也降下来。我实测过把大段审查规则写进对话单次任务大约多占 20% 到 50% 的上下文改成按需加载技能后平时对话里几乎不占额外空间只有真正触发审查时才把那部分内容拉进来。这个效率差异在多 Agent 并行场景下会更明显。2.2 换个角度Agent 是员工Skills 是岗位职责现在很多团队在做多 Agent 协作Agent 和 Agent 之间怎么分工说到底就是每个 Agent 的“岗位职责”不同。而岗位职责最适合用技能来表达。我把一个 Agent 看成员工它有性格模型底座、有设备Tools、有档案Memory但真正决定它干得专不专业的是 Skills。前端审查 Agent 挂“前端审查技能”后端安全 Agent 挂“安全评审技能”它们各自读各自的手册互不干扰。这种思路带来的好处是模块化。你想让一个 Agent 会两种工作就给它装两个技能想复制一个同样能力的 Agent直接把技能包复制过去就行。不需要重新训练模型也不需要把长长的 prompt 从老项目里抠出来再改一遍。这也是 agent-skills 这个方向让我最兴奋的地方它让“复制专家能力”变成一次文件拷贝操作。2.3 Harness、Skills、Tools 到底什么关系社区里有个高频词叫 harness直译是“挽具”你可以把它理解成跑 Agent 的容器和调度框架加载模型、管理工具、执行循环、处理权限都在这一层完成。Skills 是放进 harness 里的“能力包”Tools 是 harness 能调用的底层动作。打个比方harness 是流水线的控制系统tools 是焊枪、螺丝刀、机械臂skills 是每道工序的操作规程。没有操作规程机械臂再灵活也不知道拧几圈螺丝。我自己的经验是先花时间把技能做到位再考虑换更复杂的 harness。很多项目换成能力更强的框架后收益不大问题其实出在技能太弱而不是调度不够花哨。技能好一套极简的 harness 也能跑出稳定结果技能烂再华丽的编排也只是在放大错误。所以网上那些“harness 和 agent 区别”的争论我觉得只是买椟还珠真正值得聚焦的始终是技能内容本身。2.4 为什么我建议新手先学 Skills 而不是一上来就上框架我发现很多人一上来就搭多 Agent 编排、上重框架结果很快被框架复杂度劝退。我的建议是反着来先用最简单的方式把三类技能写出来——日常问答技能、代码审查技能、文档生成技能。等这几个技能真的稳定了再考虑多 Agent 协作和框架编排。原因很简单技能是 Agent 能力的地基框架是上面的建筑。地基没打稳换什么框架都白搭。而且技能本质是纯文本文件学习成本极低一个下午就能跑通第一个获得的正反馈比看十篇框架教程都强。你在搜索热词里能看到大量的 agent 开发教程、agent 学习路线但真正让我觉得值得复制的恰恰不是某套框架而是“为 Agent 沉淀技能”这套方法论。3. 从 0 到 1 手写一个 Agent Skill完整实操记录3.1 第一步选定一个足够“窄”的任务场景写技能的第一个坑就是场景选得太宽。我一开始写“帮我审查代码”听上去很全面但实际效果一塌糊涂因为“审查代码”包含了无数种情况风格审查、安全审查、性能审查、可维护性审查规则完全不一样Agent 加载技能后不知道该按哪套标准来。后来我把它拆成“React 前端组件代码审查”范围一下清晰了重点检查组件拆分、props 设计、性能优化、可访问性、样式和代码风格。范围窄规则才能写得具体Agent 才好执行。我的经验是一个技能只负责一件事任务的描述必须能在两三句话内说清楚。不要造一个“万能技能”那只会让 Agent 在所有场景里都半吊子。技能库宁可多几个小技能也不要一个大而全的“杂烩包”这是我从失败里换来的教训。3.2 第二步搭目录和主文件 SKILL.md目前比较主流的技能格式是一个文件夹里放一个 SKILL.md 主文件旁边可以放 scripts 目录存辅助脚本也可以放 references 目录存参考资料。以我在用的前端审查技能为例目录结构长这样frontend-code-review/ ├── SKILL.md ├── scripts/ │ ├── extract_components.py │ └── lint_check.sh └── references/ └── react-guidelines.mdSKILL.md 开头有一个 YAML 格式的元信息块作用是让 Agent 和技能管理器识别它--- name: frontend-code-review description: 当用户要求审查 React 前端组件代码时使用。聚焦组件设计、props、性能、可访问性和可维护性不处理后端逻辑。 ---description 一定要写清楚“什么时候触发”和“什么时候不触发”。我踩过坑之前写得模糊Agent 连写一个简单函数都要触发审查技能活没干先给你来一套审查报告反而帮倒忙。触发条件越明确技能的可用性越高。这个字段虽然只有几行但我花在它上面的时间几乎和写正文一样多。3.3 第三步正文怎么写才像“老手现场指挥”SKILL.md 的正文是整个技能的灵魂。我的写法遵循四个原则分节、给清单、给正反例、给停止条件。先说分节正文按“审查前准备 → 重点审查清单 → 输出格式”来组织Agent 顺着一节节执行不会东一榔头西一棒子。再说清单比如“组件审查”这一节我会写检查列表渲染是否缺少唯一且稳定的 key检查 state 是否被不必要地提升能用局部 state 就别引入全局状态检查是否用 useCallback/useMemo 过度包裹先分析实际依赖再决定检查组件是否有明显可拆分的子组件但避免过度拆分清单要有优先级。我以前把所有问题平等列出来Agent 会把“代码缩进不规范”和“组件存在内存泄漏隐患”放在同一个级别汇报完全没有主次感。后来我在清单里明确标注哪些是“必须阻断”的严重项哪些是“建议优化”的普通项报告质量立刻不一样。最后是正反例和停止条件。我在 references 里放一份包含正确和错误写法的对比文件让 Agent 有对照物。停止条件也很关键比如我明确写“只输出审查报告不直接修改用户代码除非用户明确要求”这能防止 Agent 越权动手改代码从源头减少安全风险。3.4 第四步用“坏样本”反复测试写完之后别急着宣布成功拿真实样本测。我的做法是准备三套样本一段有明显问题的 React 组件代码、一段基本规范但不够健壮的代码、一段比较优秀的参考代码。跑三遍观察 Agent 是否按技能要求触发、是否漏掉关键点、是否误报。测试时我还会对比“开技能”和“关技能”的输出差异。如果两者差距不大说明技能内容写得不够有约束力如果差距很大但输出过泛说明 description 写得还不够细。我把测试中发现的典型问题都记录下来。比如 Agent 把“缺失 key”和“组件过大”都报成“严重”我就在清单里追加一句“严重级别仅在导致运行时错误或明显性能瓶颈时标注”。多迭代几次技能会越用越顺手。这里提醒一句测试样本不要只准备一种多样性越强你越早发现技能的边界在哪。3.5 第五步安装、版本化与分享技能完善之后就是安装和发布。本机使用时大多数 Agent 运行工具都支持指定 skills 目录把文件夹放进去即可。团队共享时我更建议把技能目录纳入 Git 仓库管理每次改动走 code review避免技能成为新的黑箱。提到发布官方市场和社区平台都有对应流程但发布前需要注意三件事版本号要写清楚方便回退description 必须准确描述触发场景别为了曝光乱碰瓷高频词不要把包含敏感信息的示例带进技能包。这些看起来是小事实际发布时最容易翻车尤其是第三点很多人把内部代码片段直接粘进技能示例一发布就泄了底。4. 生态巡礼官方市场、开源仓库和我自己的选型判断4.1 官方市场与官方技能格式先解决“从哪里拿”现在各大 Agent 产品基本都有官方技能市场你可以在里面找到别人写好的技能直接安装。我试过从官方市场装几个社区技能整体体验是标准化程度高、格式统一、更新比较及时。对于常见的代码审查、文档生成、命令行操作类任务官方市场里的技能往往已经够用。社区里还有各种 awesome 系列仓库专门聚合高质量技能清单遇到官方市场搜不到的场景去这些仓库里翻一翻经常有惊喜。我自己的使用习惯是市场技能用来解决通用任务比如博客文案生成、代码格式化这类不需要特定项目背景的项目特有规则比如某个团队的命名规范、目录约定、发布流程我一定会自己写技能。因为市场里的通用技能根本不知道你的项目上下文硬套只会得到正确但不适用的结果。4.2 Claude、Codex、开源 Agent 的 Skills 机制差异不同的工具对技能的称呼和格式略有差异。Claude 这边有 Skills 机制核心是 SKILL.md 加描述式触发我上面讲的实操流程就是按这套思路来的。Codex 则偏向把项目级经验放进配置里随项目走。开源社区更百花齐放有独立的技能管理工具也有人用 Rust 写 Agent 运行时把技能当作配置文件加载性能好、启动快、可移植性也不错。我试过在不同工具之间迁移同一个技能包整体感受是底层语言和框架各有取舍但技能格式大同小异核心都是“描述 指令 可选脚本”。只要你把技能内容写得尽量不依赖特定 API换工具时基本只需要微调描述字段就能跑起来。这也是我敢在技能上持续投入的原因这玩意儿不会因为你换一个 Agent 产品就完全作废。4.3 我在选型时的三个判断标准选什么生态我只看三点。首先是触发准确度技能能不能在合适的任务里自动启用不乱触发是底线一个动不动就跳出来的技能比没有技能更烦人。其次是更新频率一个技能三个月没人维护基本可以判定它在当前模型版本下已经不够准了模型一直在变技能如果不跟着调很快就会失真。最后是安全性第三方技能我会要求先审一遍内容再启用运行权限尽量收敛涉及命令执行的技能先扔进隔离环境试跑。满足这三点无论官方市场还是社区仓库都可以放心用。4.4 技能从哪里获取市场、仓库、自己造如果你不知道从哪里开始我建议按这个顺序走先到官方市场搜现成技能解决 70% 的通用需求再去社区聚合仓库找特定场景的高质量技能剩下的 20% 自己动手写。很多人习惯一上来就自己造轮子其实很多时候你想要的技能别人已经写好了直接用比自己写高效得多。善用“awesome skills”之类的索引仓库你会打开一片新天地。所谓“打开新世界”我第一次在仓库里翻到一堆高质量技能时的感受就是这样。5. 避坑手册我在 Agent Skills 项目里踩过的坑5.1 常见问题速查表我把测试这段时间遇到的高频问题整理成了一张表你可以对号入座现象可能原因解决办法技能完全不生效目录结构或 SKILL.md 文件名不对对照官方格式检查确认元信息字段完整技能乱触发description 写得太宽明确触发场景和排除场景补充负例说明触发后上下文爆炸技能正文太长且被全文加载拆分技能正文压缩大段资料移到 references 按需读取输出风格不稳定缺少输出模板或正反例在正文里给出严格输出格式附参考样本换 Agent 后失效依赖了原工具的私有能力减少对特定 API 的依赖尽量用通用文件和标准脚本技能被模型忽略指令和用户请求冲突调整优先级提示在技能中写明执行权重这些坑我基本都踩过一遍尤其“技能乱触发”那个一度让我怀疑是不是整个机制有问题。后来发现就是 description 写得有问题改完立刻正常。所以排查的时候先怀疑自己的描述再怀疑格式最后才怀疑工具本身。5.2 安全红线外部技能先审后启用技能本质上是外部输入的指令文件如果加载了恶意或含有诱导性内容的技能Agent 可能在执行任务时被带上危险动作这就是指令注入带来的风险。我看到社区里已经有“自动挖洞”之类打着渗透测试旗号的技能包流传普通人装上去Agent 可能在不知情的情况下去扫描不该扫的目标。所以我对安全这事格外敏感。我的安全原则很简单第三方技能必须先完整读一遍再启用技能内不要内置任何敏感配置运行权限始终最小化涉及执行命令或文件操作的技能先跑在隔离环境里验证。不要因为技能写得漂亮或者宣传获得高赞就无脑信任技能是给 Agent 吃的“饭”吃坏肚子是要出事的。5.3 记忆、Token 与召回别把状态塞进技能技能不是记忆技能负责“方法”不负责“事实”。有些开发者把用户偏好、项目状态往技能里写结果技能越来越臃肿还导致不同 Agent 之间状态错乱。正确做法是状态走 memory 或配置文件技能只保留方法和规则。我见过一个团队把“当前迭代进度”写进技能文件结果另一个 Agent 加载后把进度当作自己的任务背景整个流程直接乱了。token 控制也是关键点。我的习惯是技能正文控制在 500 到 1000 字左右超过的部分放进 references按需读取。这样即使技能库里有几十个技能日常任务也不会被拖慢。记住技能不是写得越长越好能一句话说清的规则坚决不用三段话。5.4 迭代意识技能也需要“版本管理”技能不是写完就一劳永逸。模型在升级项目在变化团队规范在更新技能三个月不看就可能过时。我的习惯是给技能文件夹加一个 changelog 文件每改一次写两行说明改了什么、为什么改。虽然听起来麻烦但团队协作时能避免很多扯皮。有一次同事想优化某个技能看我留下的 changelog 才知道上一版因为误报率太高被回退过省了他重走弯路的半天时间。我把这种迭代看作技能的第二生命。一个技能从粗糙到顺手通常要经过四五轮小的调整你真正需要的不是一次写完美而是不断跟进使用反馈把它打磨成团队真正依赖的资产。如果非要总结一句我的体感那就是Agent Skills 把“经验”从人脑搬进了 Agent 的日常工作流这才是 Agent 能真正走进生产环境的关键一步。我这段时间最大的收获不是学会了几套格式而是开始用“给新同事写岗位 SOP”的思路去设计每一个技能想清楚职责边界、触发条件、操作规范和停止条件整套逻辑处处相通。你如果也想上手建议从自己日常工作里挑一个最重复、最烦的任务先写一个三百字的技能跑通一遍再慢慢打磨。最后分享一个小习惯每写完一个技能一定附一个最小测试样本并把预期输出写清楚。这样以后不管换模型、换工具你都能快速验证技能还灵不灵这是所有技能长期保值的前提。