上个月我把一个 Markdown 批量转 LaTeX 的排版任务交给 Claude Code 做第一次老老实实把转换规则、字体设置、表格规范、参考文献格式一条条写进对话里来回改了五轮才勉强能看。后来我把这套规则整理成一个 skill 放到~/.claude/skills/下同一个任务重新跑第一遍输出就基本可用。这不是模型突然变聪明了而是 agent 拿到了结构化的技能描述之后知道每一步该查什么、该注意什么、该调用什么模板。那次之后我花了大量时间研究 Agent Skills也把 GitHub 上热门的 skills 仓库基本翻了一遍。这篇文章把我对 skills 的理解、实操过程、踩过的坑一次性讲透内容包括skills 和 prompt、tool、agent、harness 到底什么关系怎么从零开发一个 skillsClaude Code、Codex 以及其他 agent 框架里 skills 的安装差异以及怎么量化评估一个 skills 的好坏。如果你正准备开发或挑选 skills这篇文章可以给你一条直接上手的路线而不是泛泛的概念介绍。1. Skills 补的是上下文管理这块短板1.1 长提示词为什么会让 agent 越用越笨很多人对 skills 的第一反应是这不就是把 prompt 拆成文件吗我一开始也这么想直到实际对比了两条路线才明白问题没那么简单。早期我习惯把任务规则一股脑写进 system prompt比如“你是排版助手处理中文时使用 ctexart 文档类表格用 booktabs图片用 graphicx参考文献用 biblatex代码块用 listings……”规则越写越长效果却开始下降。模型确实能“读到”这些内容但注意力是有限的当规则数量超过一定阈值核心指令会被边缘化模型反而开始在一些简单决策上犯低级错误。这就像让一个新人第一天上班就把 500 页操作手册背下来再让他去处理具体任务他大概率会在无关章节里打转。Skills 的思路完全不同不给 agent 塞完整手册而是让它在遇到对应场景时自己去翻那一章。这样每次对话占用的上下文更少指令也更聚焦。从成本角度看差距也很直观。一个 3 万 token 的 system prompt 每轮对话都要重新计费如果用户只是在做一个很小的任务大部分 token 可能都浪费在不断重复的环境描述上。而 skill 机制下模型只有在确认任务匹配时才加载对应文件加载完还只保留与当前子任务相关的片段上下文占用能直接砍掉一个量级。1.2 Skill、Prompt、Tool、Agent、Harness 的概念边界我在社区里看到很多人把 skill 和 prompt、tool、agent 混着用尤其在“skill 和 agent 的区别”这类讨论下答案经常说不清。这里我用一个工程上的分工来拆解。Prompt是一次会话内的指令文本静态、一次性、跟具体对话绑定。你写一段指令让模型执行某个任务这段指令就是 prompt。它的优点是零成本缺点是不可复用换个场景又要重写。Skill是结构化的可复用知识单元通常是一个文件夹加一份SKILL.md按需被 agent 加载。它解决的是“agent 遇到某类任务时应该遵循什么方法、注意什么坑、调用什么资源”的问题。它和 prompt 最大的区别在于prompt 是被动塞进上下文的skill 是 agent 根据用户请求主动去查的。Tool是 agent 可以调用的外部能力接口比如文件读写、网页搜索、执行代码。它解决的是“agent 能做哪些动作”的问题。一个有代表性的区别是skill 教 agent“怎么做”tool 替 agent“做”。skill 本身不执行任何外部操作它只是知识tool 才是真正动手的那层。Agent是具备感知、规划、决策、调用工具能力的执行主体。它可以被理解为“大脑 手”大脑负责推理手负责执行。Harness是承载 agent 运行的框架/环境负责管理模型循环、工具调用、上下文压缩。Claude Code、Codex CLI 都属于 harness 层。同一份 skill 在不同 harness 里的加载细节可能有差异但设计思路是通用的。用一个类比来串起来harness 是工作台agent 是工人tool 是工人手里的电动工具prompt 是客户贴在工作台上的便签而 skill 是工人自己的操作手册。客户换了一张便签手册不用重写换了一个工人手册也还能用。这就是为什么 skills 正在成为 agent 生态里的“知识中间件”。1.3 渐进式披露Skills 在设计上解决什么问题Skills 背后最关键的设计思想是渐进式披露progressive disclosure。这个词听起来玄其实做开发的都见过一个程序不会启动时把所有模块全部加载进内存而是调用到时才加载对应的模块。Skills 把这种思路搬到了 agent 的知识管理上。一个典型 skill 文件夹里SKILL.md只保留核心信息这个技能是干什么的、什么时候用、大概的步骤是什么。而具体到某个复杂子环节的细节比如“Markdown 里 20 种表格写法分别怎么转成 LaTeX”放在references/子目录下。agent 先用 description 判断当前任务是否需要这个 skill如果需要先读SKILL.md执行过程中遇到某个具体细节问题再去 references 里找对应文件。这避免了“为了处理一个问题被迫加载整个领域的全部知识”的浪费。我实测过一个场景只加载SKILL.md时一次任务大约多消耗 2-3k token如果把完整版手册一次性塞进去光规则部分就要 15k 以上。对于一次会话只有几个任务的场景差别不大但如果同一会话内连续做 10 个任务那个差距会被放大到不可忽略。这个机制还有一个隐藏好处作者可以把大量注意事项、反面案例放进 references 里。模型平时看不到这些只有在正好踩到相关环节时才看到既不影响常规任务的执行速度又能在关键时刻提供兜底。2. 手写一个 LaTeX 排版 Skills 的完整过程2.1 需求拆解与目录结构设计开发 skills 的第一步不是急着写 markdown而是拆需求。我以latex-typesetting为例目标很明确当用户要求把 Markdown 文档转为 LaTeX 或者帮忙排版毕业论文、期刊论文时agent 能直接产出一个结构规范、可编译的.tex文件。我把任务拆成了五个子问题中文环境用什么文档类和字体ctexart、ctexbook、ctexrep标题、章节、段落之间如何映射图表、表格、代码块分别用什么宏包和写法数学公式的特例处理特殊命令、对齐环境参考文献用什么方案biblatex 还是 thebibliography最终目录长这样latex-typesetting/ ├── SKILL.md ├── references/ │ ├── markdown-to-latex-mapping.md │ ├── chinese-font-setup.md │ └── math-formula-cheatsheet.md └── examples/ └── paper-sample.tex这里有个设计原则值得反复强调SKILL.md要短references 要深。我的SKILL.md控制在 100 行以内只写主干流程和最容易犯的错误具体映射表、宏包选型、矩阵公式写法全部下沉到 references。这样 agent 在读主文档时不会迷失遇到细节问题时又能精确查表。2.2 SKILL.md frontmatterdescription 决定了 80% 的成败SKILL.md的 YAML frontmatter 是整个 skill 的入口尤其是description字段它直接决定 agent 会不会在正确的时机加载这个 skill。我见过太多人把 description 写成一句毫无区分度的“用于处理文档排版”结果 agent 在写代码、写邮件、总结纪要时都尝试加载它导致输出行为漂移token 也白白浪费。正确的 description 应该同时包含触发条件和排除条件。照着这个思路写效果好得多--- name: latex-typesetting description: - Use when the user requests LaTeX document generation or Markdown to LaTeX conversion, including academic papers, theses, resumes, and reports. Not for documents that only need plain text or PDF output without LaTeX. Use for tasks involving ctex, bibtex, or writing compilable .tex files. ---注意我的写法前面用“Use when”明确指出适用场景后面用“Not for”把边界划清。agent 的意图分类模型对这种正反例描述非常敏感排除条件能显著降低误触发率。fontmatter 还可以加其他元信息比如allowed-tools、version、metadata不过初始阶段这两个字段就够用了。2.3 正文怎么组织规则、流程、示例、禁区接下来是SKILL.md的正文。我建议按四个板块来写核心规则、标准工作流、常见示例、明确禁区。核心规则部分我会强调“必须使用 ctexart 处理中文文档”“所有浮动体必须有 label 和 caption”“表格一律使用 booktabs 风格”这类硬性要求。标准工作流则是给 agent 一个稳定的执行顺序先分析文档结构 - 确定文档类 - 准备宏包 - 分章节转换 - 检查特殊符号 - 输出可编译文件。常见示例不是给完整代码而是给“结构示例”比如一个最小可用模板长什么样每个区块的顺序是什么。这样 agent 在不确定时能对着框架自我检查。明确禁区我写了三条不要在导言区堆砌不需要的宏包、不要直接复制在线 OCR 的乱码公式、不要忽略中文引号与 LaTeX 引号的区别。references 里的映射表则追求细和全。比如 Markdown 的对应 LaTeX 的\begin{figure}[htbp] ... \caption{alt} ...表格横线对应\toprule、\midrule、\bottomrule。这些细节如果全写进 SKILL.md主文档会变得又臭又长放在 references 里反而能按需调用。2.4 测试与调优靠日志确认加载写完 skill 之后不能直接上生产先做本地验证。我把latex-typesetting放进~/.claude/skills/后新开一个会话输入一句“把这份 Markdown 转成 LaTeX 论文”然后打开调试日志观察 agent 是否在第一步就加载了 skill。调试日志里如果能找到类似Read skill file: latex-typesetting/SKILL.md的记录说明触发正常。如果日志里完全没有出现 skill 加载记录大概率是 description 写得不够清晰agent 没识别出该用哪个技能。这时候我就去调整 description反复测试两三轮才稳定。我也建议准备一组边界测试用例比如用户只说要“把这段文字加粗”agent 不应该加载 latex skill用户说“写一份中文毕业论文模板”agent 必须加载。把这两类用例跑通过才能进入真实场景。别小看这一步很多社区下载的 skill 之所以“时灵时不灵”基本都是在触发阶段就没做好。3. 主流工具里的 Skills 生态安装方式与机制差异3.1 Claude Code官方支持最顺滑Claude Code 是目前对 skills 支持最完整的工具之一。它的加载目录分两层个人级目录~/.claude/skills/和项目级目录.claude/skills/。个人级的技能对所有项目可见适合放通用能力项目级的技能绑定特定代码库适合放领域专属的转换规则、代码风格、测试流程。安装方式非常简单把 skill 文件夹直接复制到对应目录即可# 个人级 cp -r latex-typesetting ~/.claude/skills/ # 项目级 cp -r latex-typesetting /path/to/project/.claude/skills/然后在 Claude Code 会话里执行/skills命令就能看到当前 available 的技能列表。如果列表里出现了你刚放进去的文件夹名说明加载成功。官方还给了“通过对话直接创建 skill”的入口可以让 agent 根据你的历史操作自动生成 SKILL.md这适合先跑通一个粗糙原型再手动优化。3.2 Codex、Opencode、AgentScope 等其他选择Codex 也在做技能机制。从社区反馈看它的思路和 Claude Code 类似都是通过描述驱动的动态加载。opencode这类开源 harness 对 skill 的实现差异更大一些部分版本要求把 skill 配置写在特定 JSON 里部分版本直接读取SKILL.md所以安装前一定要看具体项目的 README不要想当然。AgentScope 的 skills demo 则偏研究性质通常用来演示多 agent 协作场景中如何共享技能。它们的竞品研究意义大于生产意义如果你在做一个学术原型可以参考如果你要上线生产环境建议选社区活跃度高、文档完整的 harness。还有一个经常被忽略的点不同 harness 对“skill 加载后是否持久保留”的处理不一样。Claude Code 在一次会话中skill 内容一旦加载会保留一段时间有些轻量框架则每个循环都重新判断可能会导致同一个技能被反复加载、反复丢弃既浪费又容易遗漏。3.3 社区包Superpower Skills 等要不要装以 Superpower Skills 为代表的社区整合包在热搜里出现频率很高它把一系列技能打包到一个仓库里比如生成图表的 skill、SPR 写作的 skill、自动构建技能的 skill安装一次就能获得一整套能力。我的态度是可以装但别做“技能囤积症”。我见过有人一口气装了几十个社区 skill结果遇到最简单的画图任务agent 开始纠结到底加载“text-improvement”还是“visual-chart”反而降低了效率。社区包适合作为灵感库用了之后把其中真正高频的那几个摘出来单独维护成自己的技能集。另外安装任何社区包之前先做一次代码审查。Skill 内容是纯文本不直接执行代码但它可能会引导 agent 去执行特定命令比如自动修改文件、拉取资源等。如果 skill 里包含指向不明确网址的下载命令建议先手动看一遍内容再决定用不用。这和装第三方 npm 包是一个道理。下面这张表总结了我常用的几个工具的 skill 支持情况方便你按需选择工具/框架skill 目录个人/项目级安装复杂度备注Claude Code~/.claude/skills/、.claude/skills/都支持极低社区最活跃文档最全Codex内置 自定义目录项目级为主低偏代码任务技能粒度较细opencode配置驱动项目级中等需要读文档确认格式AgentScopedemo 型不固定较高研究向偏 agent 协同Pi Agent / Hermes Agent各家不一不固定中高新项目迭代快状态不稳定4. Skills 测评用可复现的指标代替“感觉好用”4.1 五个核心指标很多人在社区里问“skills 怎么测评”但回答大多停留在“我用了之后效果不错”这种体验式描述。要真正评估一个 skill 的价值我建议至少看五个指标。触发率该触发时agent 是否在第一次尝试时就正确加载了 skill。我通常会准备 15 个“该用”的场景和 10 个“不该用”的场景逐个记录加载行为。理想状态是该用 15/15 触发、不该用 0/10 误触。触发率低先改 description误触率高也要改 description因为边界写得太模糊。完成质量同一任务在无 skill 与有 skill 条件下各跑一次对比产出物的可用程度。质量怎么比以 LaTeX 任务为例我会检查是否编译通过、是否使用规范宏包、是否有中文乱码、格式是否符合期刊模板。用 1-5 分打分取多次运行的平均分。Token 开销加载 skill 带来的额外 token 消耗。准确做法是记录使用 skill 会话的总 token对比同等任务不用 skill 的总 token。一般控制在 20% 以内比较健康如果超过 40%说明 SKILL.md 写得过于冗余或者引用文件被过早加载。负向干扰在不该触发这个 skill 的任务上agent 的行为是否被污染。比如装了一个“邮件助手” skill 后agent 写代码时也开始用邮件客套语这就是典型的负向干扰。稳定性同一个任务连续跑 5 次成功/失败的比例。好的 skill 应该让结果稳定在“基本靠谱”而不是一次惊艳四次翻车。稳定性差通常意味着工作流描述不够具体留给模型自由发挥的空间太大。4.2 一个可照抄的评测流程我自己的评测流程分三步。第一步准备三类数据集golden set应该触发的任务、negative set不应该触发的任务、quality set用于对比完成质量的任务。第二步用脚本自动化跑多轮记录加载日志和输出结果。第三步人工或者用另一个 LLM 给输出打分汇总。如果你不想写脚本可以用一个笨办法开两个窗口一个带着 skill一个不带同一个任务各跑两遍然后对照输出。虽然手动但至少比“感觉变好了”要客观。如果你想自动化一点这里给一个思路#!/usr/bin/env bash # 简单评测对同一任务带与不带 skill 各跑 N 次 TASK把这份 Markdown 转成 LaTeX 中文论文 for i in 1 2 3; do # 不带 skill 的会话 claude -p $TASK --disable-skills no_skill_$i.txt # 带 skill 的会话 claude -p $TASK with_skill_$i.txt done然后把输出文件分别拿去编译统计编译通过率、人工评分、输出长度。两次结果一对比skill 的价值就能量化。--disable-skills这个参数不同工具写法可能不一样以你实际使用的 harness 文档为准。4.3 评测时容易忽略的细节有几个细节是我踩过坑之后才注意到的值得单独提醒。第一评测一定要在独立会话里进行。如果你在同一个会话里既测试了技能、又接着做其他任务agent 的状态已经被污染后续结果不能作为判断依据。每次评测都新开会话保证 agent 的初始状态一致。第二temperature 参数要固定。如果工具允许配置推理温度评测时保持同一个值否则结果波动可能是采样随机性导致的跟 skill 本身无关。第三LLM 作为评分器的稳定性有限。我试过用 GPT 给 LaTeX 输出质量打分它在第 1 次和第 5 次可能给出相差很大的分数。一个缓解办法是固定评分 prompt、固定输出格式比如只输出 JSON多次评分取平均或者把关键检查点变成“是否通过”的布尔项减少主观判断空间。5. 实际踩坑与沉淀出的开发原则5.1 四个典型坑第一个坑是 description 写得太宽泛。我以前写过一个“doc-converter”技能description 只写了“Use when the user wants to convert documents.”结果 agent 把代码注释转换也算成文档转换几乎每次都尝试加载反而干扰了主任务。改成限定格式Markdown/Word/LaTeX/HTML并在排除条件里写明“不适用于代码文件”之后误触率立刻降了下来。第二个坑是 SKILL.md 里塞了一堆细节导致渐进式披露失效。写过一版包含 300 行规则的技能每次加载都占 8k token效果还不稳定。后来把内容拆成“主路径 references”结构后主文档只留 60 行需要细节时再查既省 token 又提升准确率。第三个坑是模板文件使用绝对路径。我在 skill 里引用了一个本机模板换电脑之后 agents 直接路径找不到任务中断。把模板文件放到 skill 目录内、用相对路径引用后整个 skill 就变成了可以复制迁移的单元。这其实也提醒我skills 应该是自包含的。第四个坑是过度结构化。有的 skill 把规则写得像法律条文给所有决策都预设了路径agent 反而失去了灵活处理的能力。比如我在 image-generation skill 里规定“所有图片必须用 16:9 比例”结果用户要 1:1 头像时 agent 还在死守 16:9。技能应该有规则但也应该保留“当用户明确要求时以用户为准”的兜底。5.2 三条写 skills 的铁律第一一个 skill 只解决一类问题。不要造“万能技能”也不要因为某个技能内部能扩成多个函数就把所有内容塞进同一个文件夹。单一职责不仅让触发判断更清晰也让维护变得容易。第二编写时多写“为什么不”。规则里多写一句“不要用 X因为 Y 会在中文编译时报错”比单纯写“不要用 X”有效得多。模型理解了背后的原因后在新情境下能举一反三。第三技能的自我评估要写进去。在 SKILL.md 末尾加一段“自查清单”要求 agent 在任务完成前检查是否满足这些项比如“输出文件是否可编译”“是否包含必需的前言”“引用是否完整”。这个做法的本质是给 agent 提供一个完成信号它能显著降低输出“半成品”的概率。5.3 Skills 和 Agent 生态接下来会怎么走从我观察到的社区动态和开发趋势看Skills 正在从“Claude Code 独有的小功能”走向 agent 领域的通用层。最明显的变化是跨工具标准化。SKILL.md加 references 的目录结构已经被越来越多框架接受“一个 skill 在 Claude Code、Codex、opencode 之间迁移”正在成为可能。对开发者来说这是好事意味着技能资产不会被锁在一家工具里。第二个方向是 skills 与 agent 记忆结合。现在的 skill 本质上是“静态知识”不会随使用动态进化但如果把记忆模块接入技能系统让 agent 在多次执行后自动修订 SKILL.md 里的规则技能就变成了“活文档”。这会对 agent 架构的长尾场景很有帮助。第三个方向是图像生成、结构图这类多模态 skills 的成熟。热搜里已经频频出现“图片生成 skills 安装包”“结构图 skills”说明技能不只是文字指令还可以跟多模态能力绑定。比如一个“结构图 skills”可以规定用什么示意图语法、节点配色规则、布局方向、图注格式然后调用生成工具把描述转成图片。这类技能很有潜力因为它们的知识结构比纯文本任务更稳定更容易被标准化。同时agent 安全也开始和 skills 产生交集。一个经过审查的 skill 可以作为安全行为准则的载体告诉 agent“哪些操作需要用户确认、哪些路径不允许访问、哪些命令需要在沙箱中执行”。反过来恶意的 skill 也可能诱导 agent 执行危险操作。这和社区包被滥用的风险一样需要交付前做内容检查而不是盲目信任来源。最后一个建议meter 一下你到底需不需要它写了这么多最后分享一点个人体会。我在折腾 skills 的过程中最大的收获不是做出了某个堪称完美的技能包而是搞清楚了什么时候不需要 skills。如果你只是偶尔让 agent 写一段翻译、做一次代码 review普通 prompt 就够了没必要为了“结构感”强行造一个技能目录。技能最大的价值出现在三种情况任务流程复杂且重复执行、错误代价高需要系统性规避、或者知识本身具有领域深度难以用一句话讲清。反过来说如果你发现自己经常把同一段指令反复粘贴给 agent或者每次开新会话都要解释一遍繁琐的约束条件那就是该把它沉淀成 skill 的信号。这个沉淀过程本身也会逼着你把那些模棱两可的隐性知识翻译成显性规则这对个人能力提升的收益甚至比 skill 本身还大。我现在的做法是每写完一个 skill都顺手在 SKILL.md 末尾加一段变更记录。将来某天 agent 生态继续演进这堆文件就是你为自己的工作流建的知识库。起点不高从整理第一条常用规则开始就够了。