最近一直在折腾AI编程和智能体开发接触最多的一个词就是“agent-skills”。之前我一直把大部分精力花在调提示词、拼工具调用上后来发现真正让agent变“好用”的往往是那一个个小而精的skills也就是技能包。这个方向最近讨论热度很高从Codex到Claude Code再到各类开源agent框架基本都把自己的扩展体系押在skills上社区里推荐、评测、自研skills的人也越来越多。简单说skills解决的是一类非常现实的问题大模型本身能力很强但一放到具体业务里经常会忘记规则、输出格式乱、不知道调用哪个函数而这些恰恰是可以被工程化的。skills就是把这些“约定俗成的操作流程”打包成agent能理解、能复用的能力模块让agent在合适的场景自动加载并执行。不管你是做前端开发、写文档、画结构图还是搞LaTeX排版都能自己搓一个skill用完还能丢给别人一起用。这篇就围绕agent-skills展开聊聊它到底是什么、怎么工作、怎么从零手写一个、怎么安装和评测以及我实际使用中踩过的一些坑。如果你是刚开始接触agent开发或者已经上手但觉得agent总是不够听话这篇文章应该能给你一个比较完整的参考。1. skills在agent开发里的定位能力资产而不是临时提示词1.1 我先说一个让人哭笑不得的对比在没有skills之前我让agent帮我写某个类型的前端组件每开一个新会话就得把“你用React、样式用Tailwind、组件要导出默认函数、props要带类型、注释要写中文”这些话重新说一遍。更烦的是同样的要求在不同会话里agent落地的细节还总是不一致这次用单引号下次用双引号这次button样式A下次又成了样式B。后来我把这些规则统一抽成了一个前端开发skillagent只在检测到“要写React/Tailwind组件”的场景时读取这份技能描述之后所有输出都严格对齐里面的规范。那种感觉就像从“每次进厨房前都要口头交代佐料”变成了“把菜谱贴在冰箱上看一眼就自动按流程做”。这其实点明了skills的本质它是agent的能力资产是可复用、可版本管理、可分享的“菜谱”而不是躺在聊天记录里的临时提示词。1.2 为什么这两个月它成了热词搜索热度侧面反映了供求关系。过去大家做AI agent注意力都集中在模型选型、框架选型、多模态接法上后来模型能力上来之后瓶颈转移到了“如何让agent把事儿干得稳定、干得贴合业务”。你可以把模型本身想象成一个特别聪明但有点毛躁的新员工skills就是给他准备的岗位手册和工具包。这个思路迅速在几个方向打开局面一个是编程助手领域把提交信息规范、测试框架选择、代码审查清单做成skills让agent的编码产出符合同一项目风格另一个是内容生产领域把图片生成、结构图绘制、LaTeX排版这类“管线型任务”做成skills避免每次手动叮嘱第三个是数据与自动化领域把SQL查询、Excel处理、API对接等流程沉淀成技能包让业务人员也能用自然语言调用。skill和agent的组合正在变成一种非常务实的工作模式。1.3 skill和agent、harness的区别这个概念经常混我见过很多朋友把skills直接等同于agent或者把框架的harness当成skill体系其实它们的分工完全两回事。我用一张表来对比层级职责类比Agent负责理解任务、拆解计划、调用工具、根据结果调整动作是有记忆和决策闭环的执行主体一条产线上的作业员Harness控制agent如何连接模型、如何管理上下文窗口、如何调度工具、如何终止执行是承载agent的框架骨架产线上的传送带和控制系统Skill一个可复用的特定能力包告诉agent“做什么、按什么顺序做、输出成什么样”可以被多个agent在不同会话中引用产线上随时切换的工装夹具可以这么理解agent是“决策者”skills是“执行模板”harness是“运行底座”。没有agentskill只是一堆文档和脚本没有skillagent只能靠每次对话临时拼凑做法没有harnessagent根本跑不起来。现在主流的CLI编程工具本身是harness 内置agent而你想让它更贴合自己的项目就得往里面塞skills。这也是“harness和agent区别”“skill和agent的区别”这类问题特别多人的原因因为在设计扩展能力时这个边界必须先想清楚。2. skills的核心机制描述触发、指令执行、结果回填2.1 一个skill由什么组成我在实际项目里把skill拆成三个部分技能描述文件、执行脚本或模板、附带资源。技能描述通常是SKILL.md头部带YAML格式的frontmatter里面写明技能名称、触发条件、适用场景、使用示例正文则是给agent看的详细操作步骤。执行脚本可以是Python、Shell、JavaScript也可以是模板文件、提示词片段和配置文件。附带资源包括参考图片、数据字典、项目风格文件等。以我写的一个“前端组件开发skill”为例目录结构长这样frontend-react/ ├── SKILL.md ├── scripts/ │ ├── gen_component.py │ └── gen_stories.py ├── templates/ │ ├── component.tsx.tpl │ └── index.ts.tpl └── assets/ └── project-style-guide.md核心就是那个SKILL.md。agent在开始任务前会提前扫描所有可用技能包里的description字段判断当前任务是否命中命中了才把SKILL.md正文加载进上下文。所以SKILL.md写得好不好直接决定了agent能不能在正确的时候正确使用这个能力。2.2 前端描述信息是怎么影响“触发”的很多skill“没被触发”问题往往不出在代码里而出在description写得太抽象。比如你写“适用于处理各种文本编辑场景”agent看到之后大概率会陷入选择困难因为几乎所有任务都跟“文本”沾边。更合理的写法是把触发词、使用条件、反例都写清楚。我在一个技能包里这样写过--- name: latex-typesetting description: 用于生成和修改LaTeX文档的场景。当用户要求写论文、排版简历、制作学术海报或处理基于LaTeX的文档时使用。如果用户只提到Markdown、Word或纯文本排版请勿使用本技能。 ---description里既有正向触发词论文、简历、学术海报又有反向排除词Markdown、Wordagent命中准确率会显著提高。这也是为什么那些“一个skill覆盖所有需求”的做法往往不好用因为覆盖广意味着触发条件模糊最后反而处处找不到它。2.3 指令正文的边界感和执行闭环SKILL.md正文部分我建议写成“操作流程 输出规范 自检清单”三段式而不是直接把一大段话塞给agent。操作流程描述步骤比如“先检查用户输入是否包含.tex源文件再决定新建还是修改编译时按latexmk -xelatex处理”输出规范明确最终交付物的格式比如“返回修改后的tex源码和编译建议不输出二进制PDF”自检清单则让agent在提交结果前自我验证一遍比如“是否导入了ctex宏包、是否有中文字体配置、公式是否缺失”。执行脚本要尽量幂等因为agent可能会在一次任务里反复调用同一技能。比如我的图片处理skill脚本会把原图和输出分目录放好每次执行只覆盖输出目录不会动原始素材。这样即使agent中间失败重试也不会把数据搞坏。3. 从零开发一个skill以LaTeX排版技能为例3.1 先确定边界再动手我一直在做论文排版类的工作经常会碰到一个word文档或Markdown文档需要转成规范的LaTeX。每次让agent直接改它总会引入奇怪的宏包、跳掉中文配置、甚至把数学公式写崩。后来我干脆自己写了一个skill第一步就是明确边界这个技能只负责“生成和修改LaTeX源文件”不负责编译、不负责PDF预览、不负责处理TikZ复杂绘图。边界明确后思路就清晰了先建目录、再描述触发、再写脚本和模板、最后安装测试。整个过程差不多半小时能跑通。3.2 创建目录和SKILL.md我习惯把skills放在一个统一目录管理比如在项目根目录下创建.agent/skills或者放在用户级目录~/.agents/skills。这里以项目级为准mkdir -p .agent/skills/latex-typesetting/scripts cd .agent/skills/latex-typesetting touch SKILL.mdSKILL.md我这样写--- name: latex-typesetting description: 生成和修改LaTeX学术文档。适用于论文、简历、报告等场景。当用户要求将Markdown/Word内容转换为LaTeX、修复LaTeX编译错误、或优化LaTeX排版时使用。 --- # LaTeX排版技能 你是LaTeX排版专家。遵循以下流程 ## 步骤 1. 检查用户输入确认目标语言中文/英文和文档类型article/report/beamer。 2. 若需要新建文档使用scripts/gen_doc.py生成骨架若修改已有文档先读取完整源码再继续。 3. 中文文档必须添加ctex宏包使用xelatex编译链。 4. 数学公式使用amsmath宏包复杂公式用align环境。 5. 图片统一放在figures目录引用时用相对路径。 ## 输出规范 - 只输出tex源码和修改说明不输出编译后的PDF。 - 文件编码UTF-8缩进统一4空格。 - 所有自定义命令必须在导言区集中定义。 ## 自检清单 - [ ] 是否包含documentclass和begin/end{document}。 - [ ] 中文环境是否引入ctex。 - [ ] 引用的宏包是否都出现在导言区。 - [ ] 是否有未闭合的环境或括号。这份描述文件对agent来说已经可以直接执行但最好再配一个生成骨架的脚本避免每次手写一大段模板。3.3 写辅助脚本和模板我写了一个极简的Python脚本用来生成LaTeX文档骨架避免agent在代码块里手敲容易出现大小写错误。脚本逻辑很简单#!/usr/bin/env python3 import sys DOC_TYPES {article: article, report: report, beamer: beamer} def create_doc(doc_typearticle, titleUntitled, author): doc_class DOC_TYPES.get(doc_type, article) header r\documentclass{ doc_class }\n preamble r\usepackage[UTF8]{ctex}\n\usepackage{amsmath}\n\usepackage{graphicx}\n begin r\begin{document}\n title_block f\\title{{{title}}}\\author{{{author}}}\\maketitle\n body r\section{简介}\n\n end r\end{document}\n return header preamble begin title_block body end if __name__ __main__: doc_type sys.argv[1] if len(sys.argv) 1 else article title sys.argv[2] if len(sys.argv) 2 else Untitled author sys.argv[3] if len(sys.argv) 3 else print(create_doc(doc_type, title, author))在SKILL.md里可以明确告诉agent“新建文档时执行python3 scripts/gen_doc.py article 标题 作者获取骨架再基于骨架继续编辑。”这样实际输出稳定性会高很多。3.4 安装到运行环境并验证触发不同工具读取skills的路径不太一样我用的比较多的是把skills软链接到一个全局目录或项目目录然后在新会话中测试。安装方式其实很朴素把技能包目录加到agent可扫描的skills路径下或者把仓库克隆下来后建个软链接。安装完我习惯做一个“触发验证矩阵”。我会准备几条不同的指令比如“帮我写一份中文论文的LaTeX骨架”“把这篇文章改成带参考文献的LaTeX”“给我做一个beamer幻灯片”再准备几条不该触发它的指令比如“用Markdown帮我做一份简历”。运行后看日志或输出确认命中与未命中都符合预期。如果该触发没触发就去改description的措辞如果不该触发却触发了就强化反向条件。这个过程非常值得做否则你不知道技能包在真实环境中的表现如何。3.5 从用例到通用如何沉淀更多skills有了第一个skill的经验后再开发新技能就顺手很多。我做图片生成skill时思路完全一致描述触发条件比如“用户想生成插画、海报图、头像”给出生成规范比如“输出1024x1024的png风格保持柔和插画风”再加一个统一的后处理脚本处理图片尺寸和元信息。做前端开发skill也是同一套路只不过模板更多、规范更细。你会发现skills开发的核心不是写多少代码而是把“你希望agent稳定执行的流程”描述清楚。描述得越清楚agent执行得越准。4. 常用skills盘点与安装使用技巧4.1 值得优先纳入的skill类型社区里流行的skill五花八门我按使用频率和效果排个序最值得先装的大概是这几类开发规范类统一的代码风格、提交信息格式、命名规范、测试写法这类能立刻提升agent在工程里的“默契度”。文档处理类Markdown排版、LaTeX排版、表格转换、PPT大纲生成凡是涉及固定格式的都用得上。图像图表类图片生成、结构图绘制、流程图转代码这类技能通常封装了提示词工程和图像服务调用输出差距很大。数据处理类CSV清洗、SQL生成、Excel处理、JSON结构转换适合数据分析场景反复使用。我在实际里最依赖的反而是最简单的“提交信息规范化”技能。它只有一份不长的SKILL.md不需要脚本但每次agent提交代码时的message格式都统一了团队review时舒服很多。可见skills不一定要复杂关键是贴合真实场景。4.2 安装路径的几种实践关于安装我把常见做法整理成下面几条全局用户级目录比如把技能包放在类似~/.config/agent-skills的目录然后在agent的配置里声明扫描路径。好处是一次安装所有项目可用。项目级目录通常叫.agent/skills或者.claude/skills跟着仓库走团队克隆下来就能用。适合项目定制的规范。软链接方式把核心技能包统一放在一处再在多个项目里做符号链接避免重复复制维护。我建议日常使用的通用技能放全局目录针对项目特有的规范放项目目录。如果两种都配了要在SKILL.md的description里把使用范围写清楚否则会出现“全局的React规范技能”和“项目里的React规范技能”在同一任务里同时触发的情况。4.3 怎么评测一个skill到底好不好很多人问“skills怎么测评”我自己的评测维度有四个触发准度在该用的场景能用上不该用的时候不抢戏。这个看命中率和误报率。指令完成度任务完整执行的比例是否经常只做一半。输出稳定性相同输入下多次运行结果是否一致。不稳定意味着skill里某些指令有歧义。上下文占用SKILL.md写得越精简agent留给具体任务的空间就越多。一上来就写5000字的skill大概率会撑爆窗口。我评估时会给每个维度打分重点看触发准度和输出稳定性。很多刚自己写skill的朋友容易陷入“把规则写全”的执念结果技能包膨胀严重反而把agent带偏。精简优于堆料。4.4 安装之后还要做版本管理技能包和代码一样需要版本管理。我在本地会维护一个skills仓库每个技能包一个目录改动后提交commit记录。这样一旦新版本导致agent行为异常可以快速回滚到上一个稳定commit。如果团队合作这个仓库还能让成员一起review技能描述避免个人经验变成“黑盒”。5. 常见问题与排查技巧实录5.1 技能一直不触发怎么办这是最常碰到的问题。我排查时先看SKILL.md的description是否写得太笼统或者太窄。太笼统会导致什么任务都命中但什么任务都不精准太窄也不行比如只写“在用户要求latex时使用”agent可能把“latex”理解成“乳胶”而忽略。更稳的做法是列出同义词和近义场景词比如“论文、简历、学术海报、xelatex、beamer、tex源文件”。同时加入反例排除“markdown、word、txt”这些不相干场景。如果还是不行就手动开一个会话把任务描述先直接交给agent让它分析“你觉得这个任务应该使用哪个技能为什么”通过它的判断来反向修正description。这一招非常管用相当于是让gaokao考生自己说你看漏了哪个考点。5.2 一个任务同时命中多个skill互相打架项目里同时装了好几个文档处理技能后这个问题就不可避免。比如“写一份会议纪要”同时命中了“markdown排版技能”和“文档总结技能”agent便会纠结。解决方案有两种一是缩小每个skill的适用范围在description中增加明确的“不适用的场景”二是在SKILL.md正文里约定优先级比如“如果用户要求的是格式整理仅使用本技能不调用内容生成类技能”。另外在技能包的frontmatter里可以增加优先级属性被agent扫描时会有更清晰的排序依据。总之要让agent的选择路径尽量唯一化。5.3 技能执行到一半被中断或报错最典型的表现是“agent execution terminated due to error”。我遇到过几次原因大同小异脚本依赖了不存在的环境路径写错或者上下文太长把执行窗口撑满。排查思路是按三步走第一步看报错信息确认是脚本层还是agent决策层的问题。脚本类错误直接本地跑一遍脚本看看依赖是否完整。第二步检查SKILL.md是否要求agent在执行过程中载入太多内容比如让它在一次操作里读10个文件超窗口是必然的。拆成多个小步骤更稳妥。第三步给脚本加超时和异常捕获保证出错时能返回明确错误信息而不是直接终止。我给每个脚本都加了一个统一的入口输出固定格式的JSON或纯文本结果agent解析起来更省力出错时也能看到具体在哪里断掉。5.4 技能引入后反而让agent“变笨”这种情况通常不是因为模型退化了而是因为技能描述里的指令互相矛盾或者上下文里塞入了大量无用信息。比如某个技能包只对特定文件格式有用但agent每次任务都先读它等于白白消耗窗口。我遇到这类问题后第一时间会做“技能包最小化”把SKILL.md压缩到核心步骤把详细参考信息移到assets目录只在需要时加载。还要检查技能描述里是否有大量重复的提示词很多技能包是直接从历史对话里复制出来的废话太多反而干扰了决策质量。与其担心“技能不够多”不如先把现有技能做瘦身。5.5 安全与信任不是所有skill都能直接用一个坑这个必须单独说。skills本质上是一段会被agent读取并可能执行的指令和代码社区里有大量现成技能包可下载方便是真方便风险也确实存在。一个技能包可以在SKILL.md里写着“生成图片”脚本里却偷偷读取敏感文件或者改配置文件一个描述文档也可以故意写得像系统指令诱导agent绕过约束。我现在安装新技能包前会默认审查三处SKILL.md里的frontmatter有没有异常指令脚本里有没有访问外部网络、读取环境变量、修改系统配置的操作description里是否含有“忽略之前的指令”这类提示词注入特征。只信任来源清晰的技能包不在生产环境里贸然安装来路不明的包。真需要功能相同的技能优先自己看着源码重写一遍成本往往比想象中低。5.6 技能版本更新后出现行为回退我用过一些社区的技能包刚安上时表现很好更新一版反而变差了。排查后发现新版本在description里加了很多“更精确”的触发词结果把原本能触发的场景挡在门外了。处理方式很简单要么切回旧版本commit要么自己改一版精简描述。这也说明技能包的版本管理有多重要升级前一定要看变更记录升级后一定要跑一轮触发测试。一些个人实操体会说了这么多最后再分享一个我自己摸索出来的小技巧给每个技能包建立“验收清单”。也就是在SKILL.md末尾固定一段“完成标准”让agent交付前逐项自检。比如LaTeX排版技能里就是检查documentclass、检查ctex、检查宏包、检查闭合括号前端组件技能里就是检查props类型、检查样式方案、检查是否导出组件。这个清单对提升输出稳定性的帮助比对提示词调参还要大我强烈建议试一下。从“临时写提示词”到“沉淀成skills”本质上是把和agent的合作方式从“每次都要教育它”变成了“有一整套标准作业程序”。这也解释了为什么agent-skills会变成热门方向它让规模化、团队化、可复用地使用agent成为可能。如果你的agent开发已经过了新鲜期遇到的大多数问题都出在“行为不稳定”“细节不一致”上那我建议别急着换模型先回头看看自己的skills体系是不是该更新了。