过去两个月我一直在做同一件有点反直觉的事情明明日常工作是写代码我却花了大把时间研究怎么让 AI agent 学会排版。起因很普通有一阵子我需要频繁把技术方案整理成带规范格式的 LaTeX 文档试过让 Claude Code、Codex 这类 agent 直接生成结果每次都差不多——第一版看起来有模有样细看全是问题包引用缺一个、英文与中文之间不加空格、编译警告一屏都放不下。最气人的是我在对话里反复强调的规则换一个新会话它又全忘了。后来我把这些散落在对话里的修正经验整理成了一个个独立的 skill放进一个叫 agent-skills 的项目里。所谓 skill就是一段结构化的作业指导书它包含了任务流程、规范细节、配套脚本和模板agent 在需要时按需加载而不是每次对话都背着几万字规则。这篇文章就围绕 agent-skills 这个项目说说 skill 到底是什么、和 agent、prompt、harness 的边界怎么划、一个合格的 skill 目录应该长什么样、怎么从零开发一个 LaTeX 排版 skill以及安装接入和测评那些容易翻车的细节。无论你是在研究 agent 开发还是想让自己的 coding agent 更听话这篇都值得看完。1. 为什么我会专门做一个 agent-skills 项目1.1 从一次让 agent 排版翻车说起先说那次让我下决心做 skill 项目的翻车经历。当时我给了 agent 一个很具体的任务把一份 Markdown 格式的周报转成 LaTeX要求用 ctex 支持中文、代码块用 listings 宏包、正文五号字、页边距 2.5cm。agent 答得很快几分钟就给了完整代码。我拿去编译报错信息直接打脸缺listings的颜色依赖中文注释出现乱码标题层级和目录对不上。我一条条回给它它修完这一处又弄坏那一处来回折腾了快四十分钟。真正让我崩溃的是第二天。换了一个新会话我把同样的要求发给 agent它又犯了同样的错误甚至把前一天我纠正过的约定全忘了。那一刻我突然意识到问题不在 agent 笨而在我没有给它一个稳定的知识载体。对话里的修正是一次性的模型本身又不会在两次会话之间记住我的偏好——我需要一种机制把怎么排版才算对沉淀下来让 agent 随时能查、能照着做。1.2 把一次性修正变成可复用能力包所以我开始研究市面上各家 agent 的 skills 机制。发现各大工具虽然叫法不同思路其实高度一致给 agent 准备一个目录目录里放SKILL.md作为入口文件里面写清楚这个技能什么时候用、完整流程是什么、有哪些硬性规则再配上脚本和模板做确定性补充。agent 在启动时会扫描这些目录但不会把所有内容塞进上下文只有判断任务匹配时才加载对应的那个 skill。这个设计解决了我之前最头疼的问题——上下文污染。skill 是按需翻开的手册不是每天都在耳边念的规矩。它和 prompt 最大的区别就在这里一份系统提示词无论多长都会全程占着上下文而 skill 平时只占一行描述的空间真正用到时才把几百行细节加载进来。对长会话来说这种差异几乎是决定性的。1.3 agent-skills 项目的定位最终我建了一个叫 agent-skills 的项目本质是一个 skill 合集目前收录了 LaTeX 排版、结构图生成、图片生成、旧项目现代化改造等十几个 skill。这个项目在组织上有三个原则可复用每个 skill 都是一份目录能复制到任何机器、任何项目不绑定某个特定会话。可测评每个 skill 都带一组测试用例和评分清单改了不会偷偷变差。可迭代技能描述、指令正文、脚本三者分开维护改其中一块不影响另外两块。如果你问我 agent 开发学习路线里最该先搞懂什么我的答案不是 RAG不是多智能体协作而是 skill。因为它是当前让 agent 真正上手干熟练活的最小单元几乎所有编码 agent 都在往这个方向收敛。2. 先捋清概念skill、agent、harness 和 prompt 各管哪一段2.1 一张表格看清四者的边界跟同行聊 skill 的时候发现很多人卡在概念上尤其分不清 harness 和 agent 的区别。我用一个比较生活化的类比来理解把整个 agent 系统想象成一个餐厅。概念类比职责例子harness餐厅的场地和厨房设备运行环境、工具调用框架、上下文管理Claude Code、Codex CLI、opencodeagent主厨理解任务、规划步骤、决定调用哪个工具模型 循环决策逻辑prompt门口的招牌和菜单一开始就告知的通用规则系统提示词、CLAUDE.mdskill后厨的作业指导书按需加载的专项流程与规范排版流程、代码审查清单harness 管的是怎么做agent 管的是做什么prompt 管的是默认怎么想skill 管的是具体活怎么干。四者配合缺一不可。很多人把 harness 当 agent是因为现在 Agent 这个词被用滥了——你买的其实是一套 harness 加上一个大模型agent 能力是它们组合出来的结果。2.2 为什么 skill 不能和 prompt 互相替代有一个很常见的疑问既然 prompt 也能写规则为什么还要 skill答案是代价不同。把规则写进 prompt意味着每条规则都要在每一轮对话中参与计算无论用不用得着。规则一多模型注意力会被稀释反而更容易忽略真正重要的约束。我之前试过把排版规范写进项目级 CLAUDE.md结果 agent 在无关任务里也会莫名其妙套用排版术语输出风格变得很奇怪。skill 走的完全是另一条路。它的描述信息非常短大致是这个技能负责什么、什么时候启用模型看到后先判断要不要用一旦判定匹配才把完整的 SKILL.md 正文加载进来。这种渐进式披露的思路和人类读书很像先看目录和摘要确定要看哪一章再翻到那一章细读。这也是为什么像 superpower skills 这样的技能包会流行它本质上是一堆组织良好的 skill让 agent 在各种专项场景下都能快速对齐一套高质量工作流。2.3 什么时候该写 skill什么时候不该写不是所有东西都值得做成 skill。我自己的判断标准是如果这个任务满足下面至少两条才值得写。任务有固定流程步骤基本不会变。输出格式有硬性要求错了就要返工。规则相对稳定不会三天两头推翻。判断标准可以写成检查表或者脚本。反过来探索开放型任务就不适合做成 skill。比如帮我想几个产品创意分析这份数据有什么规律这种任务没有标准流程硬塞一个 skill 反而限制模型的发挥。还有一次性的小任务也不值得写直接对话里解决就行否则维护成本比收益还高。3. SKILL.md 规范与目录结构一个 skill 的标准长什么样3.1 目录骨架与文件职责我在 agent-skills 项目里用的目录模板是这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── render.py │ └── check-env.sh ├── assets/ │ └── template.tex └── references/ └── latex-cheatsheet.mdSKILL.md是唯一必须存在的文件也是 agent 加载这个 skill 时的唯一入口。scripts/放可执行脚本用来做模型不擅长的确定性工作assets/放模板文件保证输出不会长出各种奇怪形状references/放参考资料正文里不需要展开的细节可以丢在这里让 agent 按需查阅。这个分层结构遵循一个核心原则指令负责告诉 agent 做什么脚本和模板负责保证做出来的东西是对的。3.2 frontmatter 字段逐个说SKILL.md顶部需要一段 YAML frontmatter定义这个 skill 的元信息。以我的 LaTeX 排版 skill 为例--- name: latex-typesetting description: 将 Markdown 或草稿转换为符合学术规范的 LaTeX 文档。当用户要求排版论文、报告或技术文档时使用。 license: MIT allowed-tools: bash, python ---name是唯一标识尽量简短用连字符而不是下划线。description是最关键的字段它是 agent 决定是否加载这个 skill 的唯一依据必须写清楚什么时候用而不是这个技能有多好。license字段对开源项目有意义标明版权。allowed-tools限定这个 skill 里脚本可以调用的工具集也是安全边界的一层控制。这些字段不是摆设我在下文会专门解释它们怎么在实际运行中起作用。3.3 progressive disclosure为什么描述必须短我在 agent-skills 项目早期犯过一个大错把description写成了半篇说明文什么这个技能能够帮助用户以高效、专业、美观的方式生成 LaTeX 文档支持多种中文字体和参考文献格式同时保持代码简洁可维护。写完我自己看着都累agent 更是一头雾水。后来我对照各家 skill 规范才想明白skill 的索引阶段模型只看得到description这一小段文字。它要从这段文字里判断这个任务要不要用这个技能就像检索系统靠摘要判断相关性一样。描述写得越长信息密度越低误判率越高。我踩过的最离谱的坑是一个排版 skill 的描述里提到了图片处理结果 agent 在用户请求压缩图片时加载了排版技能。从那以后我把描述压缩成一句话模板[能力对象] [适用场景] [触发条件]。3.4 脚本、模板和静态资源怎么组织SKILL.md 正文解决的是流程和规则但光有规则不够。规则写得再细模型编译文档时还是可能忘加参数即使没忘输出格式也可能和手写不一致。所以我在每个 skill 里都尽量配上脚本和模板把确定性部分从模型手里拿回来。比如 LaTeX 排版 skill 里有一个check-tex.py负责编译.tex文件并解析编译日志把 overfull box、undefined reference、missing character 这类警告分类输出。模型只需要运行这个脚本然后根据输出修正不再需要自己猜有没有问题。模板文件则规定了正文结构、宏包引用顺序、章节标题样式模型往里面填内容就行稳定性和效率都大幅提升。这个思路可以推广到任何 skill凡是能用代码确定判断的就不要交给模型自由发挥。4. 实操从零开发一个 LaTeX 排版 skill4.1 需求拆分什么任务适合做成 skill我以 LaTeX 排版为例完整演示一遍开发过程。首先做需求拆分。日常排版任务可以拆成这几步读取源稿Markdown 或纯文本识别标题层级和正文结构。套用学位论文或技术报告的 LaTeX 模板。处理中文支持ctex 宏包、中文字体、中文标点。按规范格式化参考文献。编译并检查警告迭代直到无致命错误。每一步都有明确的输入、输出和验收标准这是做成 skill 的理想形态。拆分完成后我先写一份测试用例而不是先写指令——后面讲到测评时再说为什么。4.2 编写主指令把排版规范拆成可执行动作接下来是 SKILL.md 的正文。我的写法是列出有序步骤每一步都说明操作对象和验证方式避免总之要规范这种空话# LaTeX 排版 ## 执行流程 1. 读取源稿识别标题层级、列表、代码块和引用。 2. 复制 assets/template.tex 为同名 .tex 文件。 3. 将源稿内容填入对应章节不要在文档中手写样式命令。 4. 代码块统一使用 listings 宏包配置见模板不要自行增删参数。 5. 运行 scripts/check-tex.py根据分类结果修正。 6. 出现 undefined reference 时检查 label 和 ref 是否成对而不是新增宏包。 ## 硬性规则 - 中文与英文/数字之间加空格中文标点前后不加空格。 - 目录使用 \tableofcontents不用手工排版目录。 - 禁用 hyperref 默认蓝色链接样式按模板配置改为黑色。注意第 6 条这条来自我的真实教训模型遇到编译错误的第一反应往往是缺包于是乱加宏包反而引发更多问题。把正确动作写死在规则里比让模型自由判断靠谱得多。4.3 配套脚本与模板补全 agent 不具备的确定性模板文件的骨架我抽几条关键配置说明\documentclass[12pt]{ctexart} \usepackage[margin2.5cm]{geometry} \usepackage{listings} \usepackage{xcolor} \usepackage[hidelinks]{hyperref} \lstset{ basicstyle\ttfamily\small, framesingle, breaklinestrue }这些配置不是随便定的。hidelinks是为了满足链接不要带彩色边框的常见要求breaklinestrue是为了避免长代码行溢出页面。把这些写死在模板里agent 就不会每次自由发挥。脚本部分的核心是解析编译日志我会在脚本里把警告分成 error、warning、info 三级并给每条 warning 附上修正建议这样 agent 拿到的是可直接处理的结构化数据而不是一堆难懂的原生日志。4.4 本地验证用真实文档跑一遍写完 SKILL.md、模板和脚本后最重要的一步是本地验证。我会准备三份不同风格的源稿一份带大量代码块的技术文档、一份纯文字报告、一份带数学公式的草稿然后新建一个干净会话只给 agent 一个任务按技能说明完成排版。验证时我不手把手纠正就让 agent 自己读材料、自己调用脚本并迭代。任何需要我中途介入解释的地方都说明 SKILL.md 写得不到位回去补。这样跑三轮之后我通常会发现两个问题一是描述写得还不够精准agent 一开始没识别出该用这个技能二是某条规则覆盖不到特殊场景。修完再跑直到三轮无人工介入顺利通过。这个流程特别像给新员工做上岗培训只不过我的新员工每次都是失忆的所以我必须把所有知识都写到手册里。5. 安装、接入与多端适配Claude Code、Codex、opencode 的差异5.1 三种常见的安装路径skill 开发完接下来是安装。目前主流 agent 的安装方式大体有三种用户级全局目录放在~/.claude/skills或~/.codex/skills这样的路径下对当前用户的所有项目生效。项目级目录放在项目仓库内的.claude/skills或.codex/skills目录随代码库一起提交团队成员自动共享。第三方技能包安装从网上下载别人打包好的 skill 仓库然后复制或软链接到上述目录。我的 agent-skills 项目采用第三种方式管理所有技能维护在一个 git 仓库每个技能一个子目录另外提供一个install.sh脚本根据参数把指定技能软链到各 agent 的全局技能目录里。这样同一个仓库可以同时服务 Claude Code、Codex 和 opencode因为它们都认SKILL.md这个入口文件差别只在目录路径。5.2 全局还是项目级怎么选选择安装层级我建议按这个标准判断场景推荐层级原因个人写作、日常排版偏好用户级全局所有项目都能用不影响团队团队代码规范、统一提交信息项目级进 git所有人默认加载公司级安全审查、合规流程项目级 代码评审可审计、可回溯实验性技能、还没调稳先不装本地测试避免污染工作环境需要特别提醒的是项目级 skill 一旦进 git所有协作成员都会被影响。所以我的建议是未经过测评的技能不要进入团队共享目录。我在 1.3 节强调可测评原则就是这个原因。5.3 多 agent 共用一个 skill 仓库的实践不同 agent 对 skills 目录的识别规则略有差异但我的兼容策略很简单在 install 脚本里做一层映射。脚本维护一个表格把每个 agent 的 skills 根目录列出来然后逐个创建软链接。实际使用的代码逻辑大致是#!/usr/bin/env bash # install.sh —— 把 agent-skills 里的指定技能软链到各 agent 目录 SKILL_NAME$1 AGENT_DIRS( $HOME/.claude/skills $HOME/.codex/skills $HOME/.config/opencode/skills ) for dir in ${AGENT_DIRS[]}; do mkdir -p $dir ln -sfn $(pwd)/skills/$SKILL_NAME $dir/$SKILL_NAME done这样我改一次技能内容所有 agent 下次启动时都能加载到最新版本。注意软链接在 Windows 上可能需要管理员权限跨平台使用时建议改成复制命令或者在安装脚本里做一次平台判断。5.4 接入后常见报错与排查接入过程中最常遇到的报错是 agent execution terminated due to error这个错误提示看起来吓人但通常原因不复杂我列一张排查清单技能目录里脚本退出码非 0检查scripts/下脚本能否在终端独立运行。description里提到了不存在的文件路径agent 加载后找不到文件直接中断。allowed-tools限制过严脚本需要 bash 但清单里只写了 python工具调用被拒。软链接失效仓库目录移动后链接变成断链agent 扫描时读到空目录。技能内部引用了相对路径但 agent 的工作目录不在技能目录下。遇到报错我第一件事永远是看完整日志栈而不是盲目改技能内容。绝大多数情况下把日志里最后几步操作还原出来问题就一目了然了。6. skills 怎么测评不量化就不知道技能有没有用6.1 eval 先行的设计方式热词里有人问skills 怎么测评这个问题确实关键。我在开发每个技能时都会先写一份eval.md里面带上测试用例。拿 LaTeX 排版 skill 的 eval 举个例子用例编号输入样例期望输出验收标准E12000 字纯文字报告编译通过的 .tex无 undefined referenceE2含 5 个代码块的技术文档等宽字体代码块无 overfull boxE3含表格和交叉引用的草稿完整目录和引用label/ref 全部成对E4中文混排英文术语的正文中英文间有空格目测抽检 10 处均规范这些用例在写 skill 正文之前就定好等于先立验收标准再施工。没有验收标准的 skill 开发很容易陷入我觉得差不多行了的盲目自信。6.2 一套轻量评测方案完整做 skill 评测不一定需要重型 eval 框架我用的是轻量但有效的流程建一个临时目录把测试输入放进去让 agent 在干净会话中只凭 skill 完成全部任务然后按验收标准逐条打分。打分时我关注三个维度完成度是否产出目标文件编译是否通过。符合度是否遵守硬性规则可以写脚本自动检查一部分比如扫描 tex 文件里有没有禁用的宏包。稳定性同样输入跑三次输出差异大不大。差异过大说明规则还不够具体agent 在自由发挥。跑完一轮把结果写回 eval.md不达标的项就是下一轮迭代的重点。6.3 回归测试技能迭代最大的坑技能的迭代天然存在回归风险。我刚把排版技能升级到支持参考文献格式时曾经偷偷弄坏了表格样式的规则因为那次改动只改了参考文献部分没跑一遍旧的表格用例。等用户报告表格错乱我才发现回归问题。从那以后我每次修改 SKILL.md 或脚本都会完整重跑一遍 eval 用例集并记录每次运行结果。技能开发其实和软件开发一样需要把改坏了这件事尽早暴露出来而不是等上生产环境才后悔。如果你只为 agent 写了一个 skill没有配套测试那它只能算半个技能。7. 踩坑记录与个人经验7.1 描述写太长的后果我在 3.3 节提过描述要短这里再展开一个具体的反面案例。agent-skills 早期有一个结构图生成技能负责把文字描述转成流程图结构我最初把 description 写成了三行罗列了它支持的十几种图类型。结果在实际使用中用户说帮我梳理一下这个系统的模块关系agent 竟然优先加载了别的技能因为没有哪个技能的描述完全匹配。后来我把 description 改成一句将系统或流程的文字描述转换为结构图定义当用户要求画架构图、流程图、模块关系图时使用识别准确率立刻上来了。描述不是功能清单而是触发条件。7.2 别在技能里塞太多主观风格我在早期版本里写过类似排版风格要专业、大气、有高级感的规则结果不同会话产出的文档风格差异很大。模型对高级感的理解并不稳定今天可能给你加大留白明天可能给你上深色调。后来我把所有风格要求全部改写为可检查的硬性规则正文统一五号字标题用黑体加粗页边距固定 2.5cm。主观描述只会放大随机性客观规则才能带来稳定输出。7.3 第三方技能的安全意识现在网上能下到很多现成的 skill 包但我必须提醒一句不要无脑安装你不了解来源的技能。skill 本质上是一段会被 agent 执行的指令恶意技能可以诱导模型运行危险命令、读取本地敏感文件甚至把内容回传到指定服务器。安装前至少做两件事通读 SKILL.md 正文检查里面有没有要求 agent 执行可疑操作的内容检查 scripts 目录下的脚本看有没有网络请求、文件删除等敏感操作。另外不要把 API Key、密码等机密以明文形式存在技能仓库里即使仓库是私有的也应该用环境变量或密钥管理工具注入。安全是 skill 开发的底线不是加分项。7.4 我接下来会怎么扩展这个项目后续我打算做三件事一是把 skill 的公共部分抽取成共享模块比如编译检查和文件结构解析这两段逻辑在很多 skill 里都会用到避免各写各的二是给技能加版本号配合 eval 结果做发布记录升级时可对比前后版本的表现差异三是实验让一个 skill 在流程中自动调用另一个 skill比如排版技能需要生成结构图时自动加载结构图技能。这条路走通之后skill 就不再是孤立的指令包而是一张可以组合的能力网。做 agent-skills 这段时间我最大的体会是想让 agent 稳定地干活重点不是找更聪明的模型而是把经验沉淀成它随时能查的规范。模型的聪明是通用的你的业务规范是私有的skill 就是连接这两者的那座桥。每踩一个坑就把它写进对应技能的规则里你会眼看着 agent 越用越顺。
agent-skills：让AI Agent稳定掌握LaTeX排版等专业技能的实践指南
过去两个月我一直在做同一件有点反直觉的事情明明日常工作是写代码我却花了大把时间研究怎么让 AI agent 学会排版。起因很普通有一阵子我需要频繁把技术方案整理成带规范格式的 LaTeX 文档试过让 Claude Code、Codex 这类 agent 直接生成结果每次都差不多——第一版看起来有模有样细看全是问题包引用缺一个、英文与中文之间不加空格、编译警告一屏都放不下。最气人的是我在对话里反复强调的规则换一个新会话它又全忘了。后来我把这些散落在对话里的修正经验整理成了一个个独立的 skill放进一个叫 agent-skills 的项目里。所谓 skill就是一段结构化的作业指导书它包含了任务流程、规范细节、配套脚本和模板agent 在需要时按需加载而不是每次对话都背着几万字规则。这篇文章就围绕 agent-skills 这个项目说说 skill 到底是什么、和 agent、prompt、harness 的边界怎么划、一个合格的 skill 目录应该长什么样、怎么从零开发一个 LaTeX 排版 skill以及安装接入和测评那些容易翻车的细节。无论你是在研究 agent 开发还是想让自己的 coding agent 更听话这篇都值得看完。1. 为什么我会专门做一个 agent-skills 项目1.1 从一次让 agent 排版翻车说起先说那次让我下决心做 skill 项目的翻车经历。当时我给了 agent 一个很具体的任务把一份 Markdown 格式的周报转成 LaTeX要求用 ctex 支持中文、代码块用 listings 宏包、正文五号字、页边距 2.5cm。agent 答得很快几分钟就给了完整代码。我拿去编译报错信息直接打脸缺listings的颜色依赖中文注释出现乱码标题层级和目录对不上。我一条条回给它它修完这一处又弄坏那一处来回折腾了快四十分钟。真正让我崩溃的是第二天。换了一个新会话我把同样的要求发给 agent它又犯了同样的错误甚至把前一天我纠正过的约定全忘了。那一刻我突然意识到问题不在 agent 笨而在我没有给它一个稳定的知识载体。对话里的修正是一次性的模型本身又不会在两次会话之间记住我的偏好——我需要一种机制把怎么排版才算对沉淀下来让 agent 随时能查、能照着做。1.2 把一次性修正变成可复用能力包所以我开始研究市面上各家 agent 的 skills 机制。发现各大工具虽然叫法不同思路其实高度一致给 agent 准备一个目录目录里放SKILL.md作为入口文件里面写清楚这个技能什么时候用、完整流程是什么、有哪些硬性规则再配上脚本和模板做确定性补充。agent 在启动时会扫描这些目录但不会把所有内容塞进上下文只有判断任务匹配时才加载对应的那个 skill。这个设计解决了我之前最头疼的问题——上下文污染。skill 是按需翻开的手册不是每天都在耳边念的规矩。它和 prompt 最大的区别就在这里一份系统提示词无论多长都会全程占着上下文而 skill 平时只占一行描述的空间真正用到时才把几百行细节加载进来。对长会话来说这种差异几乎是决定性的。1.3 agent-skills 项目的定位最终我建了一个叫 agent-skills 的项目本质是一个 skill 合集目前收录了 LaTeX 排版、结构图生成、图片生成、旧项目现代化改造等十几个 skill。这个项目在组织上有三个原则可复用每个 skill 都是一份目录能复制到任何机器、任何项目不绑定某个特定会话。可测评每个 skill 都带一组测试用例和评分清单改了不会偷偷变差。可迭代技能描述、指令正文、脚本三者分开维护改其中一块不影响另外两块。如果你问我 agent 开发学习路线里最该先搞懂什么我的答案不是 RAG不是多智能体协作而是 skill。因为它是当前让 agent 真正上手干熟练活的最小单元几乎所有编码 agent 都在往这个方向收敛。2. 先捋清概念skill、agent、harness 和 prompt 各管哪一段2.1 一张表格看清四者的边界跟同行聊 skill 的时候发现很多人卡在概念上尤其分不清 harness 和 agent 的区别。我用一个比较生活化的类比来理解把整个 agent 系统想象成一个餐厅。概念类比职责例子harness餐厅的场地和厨房设备运行环境、工具调用框架、上下文管理Claude Code、Codex CLI、opencodeagent主厨理解任务、规划步骤、决定调用哪个工具模型 循环决策逻辑prompt门口的招牌和菜单一开始就告知的通用规则系统提示词、CLAUDE.mdskill后厨的作业指导书按需加载的专项流程与规范排版流程、代码审查清单harness 管的是怎么做agent 管的是做什么prompt 管的是默认怎么想skill 管的是具体活怎么干。四者配合缺一不可。很多人把 harness 当 agent是因为现在 Agent 这个词被用滥了——你买的其实是一套 harness 加上一个大模型agent 能力是它们组合出来的结果。2.2 为什么 skill 不能和 prompt 互相替代有一个很常见的疑问既然 prompt 也能写规则为什么还要 skill答案是代价不同。把规则写进 prompt意味着每条规则都要在每一轮对话中参与计算无论用不用得着。规则一多模型注意力会被稀释反而更容易忽略真正重要的约束。我之前试过把排版规范写进项目级 CLAUDE.md结果 agent 在无关任务里也会莫名其妙套用排版术语输出风格变得很奇怪。skill 走的完全是另一条路。它的描述信息非常短大致是这个技能负责什么、什么时候启用模型看到后先判断要不要用一旦判定匹配才把完整的 SKILL.md 正文加载进来。这种渐进式披露的思路和人类读书很像先看目录和摘要确定要看哪一章再翻到那一章细读。这也是为什么像 superpower skills 这样的技能包会流行它本质上是一堆组织良好的 skill让 agent 在各种专项场景下都能快速对齐一套高质量工作流。2.3 什么时候该写 skill什么时候不该写不是所有东西都值得做成 skill。我自己的判断标准是如果这个任务满足下面至少两条才值得写。任务有固定流程步骤基本不会变。输出格式有硬性要求错了就要返工。规则相对稳定不会三天两头推翻。判断标准可以写成检查表或者脚本。反过来探索开放型任务就不适合做成 skill。比如帮我想几个产品创意分析这份数据有什么规律这种任务没有标准流程硬塞一个 skill 反而限制模型的发挥。还有一次性的小任务也不值得写直接对话里解决就行否则维护成本比收益还高。3. SKILL.md 规范与目录结构一个 skill 的标准长什么样3.1 目录骨架与文件职责我在 agent-skills 项目里用的目录模板是这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── render.py │ └── check-env.sh ├── assets/ │ └── template.tex └── references/ └── latex-cheatsheet.mdSKILL.md是唯一必须存在的文件也是 agent 加载这个 skill 时的唯一入口。scripts/放可执行脚本用来做模型不擅长的确定性工作assets/放模板文件保证输出不会长出各种奇怪形状references/放参考资料正文里不需要展开的细节可以丢在这里让 agent 按需查阅。这个分层结构遵循一个核心原则指令负责告诉 agent 做什么脚本和模板负责保证做出来的东西是对的。3.2 frontmatter 字段逐个说SKILL.md顶部需要一段 YAML frontmatter定义这个 skill 的元信息。以我的 LaTeX 排版 skill 为例--- name: latex-typesetting description: 将 Markdown 或草稿转换为符合学术规范的 LaTeX 文档。当用户要求排版论文、报告或技术文档时使用。 license: MIT allowed-tools: bash, python ---name是唯一标识尽量简短用连字符而不是下划线。description是最关键的字段它是 agent 决定是否加载这个 skill 的唯一依据必须写清楚什么时候用而不是这个技能有多好。license字段对开源项目有意义标明版权。allowed-tools限定这个 skill 里脚本可以调用的工具集也是安全边界的一层控制。这些字段不是摆设我在下文会专门解释它们怎么在实际运行中起作用。3.3 progressive disclosure为什么描述必须短我在 agent-skills 项目早期犯过一个大错把description写成了半篇说明文什么这个技能能够帮助用户以高效、专业、美观的方式生成 LaTeX 文档支持多种中文字体和参考文献格式同时保持代码简洁可维护。写完我自己看着都累agent 更是一头雾水。后来我对照各家 skill 规范才想明白skill 的索引阶段模型只看得到description这一小段文字。它要从这段文字里判断这个任务要不要用这个技能就像检索系统靠摘要判断相关性一样。描述写得越长信息密度越低误判率越高。我踩过的最离谱的坑是一个排版 skill 的描述里提到了图片处理结果 agent 在用户请求压缩图片时加载了排版技能。从那以后我把描述压缩成一句话模板[能力对象] [适用场景] [触发条件]。3.4 脚本、模板和静态资源怎么组织SKILL.md 正文解决的是流程和规则但光有规则不够。规则写得再细模型编译文档时还是可能忘加参数即使没忘输出格式也可能和手写不一致。所以我在每个 skill 里都尽量配上脚本和模板把确定性部分从模型手里拿回来。比如 LaTeX 排版 skill 里有一个check-tex.py负责编译.tex文件并解析编译日志把 overfull box、undefined reference、missing character 这类警告分类输出。模型只需要运行这个脚本然后根据输出修正不再需要自己猜有没有问题。模板文件则规定了正文结构、宏包引用顺序、章节标题样式模型往里面填内容就行稳定性和效率都大幅提升。这个思路可以推广到任何 skill凡是能用代码确定判断的就不要交给模型自由发挥。4. 实操从零开发一个 LaTeX 排版 skill4.1 需求拆分什么任务适合做成 skill我以 LaTeX 排版为例完整演示一遍开发过程。首先做需求拆分。日常排版任务可以拆成这几步读取源稿Markdown 或纯文本识别标题层级和正文结构。套用学位论文或技术报告的 LaTeX 模板。处理中文支持ctex 宏包、中文字体、中文标点。按规范格式化参考文献。编译并检查警告迭代直到无致命错误。每一步都有明确的输入、输出和验收标准这是做成 skill 的理想形态。拆分完成后我先写一份测试用例而不是先写指令——后面讲到测评时再说为什么。4.2 编写主指令把排版规范拆成可执行动作接下来是 SKILL.md 的正文。我的写法是列出有序步骤每一步都说明操作对象和验证方式避免总之要规范这种空话# LaTeX 排版 ## 执行流程 1. 读取源稿识别标题层级、列表、代码块和引用。 2. 复制 assets/template.tex 为同名 .tex 文件。 3. 将源稿内容填入对应章节不要在文档中手写样式命令。 4. 代码块统一使用 listings 宏包配置见模板不要自行增删参数。 5. 运行 scripts/check-tex.py根据分类结果修正。 6. 出现 undefined reference 时检查 label 和 ref 是否成对而不是新增宏包。 ## 硬性规则 - 中文与英文/数字之间加空格中文标点前后不加空格。 - 目录使用 \tableofcontents不用手工排版目录。 - 禁用 hyperref 默认蓝色链接样式按模板配置改为黑色。注意第 6 条这条来自我的真实教训模型遇到编译错误的第一反应往往是缺包于是乱加宏包反而引发更多问题。把正确动作写死在规则里比让模型自由判断靠谱得多。4.3 配套脚本与模板补全 agent 不具备的确定性模板文件的骨架我抽几条关键配置说明\documentclass[12pt]{ctexart} \usepackage[margin2.5cm]{geometry} \usepackage{listings} \usepackage{xcolor} \usepackage[hidelinks]{hyperref} \lstset{ basicstyle\ttfamily\small, framesingle, breaklinestrue }这些配置不是随便定的。hidelinks是为了满足链接不要带彩色边框的常见要求breaklinestrue是为了避免长代码行溢出页面。把这些写死在模板里agent 就不会每次自由发挥。脚本部分的核心是解析编译日志我会在脚本里把警告分成 error、warning、info 三级并给每条 warning 附上修正建议这样 agent 拿到的是可直接处理的结构化数据而不是一堆难懂的原生日志。4.4 本地验证用真实文档跑一遍写完 SKILL.md、模板和脚本后最重要的一步是本地验证。我会准备三份不同风格的源稿一份带大量代码块的技术文档、一份纯文字报告、一份带数学公式的草稿然后新建一个干净会话只给 agent 一个任务按技能说明完成排版。验证时我不手把手纠正就让 agent 自己读材料、自己调用脚本并迭代。任何需要我中途介入解释的地方都说明 SKILL.md 写得不到位回去补。这样跑三轮之后我通常会发现两个问题一是描述写得还不够精准agent 一开始没识别出该用这个技能二是某条规则覆盖不到特殊场景。修完再跑直到三轮无人工介入顺利通过。这个流程特别像给新员工做上岗培训只不过我的新员工每次都是失忆的所以我必须把所有知识都写到手册里。5. 安装、接入与多端适配Claude Code、Codex、opencode 的差异5.1 三种常见的安装路径skill 开发完接下来是安装。目前主流 agent 的安装方式大体有三种用户级全局目录放在~/.claude/skills或~/.codex/skills这样的路径下对当前用户的所有项目生效。项目级目录放在项目仓库内的.claude/skills或.codex/skills目录随代码库一起提交团队成员自动共享。第三方技能包安装从网上下载别人打包好的 skill 仓库然后复制或软链接到上述目录。我的 agent-skills 项目采用第三种方式管理所有技能维护在一个 git 仓库每个技能一个子目录另外提供一个install.sh脚本根据参数把指定技能软链到各 agent 的全局技能目录里。这样同一个仓库可以同时服务 Claude Code、Codex 和 opencode因为它们都认SKILL.md这个入口文件差别只在目录路径。5.2 全局还是项目级怎么选选择安装层级我建议按这个标准判断场景推荐层级原因个人写作、日常排版偏好用户级全局所有项目都能用不影响团队团队代码规范、统一提交信息项目级进 git所有人默认加载公司级安全审查、合规流程项目级 代码评审可审计、可回溯实验性技能、还没调稳先不装本地测试避免污染工作环境需要特别提醒的是项目级 skill 一旦进 git所有协作成员都会被影响。所以我的建议是未经过测评的技能不要进入团队共享目录。我在 1.3 节强调可测评原则就是这个原因。5.3 多 agent 共用一个 skill 仓库的实践不同 agent 对 skills 目录的识别规则略有差异但我的兼容策略很简单在 install 脚本里做一层映射。脚本维护一个表格把每个 agent 的 skills 根目录列出来然后逐个创建软链接。实际使用的代码逻辑大致是#!/usr/bin/env bash # install.sh —— 把 agent-skills 里的指定技能软链到各 agent 目录 SKILL_NAME$1 AGENT_DIRS( $HOME/.claude/skills $HOME/.codex/skills $HOME/.config/opencode/skills ) for dir in ${AGENT_DIRS[]}; do mkdir -p $dir ln -sfn $(pwd)/skills/$SKILL_NAME $dir/$SKILL_NAME done这样我改一次技能内容所有 agent 下次启动时都能加载到最新版本。注意软链接在 Windows 上可能需要管理员权限跨平台使用时建议改成复制命令或者在安装脚本里做一次平台判断。5.4 接入后常见报错与排查接入过程中最常遇到的报错是 agent execution terminated due to error这个错误提示看起来吓人但通常原因不复杂我列一张排查清单技能目录里脚本退出码非 0检查scripts/下脚本能否在终端独立运行。description里提到了不存在的文件路径agent 加载后找不到文件直接中断。allowed-tools限制过严脚本需要 bash 但清单里只写了 python工具调用被拒。软链接失效仓库目录移动后链接变成断链agent 扫描时读到空目录。技能内部引用了相对路径但 agent 的工作目录不在技能目录下。遇到报错我第一件事永远是看完整日志栈而不是盲目改技能内容。绝大多数情况下把日志里最后几步操作还原出来问题就一目了然了。6. skills 怎么测评不量化就不知道技能有没有用6.1 eval 先行的设计方式热词里有人问skills 怎么测评这个问题确实关键。我在开发每个技能时都会先写一份eval.md里面带上测试用例。拿 LaTeX 排版 skill 的 eval 举个例子用例编号输入样例期望输出验收标准E12000 字纯文字报告编译通过的 .tex无 undefined referenceE2含 5 个代码块的技术文档等宽字体代码块无 overfull boxE3含表格和交叉引用的草稿完整目录和引用label/ref 全部成对E4中文混排英文术语的正文中英文间有空格目测抽检 10 处均规范这些用例在写 skill 正文之前就定好等于先立验收标准再施工。没有验收标准的 skill 开发很容易陷入我觉得差不多行了的盲目自信。6.2 一套轻量评测方案完整做 skill 评测不一定需要重型 eval 框架我用的是轻量但有效的流程建一个临时目录把测试输入放进去让 agent 在干净会话中只凭 skill 完成全部任务然后按验收标准逐条打分。打分时我关注三个维度完成度是否产出目标文件编译是否通过。符合度是否遵守硬性规则可以写脚本自动检查一部分比如扫描 tex 文件里有没有禁用的宏包。稳定性同样输入跑三次输出差异大不大。差异过大说明规则还不够具体agent 在自由发挥。跑完一轮把结果写回 eval.md不达标的项就是下一轮迭代的重点。6.3 回归测试技能迭代最大的坑技能的迭代天然存在回归风险。我刚把排版技能升级到支持参考文献格式时曾经偷偷弄坏了表格样式的规则因为那次改动只改了参考文献部分没跑一遍旧的表格用例。等用户报告表格错乱我才发现回归问题。从那以后我每次修改 SKILL.md 或脚本都会完整重跑一遍 eval 用例集并记录每次运行结果。技能开发其实和软件开发一样需要把改坏了这件事尽早暴露出来而不是等上生产环境才后悔。如果你只为 agent 写了一个 skill没有配套测试那它只能算半个技能。7. 踩坑记录与个人经验7.1 描述写太长的后果我在 3.3 节提过描述要短这里再展开一个具体的反面案例。agent-skills 早期有一个结构图生成技能负责把文字描述转成流程图结构我最初把 description 写成了三行罗列了它支持的十几种图类型。结果在实际使用中用户说帮我梳理一下这个系统的模块关系agent 竟然优先加载了别的技能因为没有哪个技能的描述完全匹配。后来我把 description 改成一句将系统或流程的文字描述转换为结构图定义当用户要求画架构图、流程图、模块关系图时使用识别准确率立刻上来了。描述不是功能清单而是触发条件。7.2 别在技能里塞太多主观风格我在早期版本里写过类似排版风格要专业、大气、有高级感的规则结果不同会话产出的文档风格差异很大。模型对高级感的理解并不稳定今天可能给你加大留白明天可能给你上深色调。后来我把所有风格要求全部改写为可检查的硬性规则正文统一五号字标题用黑体加粗页边距固定 2.5cm。主观描述只会放大随机性客观规则才能带来稳定输出。7.3 第三方技能的安全意识现在网上能下到很多现成的 skill 包但我必须提醒一句不要无脑安装你不了解来源的技能。skill 本质上是一段会被 agent 执行的指令恶意技能可以诱导模型运行危险命令、读取本地敏感文件甚至把内容回传到指定服务器。安装前至少做两件事通读 SKILL.md 正文检查里面有没有要求 agent 执行可疑操作的内容检查 scripts 目录下的脚本看有没有网络请求、文件删除等敏感操作。另外不要把 API Key、密码等机密以明文形式存在技能仓库里即使仓库是私有的也应该用环境变量或密钥管理工具注入。安全是 skill 开发的底线不是加分项。7.4 我接下来会怎么扩展这个项目后续我打算做三件事一是把 skill 的公共部分抽取成共享模块比如编译检查和文件结构解析这两段逻辑在很多 skill 里都会用到避免各写各的二是给技能加版本号配合 eval 结果做发布记录升级时可对比前后版本的表现差异三是实验让一个 skill 在流程中自动调用另一个 skill比如排版技能需要生成结构图时自动加载结构图技能。这条路走通之后skill 就不再是孤立的指令包而是一张可以组合的能力网。做 agent-skills 这段时间我最大的体会是想让 agent 稳定地干活重点不是找更聪明的模型而是把经验沉淀成它随时能查的规范。模型的聪明是通用的你的业务规范是私有的skill 就是连接这两者的那座桥。每踩一个坑就把它写进对应技能的规则里你会眼看着 agent 越用越顺。