1. 核心问题Agent Skills 到底解决了什么痛点我最初接触 agent 开发时也一度陷入了思维定式总认为让 AI 干活的唯一方式就是把所有要求、规则、步骤都塞进 system prompt或者压进一个大而全的 README 里让智能体去读。这种方式不是不行只是过了某个复杂度临界点后你会发现整个提示词结构臃肿得离谱修改一次要全局排查而且模型非常容易在长上下文里把重点指令“隐形化”。后来我用 Claude Code 和 Codex 这类编程智能体重新思考这个流程时才意识到行业里真正从工程角度去解决“给模型注入专业能力”这个问题的方案就是skills技能包。如果你把 agent 比作一个只能执行基本指令的外科住院医生那么 skills 就是给他陆续装上、随时取用的专科手术器械包。器械不用时放在仓库里只占用一点点元数据用到了才把这个器械包完整地递给他。这种模式的好处在于它不是在系统提示词里堆知识而是在模型意识到自己需要某个专项领域的方法时才动态地把对应的方法论和组织好的代码逻辑拉进来。从热词里能看到不少人在讨论 harness 和 agent 的区别其实我觉得这正对应了今天这个主题的一个侧面。harness 更像是承载 agent 运行的整套脚手架——工具注册、输出解析、循环控制、上下文剪裁都在 harness 层处理而 skills 是运行在 harness 之上的“类人专长模块”。简单说一个管运力一个管专业度。这个项目标题被很多人反复提起某种程度上也说明了一个新的技术共识正在形成调用模型能力的颗粒度正从发一段指令转变成装载一组完整的、可评测的、可复用的技能。整篇博文我就围绕这个共识来展开讲讲什么是真正好用的 skills怎么开发自己的第一个技能包怎么选型、安装现有技能以及实战里那些会让人一头雾水的坑。2. 生态盘点从 Claude Code 到 Pi Agent各自生态里的 Skills 侧写热词里同时出现了 claude code skills 安装、codex好用的skills、opencode skills、pi agent桌面端、hermes agent 安装这恰好说明 skills 不是某个单一产品的专有概念而是新一代 agent 基础设施里普遍采用的一层抽象。如果你正在纠结用哪个平台先把每个生态的技能机制看明白再决定怎么落地会省去非常多返工时间。2.1 Claude Code 的 Skills最像“太空步”的一层抽象Claude Code 是我最早接触的做 skills 概念验证的环境。它把技能组织成.claude/skills目录下的一组文件夹每个技能拥有一个SKILL.md文件里面用 YAML front matter 写元数据用正文写流程和方法。它最让我喜欢的一点是在主对话中你可以通过技能名这类主动唤起的方式让 agent 立刻加载对应的知识而模型自己在任务拆解时也会根据元数据里的 description 判断“我现在要不要用这个技能”。这种双触发机制用起来非常舒坦因为我既能在明确的场景里强制生效也能在模型自由发挥时给它足够的弹性去自主选择。我实测过一个小项目让它写一个 Python 的异步爬虫任务之前模型疯狂在循环节流和异常捕捉上自我发挥逻辑也过得去但风格极其不稳定。给 Claude Code 装上一个我自写的“高质量异步任务编写 skills”后它开始按照技能包里的流程约束去检查任务上下文、设计并发度、封装连接池连模块 docstring 的严谨程度都提升了一截。这就是 skills 的魔法场景一匹配上模型会认为“我应该按专家的标准去执行”而不是临时做一次普通的文本生成。2.2 Codex 与 OpenCode把技能的“原子能力”往工作流里嵌OpenAI Codex 生态里对 skills 的重视程度不遑多让社区里甚至把“codex 开发必备的 skills”当成了入行指南。Codex 在实现上更强调 skills 高频小步的原子能力比如一个专门负责“检查代码变更前后兼容性”的技能、一个专门处理“README 优化与文档统一”的技能。这种颗粒度划分带来的一个好处是单个技能高度可测试评估起来非常清晰。我写代码时经常把“自动生成 release note 的技能”、“输出测试矩阵的技能”、“审计依赖版本升级风险的技能”全部挂在同一个 agent 工作流里每个单元都像一个独立的微服务替换和升级都不影响其他部分。OpenCode 的思路又有些差异。它更倾向于把 skill 看作整个 agent 任务链里的一个 hook 节点用在哪一步、在什么条件下触发、失败后是重试还是降级都在配置里显式声明。这种“流程声明式”的做法对复杂工程非常适用不过在技能数量少、任务简单时容易显得过重。所以在我的经验里简单场景用 Claude Code 的轻量目录结构复杂流水线用 OpenCode 的显式编排结构。2.3 Pi Agent把 Agent Skills 做成“人机协同桌面层”热词里反复提到 pi agent 桌面端这是最近关注度非常高的一款agent执行环境。它的特点是把 agent 的运行挪到桌面客户端里让人可以直接看到智能体的思考过程、技能触发时机和上下文占用情况。对我来说它最强的点不是聊天界面多好看而是它对“技能市场”和“评测指标”的整合。很多新玩家问“skills怎么测评”Pi Agent 默认就把技能的召回频率、任务完成率、对上下文 token 的消耗做了可视化这在优化记忆和成本时是极大的帮助。有一点需要提醒Pi Agent 因为绑定了桌面环境对本地文件系统、浏览器、终端的访问层级非常深安全性边界完全取决于技能包怎么约束自己的行为。所以从“agent安全”的角度看安装不明来源的技能包前务必用隔离环境跑一次全链路模拟检查技能的每一步文件读写和指令执行是否越权。2.4 Hermes Agent 与开放式框架当 Skills 成为“最小知识单元”还有一部分使用者倾向于 Hermes Agent 这类更开放的框架它们的技能包本质上是由“元数据 指令模板 工具调用配置 参考样例”组成的复合目录。热词里提到的“她的 agent” 实际上是一些人把多角色人格、专属工作流封装成的能力集合体这也要归入 agent skills 的范畴。框架开放的另一面是选择焦虑所以我一般建议新手不要一上来就追新框架先在 Claude Code 或 Codex 生态里把技能的编写逻辑跑通再往开放架构迁移。下表是我基于自己的经验整理的几个主流环境的横向对比方便你在决定踩哪个生态之前先有个数据视角环境技能目录机制触发方式复杂度适合场景Claude Code.claude/skills目录 SKILL.md显式 技能名 智能体自主触发低日常开发、个人效率辅助Codex原子技能命令 任务链集成自动按描述匹配可在 API 中强制调用中代码生成流水线、评测驱动开发OpenCode技能hook节点与编排声明严格按任务流程触发支持失败降级中高复杂多阶段任务、团队协同开发Pi Agent桌面端技能市场 可视化评测桌面唤起 上下文智能推荐中人机协同分析、可视化监控Hermes Agent通用的知识技能目录完全由 agent 规划器选择高定制化自由度要求高的深度用户看完这张表你应该能理解skills 的价值不是某一个工具的定义而是一种组织知识和工具调用的通用模式。这个模式放到哪个 agent 平台上都能成立区别只是写法、路径和触发规则的不同。3. 从零手写一个技能包格式、结构与一个可直接照抄的样例很多人问“skills怎么写”我建议把重点放在让技能包具备三个特性可发现、可理解、可执行。可发现指元数据描述足够准确agent 在决策时一眼就能判断何时使用它可理解指正文里的步骤足够清晰不会让模型在中间环节产生歧义可执行指你提供的检查清单、代码片段、命令行工具都是直接能跑的而不是抽象的“就像这样那样做一下”。3.1 目录组织一次把信息架构做对我惯用的技能包目录组织方式大致这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── validate_input.py │ └── process_data.py ├── templates/ │ ├── report_template.md │ └── code_snippet.py └── assets/ └── reference_table.mdSKILL.md是灵魂入口scripts放可执行工具templates放输出模板assets放参考知识。这种分层最大的好处是让模型在“需要看代码逻辑时”只打开 scripts 文件而不是每次都去阅读庞大的完整知识库。很多新手把所有内容都塞进一个超长 markdown导致加载慢、关键信息被淹没这是首个常见反模式。3.2 SKILL.md 的标准骨架与字段意义一个合格的 SKILL.md 长这样--- name: frontend_performance_audit description: 对前端项目进行性能基线审计输出关键耗时指标、资源加载分析和优化建议清单。 when_to_use: 页面交互明显卡顿、首屏加载过慢、需要性能优化前的基线数据收集时使用。 prerequisites: - node 18 - 已安装 lighthouse 依赖 version: 1.0.0 --- # 前端性能审计技能包 ## 执行流程 1. 启动本地开发服务器确认项目可稳定访问。 2. 使用 lighthouse 对首页进行三次采样并取中位数。 3. 分析主线程占用、网络请求队列与资源体积关系。 4. 输出优化建议并按优先级排列。 ## 关键命令 ...你注意 description 字段它不能像写散文一样写长篇大论而应明确覆盖“这个技能是做什么的”和“什么状态下应该拿起它”。代码模型在做工具匹配时是高度依赖语义相似度的描述里的动词和名词越接近用户问题的真实表达命中率就越高。when_to_use 这个字段在不少框架里被单列虽本身不直接触达 prompt但它是模型内部 classify 的重要辅助特征。相当于给技能装了一个“使用场景雷达”。3.3 我在写技能时遵循的“三层设计法”第一层是领域知识包括术语、背景和约束这个部分来源可以是官方文档、书籍、你自己踩坑沉淀的经验作用是让模型不至于在基础概念上犯浑。第二层是操作流程你要把专家做事时的步骤按时间顺序拆开告诉模型先做什么、后做什么、什么情况下可以跳过某一步。第三层是质量验收标准等于给输出定义一套可见的勾稽关系报告里必须包含哪些指标、代码里必须有什么类型的 docstring、哪些 lint 规则必须通过。没有第三层技能包只是知识的堆砌有了第三层它才变成可执行的“手艺”。我自己最爱写的技能包是用在“将零散需求转化为技术方案文档”这个场景上的。技能包里我强制模型按背景调研、约束分析、选型对比、风险识别、实施步骤、回滚方案六段式输出并且给每一个技术选型强制补充至少两个备选项。测试下来输出质量和稳定性提升非常明显特别是在面对模糊需求时模型的“即兴发挥”被流程约束住了出来的方案一眼就能感觉到“有框架”。3.4 一个可直接抄作业的轻量技能包如果要说一个最通用的入门样例我建议学会自己给代码库生成“变更影响分析技能”。在你的技能目录下建这样的SKILL.md--- name: change_impact_analysis description: Analyze the impact of code changes in a repository, produce a risk assessment and recommend necessary follow-up actions. when_to_use: after modifying core modules, before submitting a pull request, or when planning a large refactor. --- # Change Impact Analysis ## Goal Understand which components, tests, and documentation files are affected by uncommitted changes. ## Procedure 1. Read git diff --name-only to list changed paths. 2. For each changed file, determine its dependency relationships by inspecting import/require statements. 3. Search for usages of exported symbols across the repository. 4. Identify test files that cover affected modules. 5. Produce a markdown report with three sections: affected modules, suggested test commands, and risk notes. ## Report Format markdown ## Summary of Changes ## Affected Modules ## Suggested Test Commands ## Risk NotesQuality BarMust cover every changed file.Must list concrete test commands, not generic advice.Risk notes must explicitly distinguish breaking changes from compatible changes.这个技能写起来不到三十行但价值非常高。实际使用中在准备 PR 之前手动唤起它模型就会按上面的流程把 git diff 与模块依赖关系扫一遍输出一份扎实的风险评估大幅减少“改了 util 导致远端接口挂掉”这类低级事故。 ## 4. 安装与调用过程里真正需要重视的“暗坑” 有很多人搜索 claude code skills 安装、superpower skills 安装、图片生成skills安装包、latex排版skills说明大家解决问题的思路没问题但不少坑往往发生在安装和调用这一层。这里不重复那些一搜就有的安装命令重点聊聊我踩过几次、且容易长期潜伏的问题。 ### 4.1 技能包永远不会被命中先检查描述与触发词 最典型的症状就是技能包装好了目录位置也正确但无论怎么问agent 就是不理它仿佛技能包不存在。绝大多数情况问题出在技能元数据里的 description 描述不够“接近自然语言”。你要站在“模型如何匹配”的角度去想这件事当用户说“帮我看看这部分改动会不会影响老接口稳定性”模型脑子里把这句话向量化后是在和一个 description 字段做匹配。如果你技能包里写的是“Analyze code impacts and risks”那么很可能因为它不够具体而被其他更泛化的工具先抢答。 我的做法是用一组真实的用户问句去反向构造 description。例如同时列出“这个改动会影响什么”“重构后有哪些依赖需要迁移”“变更评估报告”然后把它们的共性语义浓缩进 description 中。这样匹配精准度会明显提升实测下来技能调用率提高了非常多。 ### 4.2 技能内容过载一次加载几十个技能会让模型“选择瘫痪” 我很理解大家在各种 skills 源网站上下载了大量看起来都很有用的技能包装上去之后颇有一种“武装到牙齿”的安全感。但 agent 在执行任务时会在一次决策窗口里评估大量可用技能如果你的技能列表过于庞大模型会选择困难甚至跳过最合适的那个随机走向一个相关性一般的技能或者明明不该触发技能的任务它非要牵强地触发某个技能导致输出变得拖沓。 推荐原则**运行环境里保留的常用技能不超过 10 个其他长期不用的移到归档目录**。就像人在工作台上放太多工具时反而降低效率一样给模型保留一个“够用且清爽”的技能集是所有工程化落地里性价比最高的一招。 ### 4.3 技能与 Harness 的版本耦合问题 热词里持续有人问 harness 和 agent 的区别其实这个问题也会演化成技能包层面的坑。不同 harness 版本之间工具执行的上下文注入方式、上下文窗口策略、多轮调用的状态保持机制都会变化。你为一个旧版本 harness 调优好的技能包升级到新版本后可能表现大幅下滑。这种问题最隐蔽的地方在于它不报错、不失败只是输出变得中庸像“一次性”回答却又说不出哪里有毛病。 我缓解这个问题的办法是每个技能包里显式写明最低兼容的 agent 版本并对技能包做版本化语义管理。主版本不兼容时不采取原地修改而是另建一个新目录专门适配新版本旧版本保留归档以备在项目降级时快速回切。这个方法帮我在一次大版本升级中省下了整整一个下午的排查时间。 ### 4.4 技能包内部互相“污染”命名空间与副作用管理 框架不会刻意隔离技能与技能之间的文件读写或变量命名。两个技能包如果 scripts 目录下都有 utils.py 或 helper.py在部分执行机制下就可能出现互相覆盖的问题。此外某个技能在自己的示例代码里定义了一个“长度为 1000 的临时列表”但它的副作用是修改了全局配置里的 OUTPUT_PATH另一个技能使用时就会读到错误的路径值。 所以我一般要求技能包遵循“**外部传入内部输出**”的原则所有路径必须由调用方注入所有可执行脚本禁止修改环境变量所有中间产物统一输出到当前工作目录下的独立命名空间。这样就不会因为临时状态而让两个技能产生隐式纠缠。 ## 5. 技能质量从“能跑”到“可信”评测方法与调优思路 再往下走一步就是很多人反复搜索的“skills怎么测评”。市面上会自动给出一些榜单和推荐其实最好的评测起点是你的真实任务集。对技能的评测本质上是对“在受控条件下技能包是否稳定地让模型输出更高水平结果”这件事做检验。 ### 5.1 一次性写死五个评测任务 我给自己的每个核心技能包都会配套一个评测集里面包含五类任务 - 一个最简单的基础任务验证最基本能力没有缺失 - 一个正常复杂度任务对应技能的典型使用场景 - 一个边界任务故意输入超出常规范围的数据观察技能的容错 - 一个对抗任务输入措辞模糊、结构混乱的需求看技能能否把对话拉回正轨 - 一个组合任务同时涉及多个技能包配合验证彼此协作不冲突。 这五类任务跑下来基本可以定性判断一个技能包是“偶有闪光”还是“稳定可靠”。迭代时优先修对抗任务和边界任务暴露的问题因为正常任务的问题通常一眼就能看出来而边界条件的坑往往藏得极深。 ### 5.2 量化指标的“温度”也要调 技能包评测不只看输出文本我在 Pi Agent 和 Claude Code 上评测时会重点记录三类量化指标**技能触发准确率**应当触发时正确触发/不应当触发时不误触发、**任务完成度**步骤覆盖率与质量标准达成率、**token 消耗倍数**使用技能前后的 token 增幅是否在合理区间。一个技能如果让准确率提升了 30% 但 token 消耗翻了三倍那在成本敏感的生产环境里未必划算。 调优时优先调的是 SKILL.md 里的流程描述。模型是极度依赖文本暗示的实体你写得越像一份内部专家给实习生的操作手册它的执行就越像专家。举个例子把“处理数据”改成“先去除空值与重复值再对异常离群点做标记然后归一化到 0-1 区间最后输出统计摘要和缺失值报告”模型的执行稳定性会直线上升。这个经验可以放到任何技能开发中反复使用。 ### 5.3 版本管理与团队协作的一些实践 实际做项目时一个技能包往往不止你一个人维护。我推荐团队里把技能仓库当成代码仓库一样管理实行 MR/PR 审查制。审查的重点不是看文笔而是看“新增内容是否只是知识堆砌”“流程步骤是否出现了相互矛盾的顺序”“模板文件是否被无谓格式调整”。技能包里的 diff 和代码 diff 很像一行描述用语的变化在模型侧可能会引发出完全不同的分支行为因此任何改动都要留痕、可回滚。 另外如果团队内已有自己的 agent 应用建议给技能包建一个 catalog.json 索引文件把技能名、版本、负责人、最后评测时间、核心标签都放进去。这么做一方面方便 agent 在运行时快速读取可用技能列表另一方面也是给团队留一份“能力地图”避免重复造轮子。 ## 6. 常用技能源网站与选型建议如何避开“看起来很强”的坑 最后聊一下很多人都关心的“从哪里获取技能包”。热词里提到常用 skills 源网站、图片生成skills安装包、latex排版skills。网上的技能市场逐渐多起来但质量参差不齐。我自己的筛选标准很朴素先看技能包的 SKILL.md 是否结构完整再看是否提供评测样例和版本记录最后看维护频次。一个常年不更新的技能包除非解决的问题极其稳定不变比如“文本标准化格式转换”否则大概率会随着底层模型能力变化而逐渐失效。 针对热门方向我分别给一点选型心得 - **图片生成 skills 安装包**优先选那些不仅提供 prompt 模板还把负面 prompt、画面比例参数、后处理流程也封装进去的技能包。安装后先用自己的固定 prompt 做对照实验看技能包是否真的提高了出图稳定性避免只是换了一批花哨提示语。 - **latex 排版 skills**核心不在“能生成 latex”而在“能否符合目标期刊模板规范、是否处理了跨页图表和参考文献压缩”。我建议选那些自带论文实时编译校验步骤的技能包它能在生成最终 pdf 前自动拦截格式错误。 - **superpower skills**这套技能以“组织任务执行流程”见长非常像给智能体装了一个项目管理方法论。但实话说它更适合做规划层不适合做专业领域执行层通常我会把它和具体的领域技能配合使用而不是单独依赖它。 所谓“好用的 skills”最终都要经过你自己的任务集磨砺才能真正好用。别人的金技能包拿到你的场景可能水土不服我的建议是把第三方技能包当作起点模板而不是最终答案。下钻到核心步骤里把与你实际业务流程不符的部分改掉把缺失的验收标准补上这个技能包才能像一件贴合你手掌的工具而不是一把所有人都攥过、但与谁都未必贴合的通用旋钮。 这个领域迭代极快我也还在持续替换自己手头技能库里的过时方案。每次模型能力大幅度升级时我会系统性重测一遍技能集把那些已经可以被模型默认能力覆盖的“廉价技能”淘汰掉把真正需要专家方法论的技能做深做实。从当前的趋势来看agent 与人协同的方式会越来越像“专家工具箱”而能把技能包写好、评估好、管理好的人会是这个时代定义自己生产力边界的那批人。
