Agent skills这个说法近一年几乎成了AI智能体圈里的高频词。有人叫它“给agent装上双手”有人叫它“可复用的能力包”还有人干脆理解成“进阶版提示词”。我第一次看到一整套skill文件被装进Claude Code时第一反应是这不就是把流程说明写清楚了吗等真照着superpower skills那套思路从skill包到多步骤工作流一步步跑下来才意识到事情没这么简单——skill承载的不只是指令文本它正在重构开发者和AI模型的协作方式。这篇文章想写给几类人一直搞不清agent、skill、workflow边界的人正在用Claude Code、Codex、OpenCode这类工具想把手动操作沉淀成可复用能力的人以及刚入agent开发、想系统建立技能编写能力的新手。我会尽量少讲悬在空中的概念多讲自己跑通过的流程和踩过的坑。1. 技能、工具、MCP、harness先把这几个名词的关系理顺很多人第一次接触agent开发最先懵掉的不是怎么写代码而是名词太多。skill、tool、MCP、workflow、harness、agent这些词经常出现在同一篇文档里一会儿说“技能”一会儿说“工具”一会儿又说“框架”很容易把人绕晕。我给自己梳理了一遍先记住一句话skill是给模型看的行为手册tool是给模型调用的外部功能MCP是连接两者的标准接口harness是承载agent运行的外壳agent是壳里那个会思考、会决策的主体。1.1 skill到底是个什么东西skill通常不是一个程序插件也不是一个被调用的API接口它更像是一份高度结构化的说明文档。这份文档以Markdown文件为主里面写清楚“模型在什么场景下应该启用这个技能”“按什么顺序执行”“每一步输出什么格式”“有哪些边界和禁忌”。当一个agent接受任务后会先在上下文里搜索合适的skill找到后把skill内容和用户请求一起送进模型模型再按照skill的引导逐步执行。我习惯把它类比成餐厅里的标准作业程序。一个刚入职的厨师如果只看“做一道番茄炒蛋”这句话做出来的东西可能千奇百怪但如果给他一份SOP写明番茄去皮、切块大小、放糖还是放盐、出锅时间他大概率能稳定复现同一道菜。skill就是给AI的这份SOP。区别在于AI模型本身已经知道“番茄炒蛋”大致是什么样子所以skill主要解决的是“稳定复现”和“贴合具体场景”这两个问题。1.2 skill和tool、MCP的真正分工这部分特别容易混。在agent开发里tool和skill经常被当成同义词实际分工完全不同。tool是真正执行外部动作的能力比如搜索网页、执行Shell命令、调用Stable Diffusion生成图片而skill是在模型侧组织思路和执行策略的指导文本。一个skill内部可以引用多个tool也可以完全不引用tool只规范模型的输出格式和思考路径。MCPModel Context Protocol则是让tool接入模型的标准协议。你可以把MCP想象成一个统一的电源插座不管底下的电器是冰箱还是微波炉只要插头符合标准就能通电工作。早期接入一个外部工具往往要写专门适配代码有了MCP后工具端做一个标准化封装各种agent框架都能识别。我在项目里遇到过一个很典型的场景同一个GitHub操作能力用原生tool集成时要写几十行适配逻辑改用MCP的GitHub Server后只需要在配置里声明一下agent就能直接使用。这里我用一张表把这几个概念的区别列出来方便对照记忆概念本质面向对象生活类比skill行为引导文档规定怎么做模型员工SOP手册tool真实执行外部操作的功能外部系统扳手、螺丝刀MCP工具接入模型的标准协议系统和模型之间通用电源插座workflow多个步骤的固定串联编排流程流水线harnessagent运行的外壳/环境agent本身车架agent能感知、决策、行动的智能主体用户目标司机1.3 harness和agent的区别别再被问住“harness和agent区别”这个问题在我看到的讨论帖里几乎每个月都会出现。其实harness是一个工程概念它负责把模型、工具、上下文、对话循环这些零件组装在一起跑成一个可持续交互的主体而agent更多是逻辑层面的概念指的是那个“根据目标自主决定下一步动作”的智能体本身。打个比方harness是汽车底盘和动力系统agent是坐在驾驶位上的司机。底盘决定了车能跑多快、能装多少东西司机决定了走去哪条路。如果你要给agent增加高速采集数据的能力改的是底盘如果想让agent在遇到不同任务时切换策略改的是司机的手册也就是skill。这就引出下一个重点——skill恰恰是连接“底盘能力”和“司机决策”的那张地图。2. 拆解一套可复用的skill我的agent-skills工作区长什么样理论聊完落到实践上。我自己维护了一个叫agent-skills的工作区里面放着日常高频使用的技能包。刚开始的时候我也只是把一堆Markdown文件丢进一个文件夹用起来乱七八糟后来反复调整慢慢稳定下一套还算顺手的结构。2.1 目录结构怎么组织才能让agent“一眼看懂”我的agent-skills工作区大致长这样agent-skills/ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── checklist.md │ │ └── examples/ │ │ └── review-sample.md │ ├── latex-layout/ │ │ ├── SKILL.md │ │ ├── templates/ │ │ │ ├── article.tex │ │ │ └── beamer.tex │ │ └── references/ │ └── image-prompt/ │ ├── SKILL.md │ └── templates/ │ └── prompt-schema.md ├── scripts/ │ ├── run_skill_test.sh │ └── validate_skill.py └── README.md对agent来说最重要的入口是每个技能目录下的SKILL.md。这个文件名必须是固定的因为大多数agent框架会优先扫描这个文件。目录里其他辅助文件比如模板、示例、检查清单都通过SKILL.md里的相对路径引用。起初我习惯把很多东西写进一个超长文档后来发现分成小文件更好用因为模型读取时可以有选择地加载不会一次性把上下文撑爆。2.2 SKILL.md的骨架一页纸把“触发条件”和“执行步骤”说清楚我自己总结了一套SKILL.md的写法写多了之后基本是固定几个段落name技能名字简洁一眼能看出用途。description这是最重要的字段。很多agent通过description判断“当前任务要不要用这个技能”所以里面要写清楚触发场景比如“当用户要求排版论文、制作幻灯片、处理LaTeX文档时使用”。when_to_use明确说明适用条件同时写清楚不适用条件避免模型误触发。steps主流程按编号列出执行顺序。尽量拆小步每步只做一件事。rules边界和禁忌。比如“不要修改用户已有的文档结构”“不要多次询问用户基本信息优先从上下文推断”。examples给出一个完整的输入输出示例让模型有模仿对象。一个典型的SKILL.md开头部分是这样的--- name: latex-layout description: 当用户需要创建/修改LaTeX文档、论文排版、幻灯片时使用。 --- # LaTeX排版技能 ## when_to_use - 用户提到“写论文”“排版”“LaTeX”“Beamer”等关键词 - 用户给出一段文字希望输出标准学术格式 ## steps 1. 先确认文档类型article、beamer还是report 2. 根据类型选择对应模板 3. 将用户内容填入模板保留全部正文信息 4. 检查是否有特殊符号需要转义 5. 输出完整tex文件内容并用代码块包裹 ## rules - 不要在未询问前就删除用户原有格式 - 如果用户没提供作者信息不要自行编造2.3 好skill和坏skill的差别通常差在“边界感”我写过不少失败版本回看时发现毛病几乎一样要么描述写得太泛模型什么都往这个技能上套要么步骤写得“太聪明”预设了模型根本拿不到的信息要么规则太多太重反而让模型频繁在步骤之间反复确认。好的skill应该像一份高质量接单说明目标用户是谁、什么时候找我、我会怎么做、哪些事我不做、做完交付什么。我给自己定了一个自检清单如果把这个文档丢给一个不了解项目背景的同事他能不能照着执行出80分的结果如果能这个skill基本合格。如果不能那就继续改描述和步骤。3. 安装别人写好的技能从GitHub手动装到本地技能开发有一个很方便的地方大量现成skill在GitHub等平台开源共享不用完全从零开始。我看到“superpower skills”“awesome-skills”这类项目里有很多高质量技能包下载下来就能用。实际操作中很多人会卡在“下载下来之后怎么装”这一步这里分享一下我手动装skill的完整过程。3.1 不依赖插件把GitHub上的技能放进本地环境以Claude Code这类工具为例手动安装一个GitHub技能核心就是把技能目录放到工具能扫描到的技能路径下。通用做法是去GitHub搜索想要的项目找到技能仓库地址。在本机clone或下载整个仓库。把包含SKILL.md的那些技能子目录复制到当前项目的.claude/skills/目录下如果想对所有项目生效就放到全局主机目录的skills文件夹里。重启agent会话让新技能被索引到。在对话中触发关键词验证技能是否生效。命令大致是这样# 在项目根目录创建技能目录 mkdir -p .claude/skills # 下载某个技能仓库 git clone https://github.com/example/super-skills.git # 把需要的技能目录复制进项目技能目录 cp -r super-skills/code-review .claude/skills/这里有一个容易被忽略的细节很多开源仓库里不止一个技能而是一整个技能集合。不要一股脑全部复制进来一定要按需选择。我一开始图省事把一百多个技能全部塞进目录结果agent每次都要扫描大量文件上下文消耗明显变大响应速度也更慢。装几个常用的比装一堆占空间的要靠谱得多。3.2 值得关注的技能来源挑技能也有门道我经常逛的技能来源主要有几类。第一类是各类“awesome”系列汇总仓库里面把社区里优质的skill按功能分类收录适合按图索骥第二类是专做技能集合的项目像superpower skills这类它们通常附带详细说明和使用案例第三类是直接在GitHub上搜“skills”主题标签或者搜“skill SKILL.md”这类关键词能看到大量个人开发者维护的零散技能。挑技能时要避免一个惯性思维只看star数不看适用性。star高不一定适配你所在的具体场景反而是一些小而专的技能比如“将Markdown表格转成Excel”“写会议纪要并生成待办事项”在实际工作中命中率更高。另外要注意检查技能的授权协议。有些仓库并未明确允许自由使用或改写在商业项目里直接套用会有合规风险。3.3 不同agent环境之间的skill适配问题很多人会问我在Claude Code里写的skill能用在OpenCode或者Pi Agent上吗答案是有条件地可以。由于skill本质上是Markdown文档只要目标agent支持按目录扫描SKILL.md格式上基本能通用。但不同产品对文件位置、文件名大小写、frontmatter字段的解析规则有差异。我遇到过最典型的坑是大小写问题。某个agent要求文件名严格是SKILL.md另一个agent却能识别skill.md两个命名在同一次安装里导致其中一个环境下技能静默失效。后来我给自己定了一个规则在任何项目里统一用SKILL.md大写命名同时确认目标框架是否支持同名文件扫描。还有一点某些agent需要额外在配置文件里“启用”技能默认只扫描但不激活如果装了技能没反应优先去看看配置文件里的enable或plugins字段有没有写明白。4. 从需求到落地手写LaTeX排版与图片生成两个skill理论再多不落地都是空的。我挑两个自己完整跑过的技能案例来拆解一个偏文本生成一个偏多步骤调用工具。这两个案例基本覆盖了“写清楚规则”和“协调外部工具”两种常见模式。4.1 先定触发场景再写执行流程第一个案例是LaTeX排版技能。我的实际需求很简单写技术文档时经常要临时生成标准论文模板。以前每次都要手动开一个在线LaTeX编辑器或者复制一份旧模板再改效率很低。后来写了一个latex-layout技能当用户说“帮我排版一篇双栏论文”“生成一个beamer幻灯片”时agent会按固定流程输出完整可编译的tex文件。第二个案例是图片生成技能。这个技能需要协调一个外部绘图工具或API。大多数模型知道怎么写提示词但写出来的提示词常常缺少画面比例、风格标签、负面提示词这些细节。我的image-prompt技能做的事情是先根据用户描述提取主体、场景、风格、构图四个要素再按设定好的模板拼装成标准prompt最后调用外部工具生成图片。从这两个案例可以看出来一个纯文本技能的难度集中在描述和步骤设计涉及工具的技能难度转移到工具调用、上下文传递和异常处理上。4.2 技能上手实践从零写一个可用版本我自己写技能的时候会按下面几步走。第一步先写一个最小可用版本只保留description和steps能用就行第二步跑一个真实用例看模型输出的结果和预期差多少第三步把差距转化成rules和examples补进去第四步丢进真实项目里连续使用几天不断修正触发时机。比如写image-prompt技能我最初只有一句description和五个步骤结果模型连出几次问题该画横向图却生成了纵向图、用户说“赛博朋克风格”时提示词里没有风格权重、遇到“不要有文字”这种需求没有写进负面提示词。于是我每踩一个坑就往rules里加一条规则并对应补充一个example。下面是这个技能核心部分的一个示意## steps 1. 提取用户描述中的主体和动作 2. 提取风格、氛围、镜头、画幅信息 3. 按模板生成prompt - 正向提示词主体描述 风格词 细节词 画幅比例 - 负面提示词模糊、低质量、多余手指、画面文字 4. 调用images生成接口传入完整参数 5. 将生成结果和图片地址返回给用户 ## rules - 用户没有明确画幅时默认使用16:9 - 用户说“文字”时要在负面提示词里排除text/watermark - 必须保留英文提示词原样不要自行翻译成中文 - 生图失败时检查参数并重试一次仍失败则报告错误信息4.3 高发报错的排查思路“agent execution terminated due to error”“agent execution terminated due to error”这个报错几乎所有跑过agent流程的人都见过。它本身不是一个具体的错误原因只是agent运行循环中断的最终提示真正的问题藏在它之前的日志里。我遇到过几次原因各不相同。一次是因为skill文件里引用了一个不存在的外部工具。技能步骤写“调用图片生成的Server”但配置里根本没有注册这个MCP Serveragent执行到那一步时找不到对应工具整个会话直接终止。排查方法很直接打开日志看到“tool not found”“server not found”这类关键词回配置里补上工具注册。还有一次是模型生成的中间文件太大把上下文窗口塞满了运行超时被强制终止。那次是因为我在技能目录里放了一个很大的模板文件模型每次执行都把整个文件读进上下文。解决方式是把模板改成按需加载路径并限制一次性读取的内容长度。排查这类问题时我强烈建议先把agent的工作目录和日志级别调成debug模式。清晰的日志能告诉你是哪一步卡住、调用了什么参数、返回了什么异常。绝大多数“terminated due to error”都不是玄学而是一个可以被复现的工具链问题。5. 技能之外的agent开发记忆、评估与学习路线演完技能本身其实还有一圈更大的议题等着如果你真想进阶agent开发绕不开记忆、评估和整体的学习路径。我在实践里最大的体会是技能是agent能力的“骨架”记忆是“血肉”评估是“体检报告”缺一个都长不成健康的项目。5.1 让记忆和技能各司其职别混为一谈很多新手会把“记忆”也写进技能里比如在skill里预设“用户喜欢简洁风格”“用户常用Python”。这个做法短期看有效长期很危险。技能是静态的、可复用的方法记忆是动态的、属于单个用户或单次任务的状态。如果把个性化信息写死进技能换个用户或者换个项目技能就失效了维护成本急剧上升。现在很多agent框架提供长期记忆能力比如记录用户偏好、历史对话摘要、关键决策。它和skill配合的方式应该是技能提供完整的执行框架记忆给框架填充本用户的具体参数。我在设计agent时会把稳定不变的方法写进skill把因人而异的信息托管给记忆模块两者中间用变量或模板字段连接。5.2 用agent evals判断技能是否真的可靠一个技能写完之后怎么判断它好不好靠感觉不如靠评估。现在agent社区里越来越重视evals也就是用一组固定测试用例反复跑同一套流程观察技能是否符合预期。常见的做法是给每个技能准备一个测试集包含10到20个典型输入并标注理想的输出特征然后批量执行检查通过率。我这些天在用的评估流程很简单把测试输入逐条喂给agent记录执行结果、工具调用链、最终输出和中间报错再用几个规则去判断结果质量。比如LaTeX技能我就检查生成的tex能不能通过本地编译图片技能我检查输出里是否包含画幅比例、风格关键词、负面提示词。规则来自技能当初的rules等于让技能自己定义“什么是好结果”。有了评估数据之后迭代才谈得上。比如某次评估发现技能在“长文档”场景下经常漏掉章节编号我就在skill里补一条步骤“处理多章节文档时输出前检查带编号的章节是否连续”。每补一条重新跑一遍评估集环比提升多少一目了然。5.3 给新手的agent学习路线按阶段走别跳跃最后聊一下“如何学习skills和agent开发”。这个话题在社区问得很多我的建议是分三个阶段走。第一阶段先用成熟工具跑通闭环。不管Claude Code、Codex还是OpenCode挑一个顺手的环境把已有技能装进去跑几个真实任务感受一下“agent怎么读取技能、怎么调用工具、怎么给我反馈”。这一步别急着写先建立体感。第二阶段开始写自己的技能。从最简单的纯文本技能入手比如“生成周报”“整理会议纪要”把一个场景写透、写好。等你发现“每次都要手动调prompt”时自然就会想把它封装成skill。第三阶段研究框架、记忆和编排。到这个阶段你会碰到“agent框架与编排”“多agent协作”这些话题。这时候再看框架源码、追底层调度逻辑效率比一上来就啃框架高得多。理解完框架再回头完善自己的技能库你会发现早先很多“怪癖”都能找到工程上的解释了。最后分享一个我自己习惯上的小变化以前我特别沉迷于把技能写得面面俱到后来发现一个技能一旦超过15个步骤模型执行时反而容易在步骤之间“迷路”。现在我的原则是“一技能一焦点”复杂场景宁可拆成两三个技能分步调用也不堆在同一个SKILL.md里。这也是我折腾agent-skills这段时间里得到最重要的一条经验。