最近我花了不少时间整理一个叫 agent-skills 的技能包仓库过程中发现一个很有意思的现象社区里几乎所有刚开始学 agent 开发的人都会把 skills 和 agent 本身混为一谈。有人问“能不能用一个 skill 去调度另一个 skill”有人把 agent 框架搭起来之后发现模型总在不该自由发挥的地方自由发挥于是跑回来问是不是我的 skill 写错了。这个问题问对了但需要先把概念拆清楚。agent-skills 这个命名其实承载了两层含义一层是“agent 能用的技能”另一层是“把技能做成可复用、可安装、可评估的软件包”。这篇东西我就从这两层含义出发聊聊我在这条线上一路踩坑、重构、验证之后觉得最重要的东西覆盖概念拆解、技能包结构、从零开发、挂载使用、评测方法和学习路线。不管你是准备给 Claude Code 或 Codex 做专属技能包还是单纯想搞清楚 skill 和 agent 的区别这篇应该都能给你一个比较完整的视角。1. 先分清三个概念agent、harness 与 skills1.1 skills 不是 mini-agent这是我在社区里看到误解最重的地方。很多人觉得 skill 就是一个小型 agent理由是它也能“干一件事”甚至能调用工具。但从架构上看两者完全不是一回事。agent 是一个拥有控制循环的执行体它能感知当前状态、决定下一步动作、调用工具、观察结果、再继续决策。它持有对话上下文也承担最终输出责任。而 skill 本身没有决策循环它不持有状态不能主动发起调用本质上只是一份“被加载后才知道怎么执行”的操作规范加资源包。我用一个餐厅的类比来理解这件事agent 是大厨harness 是后厨的管理流程怎么接单、怎么传菜、食材从哪领skill 则是菜谱和专用厨具。菜谱不会自己炒菜但大厨拿到菜谱之后能稳定做出口味一致的菜。如果你把菜谱本身当成大厨就会陷入“skill 能不能调度 skill”这种无解的讨论。1.2 harness 决定 agent 的执行边界skill 决定能力上限harness 这个词在热搜里经常和 agent 并列出现很多人问“harness 和 agent 区别”。简单说harness 是包裹着模型的那层执行环境负责模型调用循环、工具注册、上下文管理、权限控制、历史截断这些脏活。agent 是 harness 之上更偏业务逻辑的概念强调“自主完成任务”skill 则是在两者之间插入的能力单元。我自己的体会是同一个 skill在不同的 harness 里触发方式和效果可能差很多。有的 harness 会把 skill 目录里的 SKILL.md 全文注入系统提示词有的则只做按需检索模型遇到相关任务时才去读。这两种机制决定了你写 skill 描述时的策略全量注入时描述不能太长否则浪费上下文按需检索时则要把触发条件写得非常精确否则模型根本想不起来去搜索它。所以“harness 和 agent 的区别”背后真正重要的问题不是名词定义而是“你选的 harness 决定了 skill 怎么被加载、怎么被消费”。做 skill 评估的时候也必须绑定具体 harness脱离执行环境谈 skill 效果没有任何意义。1.3 什么情况下才值得写一个 skill不是所有任务都适合做成 skill。我在项目里总结了一套判断标准满足以下条件越多越值得写同样的任务你已经手动处理过三次以上而且每次流程几乎一致任务有明确的输入和输出格式或者有可量化的验收标准任务需要外部工具、脚本或领域知识库配合你希望团队里其他 agent 实例也能复现同样水准的输出。反之那些探索性很强、依赖大量主观判断、或者只出现一次的一次性任务完全没必要封装成 skill。强行封装只会得到一个低质量的脚本最终模型要么不触发要么触发后反而限制了自由发挥。记住skill 的初衷是稳定不是万能。2. 拆开一个现成 skill从 SKILL.md 到附属资源的完整结构2.1 SKILL.md 是操作手册不是一句提示词先看目录形态。现在主流的 agent 技能包基本都采用“一个目录一个 skill”的组织方式latex-formatting/ ├── SKILL.md ├── scripts/ │ ├── validate_tex.py │ └── build_check.sh ├── references/ │ ├── chinese-latex-guide.md │ └── font-issues.md └── templates/ ├── paper.tex └── resume.tex最关键的文件是 SKILL.md。它是一份让模型按步骤执行的“操作手册”而不是一句“帮我排版一个 LaTeX 文档”这种提示词。SKILL.md 里要写清楚这个技能在什么场景下触发、输入需要满足什么条件、执行分哪几步、每一步产出什么、怎么判断是否完成、遇到常见错误怎么处理。我见过不少新手把 SKILL.md 写成了 prompt 模板通篇都是“请你高质量地……”这种话。实际跑起来会发现模型确实被触发了但输出质量毫无保证因为缺乏可验证的中间步骤。SKILL.md 的力量来自于约束它能把你平时靠手工校对、靠经验判断的隐性知识转成模型可以逐步执行的显性流程。2.2 scripts、references、templates 各自承担什么职责这三个附属目录不是装饰它们解决了 SKILL.md 写不下的三类问题。scripts 是“可执行的知识”。比如 LaTeX 排版任务里模型经常写出 \begin{document} 却没写 \end{document}或者中文引号用了英文符号。与其在 SKILL.md 里用文字反复提醒不如写一个 validate_tex.py 脚本让模型输出前必须跑一遍校验。把主观判断变成脚本检查是 skill 工程里性价比最高的投资。references 是“按需阅读的领域知识”。你在 SKILL.md 正文里只需要写“中文文档优先使用 ctex 宏包具体配置见 references/chinese-latex-guide.md”不用把所有字形、字体、编译器的细节全部塞进正文。这样既控制了上下文长度又保证了技能包的领域深度。templates 是“成品的骨架”。模板的作用不是让模型照抄而是给它一个高质量的起点。写论文时给一个 paper.tex 骨架简历排版时给一个 resume.tex 骨架模型只需在模板基础上填空和调整出错的概率会大幅下降。2.3 两种典型 skill 形态流程型与命令型拆过几个热门技能包之后我发现 skill 大体上分两种形态。第一种是流程型典型如 LaTeX 排版、代码审查、论文润色。这类 skill 的核心是一个多阶段 workflow先收集信息再生成初稿然后跑校验脚本最后根据报错修复直到所有检查通过。流程型 skill 的成败取决于你在 SKILL.md 里有没有把“循环修复”的条件写清楚。第二种是命令型典型如结构图生成、图片生成、图表绘制。这类 skill 更像一个“参数化工具”给定主题生成一段可复现的绘图脚本或者构造一组绘画接口调用参数把输出固化为文件。命令型 skill 写起来更容易但要注意结果的确定性不然同一个输入两次跑出完全不同的图使用者会很头疼。社区里近期讨论度很高的 superpower skills 这类技能包集合基本就是把大量流程型和命令型 skill 打包在一起提供一个开箱即用的技能库。我建议初学者不要只是安装它而是安装之后逐个拆开读一遍看看别人的 SKILL.md 是怎么组织步骤的。这比看任何教程都管用。3. 从零开发一个 skill以 LaTeX 排版技能包为例的完整实操3.1 先定义能力边界和触发条件很多人跟我说想要一个“写论文 skill”但这个定义太宽了模型一定会困惑。我在开发自己的 LaTeX 排版 skill 时第一步就是把能力边界收窄这个 skill 不负责帮你写论文内容只负责把已有内容组织成一份可编译、结构规范的中文 LaTeX 文档。接下来定义触发条件。我在 SKILL.md 的 description 字段里明确写了description: 当用户提供章节级文本要求生成或修复 LaTeX 文档时使用。 适合处理论文排版、报告排版、简历模板生成等任务。 不要在用户只是闲聊或询问 LaTeX 概念时触发本技能。description 里加入“何时不要使用”是我踩了很多次坑之后才加上的。否则模型在用户问一句“LaTeX 和 Word 哪个好用”的时候也会去加载整套 skill白白浪费上下文还干扰正常对话。3.2 写 SKILL.md把经验流程化我实际使用的 SKILL.md 核心流程是这样的收集必要信息文档类型、标题、作者、章节结构、是否需要封面页选择合适模板论文用 templates/paper.tex简历用 templates/resume.tex生成 main.tex中文环境固定使用 ctex 宏包编码统一 UTF-8运行 scripts/build_check.sh 编译检查存在错误则定位修复输出前必须运行 scripts/validate_tex.py确认 LaTeX 标签和环境的闭合配对向用户汇报生成的文档路径和编译结果。每一步都写清楚产出物尤其是最后两步。模型天然倾向于“生成完就结束”如果你不在 SKILL.md 里把“输出前必须运行校验脚本”写成硬性要求它大概率会跳过检查直接给你一个半成品。配套的校验脚本不用写得很复杂Python 几十行就够#!/usr/bin/env python3 import re import sys def check_balance(content, pattern, name): pairs re.findall(pattern, content) opens [p for p in pairs if not p.startswith(/)] closes [p for p in pairs if p.startswith(/)] if len(opens) ! len(closes): print(ferror: {name} 标签不匹配, opens{len(opens)}, closes{len(closes)}) return False return True def main(): filename sys.argv[1] with open(filename, encodingutf-8) as f: content f.read() ok True ok check_balance(content, r\\begin\{\w\}|\\end\{\w\}, environment) ok check_balance(content, r\\[a-zA-Z]\{|\}, brace) if not ok: sys.exit(1) print(validate passed) if __name__ __main__: main()这套脚本的好处是把“检查质量”从模型的主观判断变成了确定性结果。只要模型按流程执行脚本输出质量的下限就有了保证。3.3 在 agent 里调试验证跑通完整闭环skill 写完不是结束必须在真实的 agent 环境里跑通。我通常准备三组测试输入第near一组是一段带完整章节的中文论文内容第二组是只有零散笔记、需要模型自行组织的内容第三组是故意包含错误 LaTeX 语法的内容。调试时的观察重点是模型有没有在正确时机读 SKILL.md它在执行第几步时开始乱来校验脚本的报错信息是否足够明确能让模型自己定位修复如果校验脚本只输出“validate failed”模型往往无从下手但如果你在脚本里输出具体是哪个 environment 不匹配模型就能精准修复。我调整 skill 的时候最常遇到的问题就是模型不主动调脚本。后来我在 SKILL.md 里加了一句话“任何情况下都不允许跳过第 4 步和第 5 步如果脚本运行失败必须根据报错修复后重新运行直到通过为止。”这句话解决了 80% 的流程断裂问题。3.4 版本与收纳让技能包可演进技能包也需要版本管理。我习惯在目录里放一个简单的 metadata 字段至少包含 name、version、date、description 四项name: latex-formatting version: 1.2.0 date: 2025-06-01 description: 中文 LaTeX 文档排版与修复技能包版本号的意义在于当你更新 SKILL.md 之后可以通过老版本测试集来验证新版本有没有破坏以前能跑通的场景。我见过太多人只改代码不标版本结果 skill 行为漂移了都没察觉。整体仓库推荐这样的布局agent-skills/ ├── README.md ├── bootstrap.sh ├── skills/ │ ├── latex-formatting/ │ └── diagram-generation/ └── evals/ ├── cases/ └── run_evals.pyREADME 说明每个 skill 的用途、适用 harness 和版本bootstrap.sh 负责把 skills 目录同步到本地的 agent 配置目录evals 放评测用例。这样个人用、团队用都很顺手。4. 安装、集成与团队化使用Claude Code、Codex 和 opencode 的差异4.1 主流 harness 的 skill 挂载方式对比目前我常用的几个工具在 skill 挂载上并不完全相同差异主要体现在“skill 如何被发现”和“skill 如何被加载”。以我用的版本为例Claude Code 支持在项目的 .claude/skills 目录下放置技能包每个 skill 一个文件夹运行时会把 SKILL.md 中的 metadata 和描述注入模型可感知的环境具体文件内容由模型按需读取。Codex 更偏重 AGENTS.md 这种“持续指令”方式动态说明项目里的技能资产放在哪里、什么时候应该使用哪个 skill。它更像把 skills 作为工程文档体系的一部分而不是独立的插件系统。opencode 等新一些的工具则在往“按需加载”的方向走模型先根据语义检索出可能需要的 skill 列表再读具体 SKILL.md。我的建议是不要迷信“支持 skills”这个标签要先确认它支持的是哪种加载方式。如果是全量注入型SKILL.md 控制在 500 行以内比较稳妥如果是按需检索型则要重点打磨 description确保检索语义能命中。安装路径上常见的方式是直接目录克隆和符号链接。团队场景下我更推荐符号链接每个人 clone 同一个技能仓库然后 bootstrap 脚本把相关目录软链到各自的 agent 配置路径这样更新技能时只需拉一次仓库。4.2 团队技能库配置范例我在团队内部维护的 bootstrap.sh 核心逻辑如下#!/usr/bin/env bash SKILL_REPO$HOME/code/agent-skills TARGET_DIR$HOME/.claude/skills mkdir -p $TARGET_DIR for dir in $SKILL_REPO/skills/*/; do name$(basename $dir) if [ -e $TARGET_DIR/$name ]; then rm -rf $TARGET_DIR/$name fi ln -s $dir $TARGET_DIR/$name echo linked $name done这个脚本本身没有黑科技但它把“新成员怎么接入技能库”这件事变成了一条命令。新同事 clone 仓库、跑一次 bootstrap、打开 Claude Code所有技能就位。4.3 使用中的常见失效现象与补救用了一段时间之后我发现 skill 失效通常有几种模式问题和补救办法也相对固定。该触发不触发description 里的语义和用户实际表达之间距离太远。补救办法是把用户可能说的“口语化表达”加进 description比如“帮我排个版”“写个简历模板”。不该触发乱触发description 缺少否定条件。补救办法是加“不要在……时使用”的约束遇到闲聊或概念咨询时明确不加载。步骤被跳过模型生成了内容但没有跑校验脚本也没有套用模板。补救办法是在 SKILL.md 步骤里把“必须运行脚本”写成硬性条件并在步骤间增加产出物说明。输出不稳定同一个输入两次结果差很多。补救办法是强化 templates 和 scripts 的权重让模型在成熟骨架上修改而不是每次从头自由发挥。5. 怎么评估一个 skill 好不好我的 agent evals 实测方法5.1 评估的四个维度技能包能不能用、好不好用不能靠感觉要回到 eval。我自己在做 agent evals 时会固定盯四个维度维度测什么我的通过标准触发准确率该触发时触发不该触发时不触发20 个用例中错误触发不超过 1 个流程完整率关键步骤是否全部执行脚本是否运行每个用例的关键步骤覆盖率达到 100%输出合格率产物是否符合验收清单核心验收项全部通过回归稳定性修改后老用例是否仍成功历史用例通过率不下降这套维度对流程型和命令型 skill 都适用。命令型 skill 更看重输出合格率流程型 skill 更看重流程完整率但四个维度都应该记录。5.2 搭建最小可用的评测集最小评测集不需要复杂平台一个目录加一个脚本就够。我在 evals/cases 下放一组 markdown 文件每个文件是一条评测用例包含输入、期望行为、期望输出清单。比如# case-001 ## 输入 用户提供了一篇包含引言、方法、实验、结论四章的论文草稿要求生成 LaTeX 排版文件。 ## 期望行为 - 加载 latex-formatting skill - 选择 templates/paper.tex 模板 - 生成 main.tex - 运行 validate_tex.py 且通过 ## 期望输出 - 存在 main.tex - 包含 ctex 宏包 - \begin/\end 配对正确评测脚本做的事情很简单逐条调用 agent 的非交互命令行把输入喂进去然后检查输出文件、日志和产物。脚本本身几十行就够但要注意把每次运行时的上下文快照保留下来否则模型中途哪一步走偏了你很难定位原因。我第一次跑 eval 时犯过一个错误只统计最终结果不看过程日志。后来发现某个用例输出文件偶然是好的但模型根本没按流程跑是碰巧修对了。这是假阳性会掩盖流程完整率低的问题。所以过程快照比结果更重要。5.3 从失败案例反推 skill 的问题评测的目的是改进不是打分。我把失败案例分成几类每类对应 SKILL.md 的特定位置描述语义没命中修改 description增加等价表达模型跳过检查步骤把该步骤提升为“必须执行”并附上不执行的后果示例输出不符合模板检查 templates 是否足够具体模型是否缺少参考样例校验脚本报错但模型不会修检查脚本报错信息是否足够定位问题必要时把常见错误和修复方式写进 references。每改一次 SKILL.md就重新跑一遍整个评测集。这听起来麻烦但正是这套“改一点、验一点”的循环让我的技能包从“偶尔能用”变成“稳定可用”。6. 学习路线与持续沉淀从会用 skill 到会造 skill6.1 三个阶梯消费、拆解、创造如果你刚入门 agent 开发我建议的学习路线是三个阶段。第一阶梯消费。先安装社区里成熟的技能包比如 superpower skills、hermes agent 自带的技能集合、还有各类专精技能画图、结构图、数据图表。这个阶段的目标不是“用得有多好”而是积累手感功能型技能平常怎么组织、流程型技能怎么设计步骤。第二阶梯拆解。把你正在用的技能包目录打开逐个文件读问自己几个问题这个 SKILL.md 为什么把某一步放在这个位置scripts 里每一项检查是为了防什么错templates 为什么长这样把答案写下来比读十篇教程都有用。第三阶梯创造。找你日常工作里最重复的那件事按第三节的流程从零写一个 skill然后绑到 Claude Code 或 Codex 里跑一周。跑通一个再去解决下一个。不用贪多一个能稳定改善你效率的技能包胜过一摞吃灰的模板。6.2 我沉淀下来的 skill 设计原则做了十几个技能包之后我的设计原则可以浓缩成四句话每个 skill 只解决一个明确任务宁可多装几个 skill也不做一个大杂烩完成定义前置先写清楚“什么样算做完”再写怎么做能脚本化的判断不放 SKILL.md把主观校验变成确定性检查每次修改都必须跑 eval用回归数据说话不靠“我觉得改了更好”。其中第四点最重要。没有回归测试的 skill 修改就是在给未来的自己埋雷。6.3 后续值得投入的方向skill 只是 agent 能力体系里的一个零件。社区里“rethinking skills and prompts”的讨论越来越多核心思路是那些本该沉淀的、反复使用的方法论不应该继续塞在 prompt 里而应该变成可管理、可评估、可版本化的能力单元。这是从“提示词工程”走向“技能工程”的一步。再往后我会优先关注三个方向agent 记忆让 skill 能利用历史交互数据、多 skill 编排让不同技能包组合成更大的工作流、eval 基础设施把评测用例做成团队资产而不是个人脚本。agent 的安全性同样不能忽视所有 skill 涉及的脚本和外部调用都应该放在可控的沙箱环境里运行。如果你现在正准备入坑 agent 开发我的建议很简单别一上来就搭框架、写框架。先挑一个自己每周都会遇到的重复任务按这篇里的思路写成 skill装进你常用的 agent 工具跑一周。跑通第一个之后你自然就知道下一步该往哪里使劲了。这套玩法我也是从“一个 LaTeX 排版技能包”开始的现在它已经成了我所有 agent 工作流的底座。
