这两年做 AI Agent 相关项目我被问得最多的一个问题就是为什么同一个模型有人能调教出顺手得吓人的智能体有人却只能得到一个会聊天、不会干活的玩具一开始我也以为是提示词写得好不好、模型强不强的问题直到我把 agent-skills 这套思路完整用了一轮才意识到问题往往不在模型本身而在“技能”这一层。Agent Skills字面意思是智能体技能确切点说就是把“模型完成任务时需要的过程性知识”封装成 agent 能按需读取、执行、复用的独立资产。它不是提示词模板的简单升级也不是挂在某个脚本里的工具函数而是一套从“技能定义-技能发现-技能执行-技能维护”全链路打通的工程实践。这篇文章我会从实际项目角度拆解 agent-skills 到底是什么、一个技能包内部长什么样、怎么从零写一个能用的技能以及我踩过的具体坑。无论你是在做个人助手、团队知识库还是垂直领域应用这套思路都值得了解一下。1. agent-skills 解决的不是“多一个工具”而是能力存放位置的问题很多人第一次接触 agent-skills 时会下意识觉得这跟多写几个函数、多配几个工具调用有什么区别区别很大。函数和工具解决的是“agent 能做什么动作”而 agent-skills 解决的是“agent 知道什么时候做、按什么顺序做、做到什么程度算完”。前者是原子操作后者是完整的工作流。1.1 从工具到技能能力粒度的一次质变我最早做智能体的时候习惯把所有能力都堆在 function calling 里。比如给 agent 接一个“查询天气”的函数再接一个“查询日历”的函数再接一个“发送邮件”的函数。结果 agent 确实会调用了但遇到“帮我安排明天下午的会议”这种复合任务它只会机械地查日历、发邀请完全不懂要提前确认参会人空闲时间、要预留路程时间、要准备会议纪要模板这些“人应当知道”的步骤。agent-skills 的核心思路就是把这类“人应当知道怎么做”的知识从人的脑子里、从零散文档里搬到一个 agent 可以主动读取和执行的资产包里。技能包里既包含描述“何时使用、怎么使用”的说明文件也包含可执行的脚本、模板和校验逻辑。Agent 在跟用户对话时会像人翻手册一样先判断当前任务匹配哪个技能再按技能里的步骤执行而不是靠模型硬猜。1.2 日常沟通和书信技能包绝不是提示词模板区分几个容易混淆的概念这里用一张我常给团队看的表形态粒度谁在执行可否复用典型问题提示词模板一句话或一段指令模型直接遵循能复制难维护没有校验和可执行逻辑工具函数单个原子操作模型调用代码能不懂业务流程只会单点调用插件框架多个工具配置代码框架调度能重绑定特定平台agent-skills完整技能流程模型自主发现并执行能且可组合需要认真设计技能边界提示词模板最大的问题是没有“执行层”。你可以在系统提示里写“帮用户汇总周报时要先收集各成员数据再检查完整性最后生成 Markdown 报告”但模型只能靠语言直觉去完成。一旦遇到文件路径变了、数据格式变了、某个字段缺失了模型往往会当场懵掉。agent-skills 则把“读数据-校验-生成报告”这些步骤落到真实脚本里说明文档负责教模型什么时候调用、怎么判断结果脚本负责保证执行结果稳定。这就像菜谱和锅铲的区别菜谱告诉你顺序和火候锅铲负责把菜翻熟两者缺一不可。1.3 为什么它能让 agent 和人都感到轻松我用 agent-skills 之后最直观的感受是模型突然“靠谱”了很多。原因不难理解模型的上下文窗口是有限的你不可能把所有流程细节都塞进系统提示更不可能在每次对话时重新解释“这个报表要按什么格式出”。技能包把大部分过程性知识放在文件系统里模型只需要读关键部分按需执行上下文压力小很多。而人这边维护一个技能也比维护一沓提示词文档轻松技能里的说明和脚本放在同一个目录改了代码顺手更新说明版本清清楚楚。2. 拆开一个技能包SKILL.md 与可执行代码是怎么配合的如果把 agent-skills 比作一个开源项目那 SKILL.md 就是这个项目的 README但它比普通 README 更需要讲究“写给谁看”。普通 README 是给人看的SKILL.md 是给模型看的同时也给维护技能的人看。所以它既要模型能准确理解又要人方便维护。2.1 一个典型技能包的目录结构我常用的技能包长这样website-audit/ ├── SKILL.md ├── scripts/ │ ├── check_links.py │ ├── lighthouse.mjs │ └── report_builder.py ├── assets/ │ └── report_template.md ├── requirements.txt └── config.jsonSKILL.md 放技能说明scripts 放可执行脚本 assets 放模板类资产requirements.txt 放 Python 依赖config.json 放可调参数。这个结构不是拍脑袋定的它有非常实际的原因模型发现技能后首先读 SKILL.md 判断要不要用确认使用后再根据 SKILL.md 的描述去调 scripts 里的脚本。所有依赖和配置集中管理避免“脚本能跑但模型不知道要装什么依赖”这种尴尬。2.2 SKILL.md 中“写给模型的话”要怎么设计SKILL.md 我一般分成两个大块YAML 元数据区和正文指令区。元数据区包含 name、description这是模型做技能匹配的关键依据。正文指令区写清楚三件事这个技能什么时候用、什么时候坚决不用、具体执行步骤是什么。我早期写 SKILL.md 时犯过一个典型错误description 写得太泛。比如“帮助用户进行网站审计”模型面对“帮我看看这个网页加载快不快”时会犹豫到底该不该用。后来我改成“当用户需要评估网站性能、可访问性、SEO 基础情况并生成结构化报告时使用当用户只是随口问一个 HTML 标签含义时不要使用”。效果立竿见影误触发率明显下降。这个细节非常值得记下来。2.3 可执行脚本承担什么角色SKILL.md 负责“决策”scripts 负责“执行”。比如 check_links.py 就是一段独立可跑的 Python 脚本输入一个网页地址输出一份链接状态列表。模型不需要理解脚本内部怎么用 requests 库、怎么处理重定向它只需要知道“跑这个脚本把结果读回来”。这带来一个很大的好处模型的决定更可靠了。脚本是确定性逻辑不会像模型自由发挥那样忽好忽坏。真正决定一个技能能不能用往往卡在依赖安装和环境隔离上。我的做法是给每个技能配一个虚拟环境或独立容器在 SKILL.md 里明确写明启动脚本前必须先执行依赖安装命令。这一步不能省否则你昨天还能跑的脚本今天换了台机器直接报ImportError模型只会一脸茫然地反复重试。2.4 可复用与可发现技能对人和模型是一套资产还有一点容易被忽视技能包不只在 agent 运行时才有价值。它本身就是一套很好的人类可读文档。新同学接手项目时只要打开 SKILL.md 就知道“这摊业务是怎么处理的”这比翻聊天记录和看散落的脚本高效得多。所以我在团队里推 agent-skills 时总会多说一句别把技能当成机器人的私有配置它也是团队知识库的一部分写到什么程度、结构清不清晰直接决定它能不能被长期维护下去。3. 从零写一个技能以“周报自动汇总”为例理论说再多不如直接动手。我拿一个真实用过的场景“周报自动汇总”来说说完整实现路径。这个技能不大不小正好覆盖 agent-skills 的核心环节数据收集、内容校验、生成报告、处理异常。3.1 需求拆解先定边界再写代码动手之前先问自己三个问题输入是什么输出是什么哪些情况算“不该管”我的定义是输入是一个团队成员的周报文本或链接列表输出是一份按人归类的 Markdown 周报汇总文件边界是不负责提醒谁没交周报也不负责生成评语那些是另一个技能的活。把边界划定之后写技能时就不会什么都往里面塞模型也不会因为技能描述含糊而犹豫不决。3.2 编写脚本与 SKILL.md 的完整过程先写一个收集脚本collect_reports.py负责扫描指定目录下的所有周报文件解析出作者、日期、正文三个字段。再写一个build_summary.py把这些字段汇总成 Markdown。脚本本身不复杂复杂的是让模型知道“现在该跑哪一条命令、中间出错怎么办”。SKILL.md 我写成这样--- name: weekly-report-summary description: 当用户需要汇总多份周报并生成统一 Markdown 文档时使用。 尤其适合团队成员提交的周报分散在多个文件或链接中的场景。 如果用户只是询问某个人的周报内容请直接阅读该文件不要调用本技能。 --- # 周报汇总技能 ## 使用步骤 1. 调用 collect_reports.py 扫描 raw_reports 目录。 2. 读取生成的 report_list.json检查是否有缺失字段。 3. 若有字段缺失在回复中列出缺失项并使用默认值补齐。 4. 调用 build_summary.py 生成 summary.md。 5. 将 summary.md 路径告知用户并给出简要说明。 ## 注意事项 - 脚本运行失败时先检查 raw_reports 目录是否存在。 - 数据量大时不要把完整 JSON 一次性粘贴到回复中。这一段描述的信息密度很关键。我没有写“请礼貌地帮助用户”因为模型不缺礼貌缺的是明确边界。步骤从 1 到 5每一步都有可验证的产物模型不会不知道该干嘛。3.3 本地验证模型不只看说明还看实际结果写完之后我习惯在命令行把技能跑一遍确认 collect 和 build 两个脚本都能正常出结果。这里有一个经验模型会自己执行你写的命令但它不会像人一样“跳过错误继续”。如果脚本报错了一个小 typo模型可能会反复尝试浪费大量时间。所以写技能时脚本要尽量“宽容”——能加默认值的地方就加默认值能不因为单个缺失字段中断的地方就别中断。我第一次测试时在 SKILL.md 中写“使用 Python 运行 collect_reports.py”结果模型用了python3但 requirements.txt 里的依赖压根没装。后来我特意在步骤 0 加了一条pip install -r requirements.txt且失败时停止不要尝试用其他方式补包。这个小改动让整个技能稳定回报率提升了不止一个台阶。3.4 容易踩的坑路径、权限、幂等性再列几个我在这个技能上踩过的具体坑相对路径混乱模型的工作目录会变脚本里写死的相对路径一旦找不到文件就报错。解决办法是让脚本内部用当前文件所在目录作为基线。文件覆盖问题重复运行 build_summary.py 会覆盖之前的汇总文件。我在脚本里加了时间戳后缀避免破坏历史记录。输出被截断数据量大时模型读回结果容易超上下文。我让脚本自动生成摘要统计并先行输出细节部分按需读取。这些坑都不是模型的问题而是技能作者没把执行环境想清楚。写技能和写 API 一个道理调用者越不需要知道内部细节出错率越低。4. 技能被发现的过程命名、描述与渐进式披露一个技能写得再好如果模型在关键时刻想不到用它一切白搭。我看过很多团队花大力气做技能结果 agent 还是天天答非所问问题基本都出在“技能发现”环节。4.1 模型靠什么判断用哪个技能模型拿到用户请求之后会把请求跟每个候选技能的 description 做语义匹配。这个机制有点像搜索引擎你的 description 就是技能页面的标题和摘要能不能在正确的时刻被“搜索”出来直接决定技能使用率。很多人的 description 写得太抽象比如“提供实用的工具能力”这对模型没有任何区分度。我一般要求 description 遵循“触发场景典型输入输出明确排除项”的句式宁可长一点也要把边界讲清楚。4.2 渐进式披露别让模型一次性读太多SKILL.md 不是越长越好。模型先读到的是元数据和 brief 部分判断命中后才会深入阅读详细步骤。如果一开始就把 2000 行的完整操作手册丢给模型且不说浪费 token光是“从中提取当前任务需要的那一段”就容易出错。所以我在 SKILL.md 里会刻意做分层顶部 20 行讲清使用条件中间讲标准流程底部放完整的参数说明和故障排查表。模型根据当前情况决定读到哪一层。这跟新手写文档时“一口气把所有内容全写进 README”的本能是相反的。我在项目里推行了一个原则能放到脚本里的逻辑就不要写进说明能写进说明的人类决策就不要塞进代码。说明文件负责决策树脚本负责执行模型只需要在两者之间当调度员。4.3 多个技能冲突时怎么办当 library 里的技能多起来之后会发现有些请求同时命中两三个技能。比如“帮我把周报整理成 PPT”可能同时触发“周报汇总”和“PPT生成”两个技能。我的处理方式是在技能描述中增加显式的“依赖关系”说明比如在“周报汇总”里写“若用户要求输出 PPT请先运行本技能生成 Markdown再调用 presentation-builder 技能”。Agent 链路就会自然串成一条流水线而不是两个技能在那里争夺主导权。4.4 用测试集来验证技能的“可发现性”技能写得好不好不能靠感觉。我会准备一组典型用户请求比如“汇总这周大家的周报”“看看有没有漏交的周报”“帮我把周报按项目分类统计”然后观察模型是否在正确时机选中正确技能。如果发现某类请求经常漏触发多半是 description 中没有覆盖那种表达方式我会去补同义短语。这里有一个反直觉的点描述里适当包含“用户可能怎么说”的口语化表达确实能提高匹配率并不是在堆关键词。5. 实践中积累的几条硬经验踩坑、边界与维护做到第五个技能包时我开始认真复盘哪些做法真的有用哪些只是自我感动。下面这几条算是我最有把握的经验拿出来分享。5.1 技能膨胀比没有技能更可怕技能包很容易越写越多。头两周我写了十几个技能覆盖各种日常场景结果 agent 的选择速度明显变慢而且经常挑错。后来我痛下决心做了合并和瘦身把能合并成的同一工作流的技能合成一个把低频场景降级为普通脚本只保留真正经常触发且流程稳定的技能。这个道理跟代码重构一样接口少而稳定比接口多而杂更好维护。宋体 可以说技能库的质量边界就是 agent 能力的边界贪多嚼不烂。5.2 版本管理和回滚机制技能是活的业务一变技能就得改。我吃过一次亏某个技能脚本升级后没留旧版结果新逻辑对旧数据不兼容agent 跑出来的结果乱成一锅粥。从那以后我给每个技能包打上了语义化版本号并在关键脚本里加了版本标识和输入输出格式校验。当新版本表现不佳我可以直接回滚到上一个版本而不是对着 git log 找半天“到底上次改了啥”。5.3 安全与授权边界技能能执行脚本、能访问文件系统等于把一部分控制权交给了模型。这个权力的边界必须提前划定。我的原则是技能只能访问显式授权的目录不能把环境变量里的密钥直接打印给模型也不能允许技能脚本执行任意 shell 命令。我在 SKILL.md 里明确写了“禁止将 token 或密钥内容粘贴到聊天中”并且从代码层面挡住这类操作。安全这件事不能指望模型的自觉。5.4 让团队一起维护技能一个人维护技能库会累死也无法覆盖所有业务场景。我现在的做法是每个技能包配一个 owner新技能必须经过 review重点看 description 是否清晰、脚本是否可独立运行、有没有边界风险。团队里不一定人人都懂 AI但大家都看得懂 SKILL.md 的结构因为这个文件本来就是给人写的。把“写技能”变成一种文档文化之后agent 的质量会随着团队知识积累一起成长。6. 技能生态的下一步和我的一点个人习惯说句实话agent-skills 目前在行业里没有一个统一标准。各家框架都有自己的定义方式有的是 JSON 配置有的是 YAML 加脚本有的干脆是纯提示词。但从趋势上看大家往同一个方向走把技能做成交互式的、可被模型发现和执行的资产而不是锁死在某个代码仓库里。我个人的习惯是会优先选择那些支持“技能包”模式的框架因为它们让我能把大部分逻辑沉淀在文件系统层面模型只是那个按图索骥的执行者。最后分享一个小技巧每写一个新技能我都会花十分钟做一次“陌生人测试”。让一个完全没看过这个技能的人只读 SKILL.md然后告诉你这个技能该在什么时候用、怎么用。如果他讲不清楚那模型大概率也讲不清楚这个技能就得重写。把这些细节打磨好agent-skills 才能真正变成你的团队资产而不是一堆会跑但没有人愿意碰的脚本。