Agent Skills实战指南：从提示词封装到稳定输出

说件近期让我挺有感触的事：以前让AI帮我改前端代码，每次都要在对话里重新粘贴一大段“你要遵守的规则”，它开头几条还能记住，到后面就开始自由发挥。后来我把这些规则整理成一个agent-skills技能包，让agent在对应场景下主动调用，效果完全不一样——输出稳定、格式统一、连我习惯的注释风格都能保持住。这篇文章就围绕agent-skills这个主题，把我这半年在Claude Code、Codex、opencode上折腾skills的经验、踩过的坑，以及从0写一个skill的全过程，完整捋一遍。不管你是刚接触agent的初学者，还是已经在做agent开发的老手，应该都能找到能直接拿走用的东西。

1. agent-skills到底是什么：先把它和prompt、agent、harness的关系理清楚

1.1 一个让我决定研究skill的“翻车现场”

上个月我接了个小项目，要用agent自动整理会议纪要并生成日报。我在系统提示词里写了两百多行格式规范：日期格式、标题层级、谁负责什么字段、用词风格……实际跑起来，模型前两轮输出完全正常，到第三条记录时日期格式突然变成“2025年6月3日”，第四条又开始自己加“总结与展望”。我一度以为是模型理解能力不行，后来才发现问题不在模型，而在我的组织方式——我把规则和任务混在了一段上下文里，模型每轮都要在很长的上下文里翻找规则，很容易“遗忘”。

这其实是很多agent项目的通病。也就在那个时候，我开始认真研究agent-skills：与其在对话里反复强调规则，不如把规则封装为一份结构化的技能说明书，由agent在合适的时机自动加载执行。后来结果也证明这条路是对的。同一个模型、同一个任务，用skill包之后，连续跑了十轮格式都没有再跑偏。

1.2 skill、agent、harness：三个容易混的概念

很多人分不清skill、agent和harness，我在这里用大白话拆一下。

• Agent ：一个能感知、决策、行动的智能体。它接收任务、决定调用什么工具、怎么推进步骤，是“做决定的头脑”。
• Harness ：Agent的运行时框架，也叫“脚手架”。它负责跟模型API交互、管理上下文窗口、解析工具调用的返回结果、处理权限和错误。可以理解成“给agent用的工作台”。
• Skill ：封装好的专业技能模块。它包含一份操作手册（通常是SKILL.md）以及可能附带的脚本、模板、校验工具，描述“某类任务应该按什么流程做”。

用一个类比：Agent是项目经理，Harness是他的办公室和电脑，Skill是他手里的标准作业手册。项目经理碰到不熟悉的任务时，打开手册按流程执行，而不是临场瞎编。

理解这个区别之后，再看“agent框架与编排”就好办了：harness负责基础编排（模型调用、工具调度、权限控制），skill负责专业领域内具体任务的执行逻辑，两者加起来，才是一个能真正干活的agent系统。

1.3 一个标准skill包内部到底装了什么

常见的skill包目录结构大致如下，以我常用的LaTeX排版技能为例：

latex-skill/
├── SKILL.md
├── templates/
│   ├── ieee_conf.tex
│   └── cn_journal.tex
├── scripts/
│   ├── check_tex.py
│   └── convert_md.py
└── examples/
    └── output_example.tex

核心文件是SKILL.md，它由两部分组成：YAML格式的元信息（name、description等）和Markdown格式的步骤正文。元信息负责让agent“知道该在什么时候用我”，步骤正文负责“告诉我具体怎么做”。templates、scripts是给正文引用的辅助材料，用来提升输出质量。

和普通prompt最大的区别在于：prompt是一次性输入的文本，SKILL.md是独立存在的知识资产。它可以被git版本管理，可以在不同项目间复用，甚至可以被其他开发者下载安装。这是agent-skills最有价值的地方——经验不再是一段“用完就丢”的对话，而是一份能不断迭代的技能包。顺手再提一句容易混淆的点：skill不等于记忆。agent记忆是“当前状态和历史偏好”的动态信息，比如用户喜欢把日期写成年月日；skill是“怎么做”的程序化知识，比如如何把论文排版成IEEE模板。两者互相配合，才是一个既懂用户又懂行的agent。

