Agent Skills完全指南：从原理到实战，打造可复用的AI技能封装-北京尧图网络

前阵子在社区刷到一个让我印象很深的分享有人用 agent 跑完了一整套前端页面评审从骨架屏检查、无障碍标注到性能预算最后连 Lighthouse 报告都自动归档进了项目文档全程半小时不到。评论区问得最多的一个问题是它怎么突然变聪明了答案是agent 本身没变聪明是有人给它装了一组 skills。这个装了一组 skills的动作就是今年 agent 开发圈最值得关注的变化之一。如果你最近在折腾 agent、开发 skills或者只是被AI agent 怎么搭这个话题吸引过来这篇文章就是写给你的。我会从第一性原理讲清楚 agent skills 到底是什么拆解它的运行机制然后手把手带你写一个能真正落地的 skill再聊一聊我在真实项目里踩过的坑。不夸概念只讲怎么用。1. 先弄清楚一件事agent skills 到底解决什么问题1.1 从一次尴尬的对话说起我最早接触 skills 之前用 agent 的方式非常原始把一段又长又细的指令塞进 system prompt告诉它你是一个前端审查专家你要检查以下 12 项内容……。结果有两个问题永远解决不了。第一个是上下文不够用。一份完整的前端审查规范写下来动辄三四千字再加上项目代码、用户需求对话还没开始上下文预算就先烧掉一大块。第二个问题是容易串味。同一个 agent 既要做前端审查又要做会议纪要还要写周报这些指令全堆在一个 system prompt 里模型很容易把审查规范里的表格格式套到周报上输出就变得四不像。skills 解决的就是这两件事把某一个领域的能力封装成一个独立模块按需加载用的时候才展开不用的时候只有一个目录条目占着极其有限的上下文。1.2 skill、prompt、tool、plugin 到底怎么分这里有一个很容易混的概念。我见过很多人在讨论时把 skill、tool、plugin 当成一回事实际上它们的分工完全不一样。概念粒度解决什么问题典型形态prompt一段文本给模型设定角色和语气文字指令tool一个操作执行单次确定性的动作函数调用、API 接口plugin一组扩展给应用集成外部服务安装包、SDKskill一套能力流程指导模型在某个领域内完成多步骤任务SKILL.md 配套文件用生活化的方式比喻tool 是一把螺丝刀每次只负责拧一颗螺丝prompt 是操作员的工作态度说明告诉你要细心、要负责而 skill 是一本《家具组装手册》里面既有步骤说明又有工具清单还有验收标准指导你把一整件家具装出来。所以一个 skill 内部通常会用到多个 tool也会内嵌大量 prompt 式的操作指引。它是更高一层的东西是方法论的可执行封装。1.3 为什么偏偏是现在火起来skills 不是凭空冒出来的。二十年前 IDE 有插件体系五年前浏览器有扩展体系今天 agent 有了自己的插件体系这个体系就是 skills。它火的根本原因是模型自身的通用推理能力已经够强了瓶颈转移到了如何让模型稳定地执行特定领域的标准流程。换句话说一个模型可能知道无障碍评估该看对比度但它不一定每次都想起来要看对比度更不一定知道你们团队要求的对比度阈值是 4.5:1、要在什么工具上验证、报告要按什么模板输出。这些组织内部的确定性知识以前靠人肉写进 prompt现在可以沉淀成一个 skill随用随取。这也是为什么现在不管是主流的 Claude 系工具还是 Codex 这类命令行 coding agent甚至社区里的 Hermes Agent 这类第三方工作台都在用相近的 SKILL.md 格式做能力扩展。大家不约而同走到这条路上说明这不是某个厂商的一时兴起而是 agent 应用走向工程化的必然。2. 第一性原理看 skill 的运行机制2.1 SKILL.md 是入口不是全部一个 skill 在文件系统里通常就是一个目录目录里最核心的文件叫 SKILL.md。它有点像软件的 README但职责比 README 重得多它既是这个 skill 的说明书又是模型理解什么时候该用这个 skill的入口。SKILL.md 的开头是 YAML 格式的 frontmatter里面有几个关键字段我想展开说说因为这里藏着很多问题。--- name: frontend-accessibility-review description: 适用于对 React/Vue 等现代前端项目做无障碍评审检查对比度、焦点管理、ARIA 标注等问题并输出结构化报告。不适用于移动端原生应用的审核。 allowed-tools: - Read - Glob - Grep - Bash license: MIT ---name 是技能的唯一标识。description 是最重要的字段——模型就是靠读 description 来判断当前任务要不要用这个 skill的所以它必须写清楚三件事这个 skill 覆盖什么场景、用什么技术栈、不覆盖什么场景。后面我会专门讲这个字段的写法。allowed-tools 声明的是这个 skill 运行过程中允许调用的工具。这个字段特别重要它本质上是给 skill 划了权限边界。如果一个审查类 skill 不需要写文件就不要放 Write 和 Edit 权限能有效减少 agent 乱改你代码的风险。2.2 渐进式披露上下文是怎么保住的那 SKILL.md 的全量内容会不会占满上下文这就涉及到 skills 机制最核心的设计——渐进式披露progressive disclosure。简单说模型的上下文窗口里只保留 SKILL.md 最前面的摘要区通常是简介和核心步骤的概要大概几百 token。只有当模型判断这个 skill 确实和当前任务相关时它才会按需展开后面的详细章节比如详细检查清单、代码示例、命令模板。这个设计跟读书很像。图书目录只有孤零零的几十行你不会把整本书背在脑子里需要哪一章就翻到哪一章细读。skills 机制把同样的思路搬到了 agent 里一个装了 50 个 skill 的 agent上下文里只有 50 个目录条目不会因为装了 50 个 skill 就把上下文撑爆只在真正执行某个 skill 时才加载它完整的内容。这也是 skills 和往 system prompt 里堆指令之间本质性的区别。前者是懒加载后者是全量常驻。实测下来同样一个带完整审查规范的任务用 skills 的上下文开销大约只有传统写法的三分之一不到。2.3 从请求到技能命中的完整链路理解了渐进式披露就能串起一条完整的调用链了。一次实际请求大概经过这么几步用户提出任务比如检查一下这个页面的无障碍问题。agent 在规划阶段扫描所有已安装 skill 的 description把这个任务和每个 description 做语义匹配。命中一个或多个 skill 后agent 展开对应的 SKILL.md 内容阅读操作步骤和工具配置。agent 按照 skill 里的步骤调用允许的工具逐个执行检查。全部步骤执行完按 skill 里规定的报告格式输出结果。这里面最容易被忽视的是第二步的匹配。它本质上是一次语义检索你写的 description 质量直接决定了匹配的精准度。我和不少同行讨论过这个问题普遍结论是70% 的 skill 失效问题都出在 description 写得太模糊而不是步骤内容写得不好。另外要注意skills 和 MCP模型上下文协议这类东西并不冲突。MCP 解决的是agent 怎么发现并调用外部工具的问题而 skills 解决的是agent 在复杂领域内怎么按方法论把一系列动作组织起来的问题。实践中两者经常配合使用skill 里声明 allowed-tools这些工具可以本身就是通过 MCP 暴露出来的。3. 从零开发一个前端可用性审查skill3.1 先定边界这个 skill 负责哪一段理论聊完直接上手。我选一个你大概率用得到的场景做例子前端可用性审查。选它的原因是流程足够典型——有明确输入、有多步骤检查、有结构化输出非常适合拿来理解 skill 的写法。动手之前先界定边界。一个 skill 千万不要妄图覆盖所有前端问题那样它就会变成一个什么都懂一点、什么都不精的文档。我给我的审查 skill 定了三条边界只针对 Web 页面不做原生移动端应用审核。只做自动化可验证的检查项比如 DOM 结构、对比度、图片 alt、表单标签。输出统一格式的报告方便后续归档和人工复核。边界想清楚后面每一步都顺了。3.2 目录结构和 SKILL.md 的写法一个标准 skill 目录长这样frontend-audit/ ├── SKILL.md ├── scripts/ │ └── contrast_check.py └── templates/ └── report_template.mdSKILL.md 是主入口scripts 里放辅助脚本templates 里放输出模板。目录一多要注意文件路径的写法一律用相对于 SKILL.md 的路径不能写绝对路径。SKILL.md 的正文我强烈建议这样组织先概述再写适用与不适用场景然后列执行步骤每步给检查要点最后给报告模板和验收清单。全文控制在 200 行以内如果超过就需要反省是不是塞了太多不该让模型反复阅读的内容该拆出去的部分放到 reference 文件里。3.3 正文指令怎么写才不会被 agent 忽略我见过不少人写的 skill 正文其实就是一个大号 checklist把所有可能的情况平铺直叙列一遍。这种写法不是不行但效率不高。更好的做法是写成决策流让 agent 每到一个分支点先做个判断再走对应的检查路径。比如对比度检查这一节我不会只写检查文本对比度是否达标而会写成这样获取页面中所有文本节点筛选出前景色和背景色。计算对比度比值注意大号文本的阈值是 3:1普通文本是 4.5:1。若对比度不达标判断文本是否处于禁用态禁用态的文本豁免该项。把不达标项按严重程度分级影响阅读的记 High视觉上不明显但不符合规范的记 Medium。这种写法本质上是把检查方法论给程序化了。模型在 reasoning 方面再强也需要一个明确的执行骨架来减少遗忘和跳步。skill 的价值就在于提供这个骨架。另外步骤里涉及具体命令和工具时直接把命令写出来。能用npx lighthouse --outputjson --output-path./report.json就写全命令不要写运行 Lighthouse 并保存结果后者让 agent 自由发挥的空间太大结果不稳定。3.4 本地验证和迭代skill 写完之后第一件事是先自己读一遍确认描述和步骤没有歧义然后开一个干净的 agent 会话只装这一个 skill丢给它三个测试任务一个能命中的比如审查这个页面的无障碍问题。一个不该命中的比如帮我写一个 Python 爬虫。一个边界任务比如帮我检查一下这个 Vue 项目的可访问性但只需要看表单部分。看它会不会正确触发 skill触发之后执行路径是不是按我写的顺序走的。如果边界任务里它误触发了完整审查流程就去 description 里补充仅检查表单时跳过页面级检查项这样的限定说明。我自己的经验是一个 skill 从初版到可用通常要经过三到五轮这样的迭代。这不是写代码调试的是模型的决策行为所以要有耐心。每轮迭代只改一个变量要么改 description要么改步骤不要同时动两处否则出了问题你根本不知道是哪一处造成的。4. 生态里的真实工作流找、装、评、管4.1 去哪找 skill写自己的 skill 当然好但更多时候我们打开一个 agent 项目第一反应是先看看别人已经沉淀了什么东西。目前 skills 的来源大体上有几条路。官方市场和内置示例是最省心的一类。Claude 系工具带的官方 skills 市场里能直接搜到会议纪要、网页抓取、数据分析这类常用技能Codex 也有自己的 skill 体系社区里甚至出现了一批专门做 skill 聚合的开源仓库GitHub 上搜索 awesome agent skills 就能找到不少。第三方工作台是另一大类。像 Hermes Agent 这类社区工具本质上是把 agent 能力和外部应用比如 Obsidian 这类笔记软件做了打通很多用户会把自己的工作流封装成 skill 分享出来。我逛过不少这类平台里面确实有宝藏但也鱼龙混杂下载之前一定要做评估。4.2 安装和管理方式安装 skill 在大部分实现里就是把目录放到正确的位置这么简单。通常分成两个层级用户级目录放在~/.claude/skills/之类的全局目录下所有项目都能用。项目级目录放在项目内的.claude/skills/下跟着仓库走方便团队共享。具体路径和命令因工具而异最稳妥的方式是看对应工具的文档或者直接看官方市场里的安装说明。我个人的习惯是个人常用的通用 skill 装在用户级和项目强绑定的放项目级。这样切换项目时不会带上一堆无关技能description 匹配的干扰也小。版本管理上如果你把 skills 集中放在一个 git 仓库里统一管理更新和回滚都会轻松很多。我甚至见过有人像管理 dotfiles 一样管理自己的 skills 库这理念我很认同。4.3 判断一个 skill 值不值得装装了不好用的 skill比不装还难受因为它会抢占上下文里的摘要位还可能误触发。我总结了四个筛选维度分享出来维度看什么不合格的信号描述清晰度description 是否明确写了适用和不适用场景没有写不适用场景代码与依赖涉及的脚本、依赖是否声明清楚依赖版本号缺失README 空白权限边界allowed-tools 是否最小化一个只读审查 skill 居然要求 Write 权限可验证性有没有给测试用例或示例输出没有跑通过任何真实任务另外要特别提醒一句别被爆款全网最全这种词带节奏。不少所谓的神级 skill 拆开看就是一个超长 prompt 套了个壳既没有渐进式披露分层也没有工具权限设计。拿我上面四个维度一套水分立刻见分晓。4.4 热门类型一览我整理了一下目前社区里热度比较高的 skill 类型给你一个选装参考类型典型场景为什么火前端开发类代码审查、组件生成、性能诊断流程标准、工具链固定天然适合封装知识库工作流类笔记整理、目录迁移、周报汇总绑定个人知识管理工具复用价值高数据取证类日志分析、数据清洗、报表生成步骤确定、输出格式统一安全评审类依赖漏洞提示、权限配置检查规范性文件多模型容易遗漏细节内容生产类分镜脚本、文章结构化、多平台改写创意流程需要强约束输出格式这里面值得留个心眼的是安全评审相关的技能。安全评估本身是很正当的需求但你下载任何第三方 skill 之前都要看清楚它到底执行什么命令。社区里出现过把敏感文件读取后外传的恶意 skill 案例这个风险我下面会展开讲。5. 我踩过的坑和换来的教训5.1 description 写太宽技能乱接活我最开始写第一个 skill 的时候description 用的是用于处理前端开发相关的各种任务。结果就是我让 agent 写一段 HTML 邮件模板它二话不说调起了审查 skill把一封邮件按完整页面标准审了一遍输出一堆无关紧要的警告。后来我把 description 改成仅用于对现有前端项目做代码与页面层面的静态审查输出问题清单不负责写新代码不适用于纯文案或邮件类任务误触发率立刻降下来了。这背后是 agent 的匹配逻辑决定的。你给模型的 description 越开放它越倾向于在有相关性的任务里启用它给出明确的负向排除项匹配才会收敛。所以写 description 时至少要留三分之一篇幅写不适用的内容。5.2 skill 越更新越大上下文爆掉我的第二个惨痛教训是过度补内容。有一阵子我为了让审查 skill 更全面把团队的编码规范、历史典型问题、各种框架的适配经验全塞了进去SKILL.md 膨胀到 600 多行。效果适得其反。agent 展开这个 skill 之后光读主文档就耗掉上万个 token而且关键步骤淹没在大量背景信息里模型反而更容易漏掉核心检查项。后来我按渐进式披露的原则重构了它主文档只保留执行骨架详细的项目规范全部拆到references/子目录里用单独的引用章节说明当需要检查 React 项目时读取 references/react_checks.md。这样一来普通场景只加载主文档遇到 React 项目才额外加载对应规范文件上下文开销降了一大半。5.3 依赖路径和工具权限的隐藏炸弹还有一个很容易出问题的点是脚本依赖。我的对比度检查脚本依赖 Python 的 colour 库最开始在 SKILL.md 里写了一行运行检查脚本但没写依赖安装方式。结果 agent 执行的时候直接报 ModuleNotFoundError然后它自作聪明地尝试用 pip 装了一堆版本冲突的包最后弄脏了 Python 环境。现在我的做法是把依赖声明写在脚本同目录的 requirements.txt 里在 SKILL.md 的启动步骤里明确写先读取 requirements.txt若依赖缺失则提示用户手动确认安装不得擅自安装全局依赖。这一步看似多余实际上能救回很多次被 agent 搞坏的环境。5.4 多 skill 相互踩踏的问题装上十几个 skill 之后新的问题出现了多个 skill 的职责范围有重叠。比如我有一个前端审查skill还有一个项目健康检查skill两个都包含检查依赖版本这个步骤。有一次 agent 同时命中了两个对同一份 package.json 各查了一遍产出两份格式不同的报告还互相矛盾。我的处理方案是两个一是给重叠的部分建立引用关系而不是重复编写让其中一个 skill 在对应步骤里写明该步骤复用 frontend-audit 技能的 3.2 节不要重复执行二是在 description 里各自声明边界如已有其他技能覆盖依赖检查跳过本技能的对应步骤。经过这样的梳理踩踏问题基本消失了。5.5 权限失控差点丢了文件最后一个坑也是最重要的一个权限。我在一个社区下载的自动归档skill 里发现它的 allowed-tools 包含 Bash 和 Write但具体命令里有一条find . -type f -exec sed -i s/pattern/replacement/g {} 这条命令的作用范围是整个项目目录。我是在沙盒环境里做演练时发现的要是直接放在生产仓库里跑后果不堪设想。从那以后我养成了三个习惯第一任何第三方 skill 装进来之后先逐行读一遍里面出现的所有命令第二检查 allowed-tools凡是不匹配最小权限原则的一律不装或手动收紧第三在本地沙盒目录里先跑一个测试任务观察它有没有触碰超出任务范围的文件。这些习惯花不了多少时间但能挡住绝大多数潜在风险。6. 从单 agent 到多 agentskill 在整个格局里的位置6.1 轻量技能 vs 独立 agent在聊多 agent 之前需要先厘清 skill 和 agent 的关系。我在圈子里经常看到两种极端观点一种说以后不需要 agent 了装几个 skill 就够另一种说skill 就是花架子真正干活的还得靠独立 agent。这两种说法都不算错但都不完整。skill 的优势在于轻量和复用它是能力模块不持有记忆不维护会话状态随装随用。agent 的优势在于自主和连续它有自己的目标、记忆和循环决策能力。正确的理解是skill 是 agent 的职业技能包agent 是拥有职业角色的工作者。一个 agent 可以装配多个 skill 来扩展自己的职业范围而一个 skill 也可以被多个 agent 共享使用。举一个实际的架构例子。我的一个内部分析项目里有一个编排型 agent 负责任务理解、拆解和调度三个执行型 agent 分别负责数据获取、前端页面分析、报告编写。三个执行型 agent 各自装配了 2-3 个专门的 skill而数据获取这个 skill 同时被编排型 agent 和报告 agent 引用因为它们都需要拉取同一种格式的原始数据。这个结构跑下来非常顺。6.2 框架、编排和 skill 共享多 agent 场景里框架和编排层是绕不开的话题。现在主流的 agent 框架大多支持把 skill 作为一等公民来管理也就是说你可以在框架配置里声明每个 agent 挂载哪些 skillskill 的加载和切换由编排层统一处理。这种设计带来的直接收益有两方面。第一是 token 经济性好多个 agent 共享同一个 skill不需要把 skill 内容复制到每个 agent 的 system prompt 里而是各自按需加载整体 token 消耗显著下降。第二是维护成本低一个技能更新所有挂载它的 agent 自动用上新版本不需要逐个去改提示词。我踩过的多 agent 相关的坑主要是技能漂移——几个 agent 各自微调了同一份 skill 的副本最后互相不一致。后来我把常用 skill 提升为一个公共包通过 git submodule 或依赖管理方式统一引用问题才根治。多 agent 系统的工程味儿从管理 skill 的方式上就能看出来。6.3 还有什么值得继续折腾如果你决定往 agent skills 这个方向深入我个人建议的下一步是三件事。第一给团队的 skill 建一个评测集。收集 10-20 个典型任务每次改完 skill 就跑一遍评测集看命中率和输出质量有没有变化。这比靠印象判断靠谱得多也是我迭代 skill 时最依赖的手段。第二关注 skills 标准和互联互通。目前各家格式趋同但还没完全统一SKILL.md 的影响力在扩大Codex 也在用相近的约定。在这个窗口期尽早把你们的技能资产沉淀成标准结构将来迁移成本会很低。第三保持对安全边界的敏感。技能越强大权限越要收敛。我给自己的底线是任何 skill 在真正进入生产环境之前都必须过一遍命令审计和权限审计这个环节不可省略。回头看我这一路从往 prompt 里塞指令到建立第一条技能流水线最大的感受是agent 能力的上限确实由模型决定但它能力的下限其实是由你给它装了什么 skills 决定的。一个装了劣质 skill 的 agent上限再高也会低级失误一个 skill 体系打理得干净有序的 agent才是真正能放进工作流里长期信任的合作伙伴。最后分享一个实际操作中的小诀窍给每个 skill 都写一句触发这个技能前必须满足的条件放在 description 第一行。比如仅当用户明确要求自动化页面检查时启用。这一句话能让你的技能误触发率再降一个数量级。

Agent Skills完全指南：从原理到实战，打造可复用的AI技能封装

相关推荐

Agent-Reach 实战：CLI AI Agent 框架从安装到工具调用

MySQL日志查询全攻略：从错误日志、binlog到慢查询优化实战

RK3588多路视频监控实战：VPU硬解+RGA转换+GPU渲染全解析

更多资讯

多智能体框架实战指南：从五万九千颗Star到跑通流水线

Vulkan稀疏资源实战：从内存分配到流式加载的显存优化指南

电网故障下三相并网变流器控制策略：正负序分离与故障穿越

LangChain智能体Webhook通知：规则触发与回调机制实战

加权平衡截断：核函数指数和近似的模型降阶加速方法

学习日志（第二篇）：Python爬虫实操与复盘方法论

今日更新

基于sEMG与IMU的手语手势识别：从数据采集到实时部署避坑指南

装配车间MES落地指南：SimpleMES工单流转、BOM与齐套检查实战

AI获客怎样减少重复线索？意客AI的原文复用与版本筛选

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？