2. 主流框架的skills机制：从Claude Code到Codex再到opencode

我用的工具比较多，从Claude Code到Codex再到opencode，各家skills的实现思路大同小异，但细节差异很大。这里把常用路径整理出来。

2.1 Claude Code的skills：目录就是岗位，description就是触发词

Claude Code把skills放在 .claude/skills/<技能名>/SKILL.md 。项目级放项目目录里的 .claude/skills ，用户级放 ~/.claude/skills 。路径里那个目录名就是技能名（比如latex-format），但真正决定触发时机的是SKILL.md里的description字段。

这里有个细节特别容易踩坑：description写得越具体，模型越容易在正确时机加载。如果你写“处理LaTeX相关任务”，模型可能在任何一次提到LaTeX的时候都调用它；如果你写“仅当输入的Markdown学术草稿需要输出为可编译的IEEE模板.tex文件时使用”，触发精度就高很多。新版本Claude Code还在SKILL.md里支持声明依赖脚本、限制权限等级等高级功能，具体以官方文档为准，但核心原理都是“元信息驱动触发”。

2.2 Codex的AGENTS.md思路：把技能写进“员工手册”

Codex（OpenAI的编码agent）走的是AGENTS.md路线。可以把AGENTS.md理解成一份项目级或用户级的“员工手册”，里面写的规则、技能、指南，都会被agent在相应场景自动参考。和Claude Code的SKILL.md相比，AGENTS.md的“手册感”更强，更适合写项目约定（比如“前端项目必须用pnpm”），而Claude Code的skills更适合封装一个完整的可复用流程。

最近Codex社区也出现不少skills文件，比如数学建模比赛常用的一些codex skills，核心就是把建模流程（数据清洗、特征工程、模型对比、论文LaTeX排版）拆成一步步指令，让agent按流程干活。用下来感觉这类技能包对流程固定的比赛场景极其有效，连“华为杯”这类偏重论文写作的比赛都能用上——前提是你把赛题要求、格式规范都写进skill里。

2.3 opencode、pi agent、hermes agent的数据做法

除了Claude Code和Codex，opencode、pi agent、hermes agent这些新框架也内置了skills支持。opencode的skill目录一般在 ~/.config/opencode/skill 下，同样用SKILL.md作为入口。pi agent和hermes agent我接触相对少一些，但基本也是类似模式：内置一个技能目录，agent根据描述信息在合适任务中自动加载。社区里已经有人把“图片生成skills安装包”装到这些工具里，通过固定提示词模板和校验脚本，让不太擅长控制图片风格的agent输出风格一致的图片。这种“把好用的提示词沉淀为技能包”的做法，正是agent-skills在真实场景里最典型的应用。

可能你会问：既然各家机制不一样，写一个技能包是不是要写好几份？就我目前的经验来说，SKILL.md的核心结构是通用的，换框架时只需要微调元信息字段和目录路径，正文步骤可以几乎原样复用。所以我的建议是：先照着Claude Code的规范把skill写出来，再按需要移植到其他框架。

3. 动手写一个LaTeX排版skill：从需求分析到SKILL.md落地

这是全文最核心的实操章节。我拿“LaTeX排版”举例，因为它在学术圈、科研党里需求很高，而且步骤相对固定，特别适合作为第一个自研skill。

3.1 动手前先做流程设计师

写skill最难的不是写SKILL.md，而是梳理流程。很多初学者一上来就写“帮我排一篇论文”，然后发现AI输出的tex文件漏包、图表引用错乱、双栏格式不对。原因在于SKILL.md里根本没有定义“什么是正确的排版结果”。

我自己的习惯是：先在纸上回答三个问题。

• 输入是什么样？比如“Markdown草稿，含标题、摘要、公式、图表说明”。
• 输出必须满足什么？比如“.tex文件、IEEEtran双栏模板、公式用amsmath、图表用figure环境并带caption”。
• 中间有哪些固定步骤？比如“解析结构、填充模板、处理公式、生成图表代码、校验编译”。

只要这三条想清楚，后面填详细指令就是顺理成章的事。这一步偷懒，后面调试会花几倍时间补回来，我试过，代价不小。

3.2 元信息与触发条件的设计

SKILL.md开头的front matter是整个技能包的“门面”，我一般这么写：

---
name: latex-format
description: 将Markdown格式的学术草稿排版为LaTeX文件。适用于需要输出完整可编译.tex的论文、报告、课程作业场景。当用户输入中包含标题、章节或公式并要求LaTeX输出时使用。
allowed-tools: read, write, run
---

注意name不要太长，description要回答三个问题：输入是什么、输出是什么、什么时候用。这是触发机制能不能生效的关键。很多人花很大篇幅写“怎么做”，却忽略“什么时候用”，结果装了一堆skill但agent永远不主动调用，最后抱怨“skill没用”——问题根子多半在description。

3.3 把排版规范拆成AI能照做的步骤

正文部分类似这样的结构：

# LaTeX排版技能

## 执行步骤
1. 解析输入Markdown的标题层级，映射为section/subsection。
2. 将数学公式从 $...$ 转为amsmath的 equation/aligned 环境。
3. 表格统一转为tabular，必要时转为booktabs形式。
4. 图片引用统一使用figure环境，并为每张图片写caption和label。
5. 生成后先用tectonic或latexmk编译一次，根据报错修正。

## 禁止事项
- 不要使用尚未在模板中引入的宏包。
- 不要将中文内容无序混排，除非目标模板为中文期刊。

“禁止事项”这一节是我特别推荐写的。它可以拦住模型最常犯的“自由发挥”：比如擅自加宏包、把章节编号写死、忽略图表label。夸张一点说，禁止项可能比正向步骤更重要，因为它把“不该做什么”圈死了，模型的输出空间被限制在可控范围内，稳定性会明显上升。

3.4 模板、脚本和示例的作用

SKILL.md只描述了流程，真正保证输出质量的是辅助资产。我在templates目录里放几个已经验证过的latex模板，scripts目录放一个快速检查脚本，在校验错误时自动化定位问题，examples目录放一份“模型输出参考样例”。别小看样例——对模型来说，一个具体的输出示例，往往比十行文字规则更管用。这是模板、脚本和示例的共同价值：它们让“标准”不再抽象。

举个实际现象：我写完这个skill后，让同一个模型分别用“普通prompt”和“调用skill”两种方式排版同一篇论文。普通prompt的效果是格式基本对，但图片位置随机、引用编号靠猜；调用skill之后，图片按章节顺序放置，标签和引用对应关系一个不差。这就是把隐形流程显性化的价值。

4. 装了很多skills不生效？我的排查链路和测评方法

社区里经常有人问“skills怎么测评”“为什么装了不生效”。这一章专门聊这些问题，顺序很重要。

4.1 先确认它有没有被加载，而不是怀疑模型

第一步不是换模型，而是确认skill有没有进入上下文。不同框架的排查入口不同：Claude Code可以在会话里用相关命令或日志查看是否加载了对应skill；opencode这类框架可以通过debug日志观察。如果发现根本没加载，问题大概率出在description上——模型没法把当前任务和你的描述关联起来，它就不会主动去调用。这时候不要急着改SKILL.md正文，先把description改具体，再重测触发。

4.2 description太泛是第一个坑

我测评过一批从社区下载的skill，最明显的问题是description写得太宽泛。比如某代码审查skill写“用于代码审查”，结果agent在任何代码任务里都想调用它，反而拖慢执行；我把描述改成“仅当需要检查Pull Request中是否存在安全性漏洞、未捕获异常和重复代码时使用”，误触发率立刻降下来了。

这里有个很朴素的规律：触发描述最好精确到“输入类型+预期输出+不适用场景”。宁可让agent偶然少调用，也别让它频繁误调用。我甚至会在description末尾加一句“当用户仅询问一般性代码建议时不要使用本技能”，把边界划清楚。

4.3 怎么测评一个skill到底行不行

测评的核心思路是“同一任务、多个变体、统计输出”。我会准备5到10个覆盖不同难度和变体的标准任务，连续跑两次，每次记录三样东西：是否自动触发、输出是否通过校验、有没有明显流程偏离。

比如拿LaTeX skill来说，测试集就是：有公式的论文片段、无公式的报告、带大量图表的课程作业、双栏模板下的会议短文。跑完把错误分类——格式问题、宏包问题、引用问题——你就知道这个skill的短板在哪儿。这一套做下来，其实就是一个小型eval，不需要太复杂的平台，一个表格就能装下。很多团队说的“agent evals”，起步也就是这么做的。

4.4 安全与注入风险：不是所有skill都能随便装

这一条放在最后但非常重要。Skill的本质是“让agent按其中写的指令执行”，一个恶意构造的SKILL.md完全可能在执行任务时夹带私货，比如诱导agent读取敏感文件、把数据发到某个接口、绕过某些权限检查。热搜词里有“agent安全”不是没道理的。

我的习惯是：只从可信源下载skill；装之前一定把SKILL.md通读一遍，尤其关注“执行步骤”里有没有让人疑惑的额外操作；运行时尽量给agent最小工具权限；重要的仓库和秘钥目录不要开放给agent随意读取。这和装第三方浏览器插件是一样的心态——在代码不可见之前，保持警惕。

5. 去哪里找靠谱的skills：常用源网站、筛选标准和版本管理

5.1 社区源和“skills市场”

现在社区里已经出现不少skills聚合站点和GitHub合集，比如各种awesome-claude-skills仓库，搜索“skill名+安装包”也能找到不少。另外一些框架自带的“人工智能skills市场”也慢慢起来了，很多人把自家skill打包上传，方便一键安装。说白了，skills市场就是把原来“到处找提示词”的事，变成“找一个打包好的技能包”。

找的时候，我的搜索技巧是：不要只搜“skills”，而是搜具体任务，例如“claude code skills 图表生成”“codex skills 数学建模”“opencode skills 前端开发”。任务越具体，找到的skill越能直接干活。你要是第一眼看到的是洋洋洒洒几千字、什么都想干的“超级skill”，建议直接跳过——这种大概率什么都干不好。

5.2 筛选skill的四个硬指标

• 最近是否有更新。超过一年没维护的skill，大概率跟不上模型和框架的习惯变化。
• README和SKILL.md本身是否写得清楚。一个连自己都写不清楚的skill，指望它让AI干清楚活，不太现实。
• 有没有examples目录。没有示例的skill，调试成本通常很高。
• issue社区活跃度。有人提问、有人答复，说明它被真实使用过。

这四条基本上能过滤掉很大一部分“玩具技能包”。我自己最开始也下载过几十个，最后真正留在工作流里的不超过五个，筛掉的大部分都栽在这四条上。

5.3 用git管理自己的技能包

最后分享一个个人操作习惯：把自己写的所有skill放进一个git仓库，用标签区分版本。安装到具体框架时用软链接或复制过去，改完统一提交。这样一旦某个框架升级导致skill失效，我能快速回滚到旧版本，也能在不同电脑上最快恢复整个技能环境。

我的经验是：不要一次写一个大而全的超级skill。先从“满足自己每周都会遇到的重复工作”这种小需求写起，比如会议纪要格式化、报告排版、代码审查清单。一个技能少则一百行，多则几百行，只有实际在你自己的项目里被反复调用过，才会慢慢打磨成真正稳定的东西。那些从社区下载来的热门skill，最好也当成起点而不是终点——拿到手先改一轮，把description改成你自己的场景，再去掉用不上的步骤，它才能真正和你配合好。

最后再说一点题外话。我见过很多朋友折腾了一堆skills，最后发现最常用的也就那几个。不要被“技能越多越好”带偏，一个能稳定产出结果的skill，比十个下载安装后再也没被触发过的skill有价值得多。如果你正准备入坑agent-skills，我建议第一件事不是去排行榜下载，而是打开你最近一周的聊天记录，找一件你重复让AI做了三次以上、且每次都要重新描述需求的事，把它写成你的第一个skill。从这一件小事开始，你就真正理解agent-skills了。