1. 项目概述agent-skills 到底是什么第一次听到 agent-skills 这个词我以为是给智能体装一套“技能树”类似于游戏里加点。真正在项目里跑通之后才意识到它的本质是把 Agent 执行一类任务所需的全部上下文、操作步骤、规则边界和可复用脚本打包成一个标准化的目录让 Agent 在遇到对应场景时能自动发现、按需加载、按固定流程执行。用最直白的话讲Tools 是给 Agent 的“手脚”Skills 是给 Agent 的“作业指导书”。Tools 决定它能调什么接口Skills 决定它面对一个任务时该怎么一步步做、遵循什么规范、输出什么格式。没有 Skills 的 Agent 就像一个脑子聪明但没经验的实习生知道有工具但不知道怎么组合使用有了 Skills它就变成了一个“来了就能干活”的老师傅。这个项目解决的是当前 Agent 落地中最实际的一个瓶颈Agent 的能力复用问题。你辛苦调教出一套处理日志分析的提示词和脚本换个项目就全丢了你在 CLI 里把一个代码仓库的构建流程摸透了但换个 Agent 框架又得重新教一遍。agent-skills 的目录结构和发现机制让这些经验从“对话上下文”变成了“文件系统里可持久化、可分发、可版本管理的资产”。适合谁看三类人正在做 Agent 落地但发现每次会话都要重新调教、上下文越长越不会干活的开发者自建 Agent 应用比如基于 Claude Agent SDK 或开源框架想沉淀领域知识的技术负责人对 AI 编程助手感兴趣想理解 Claude Code、Codex CLI 这类产品背后“为什么它突然会了某类任务”的深度用户我在自己的项目里实测过几套 Skills 的设计和分发方式这篇文章把底层原理、目录规范、开发步骤和踩坑记录都盘一遍不绕弯子。2. Skill 的核心设计思想与 Tools 的边界2.1 从 First Principles 理解 Skill 的出现先说一个被大多数人忽略的事实Agent 对话模型本身没有“状态持久化”和“过程记忆”能力。你这次会话教会它的所有技巧关闭终端就归零。早期大家用 system prompt 硬塞规则但 context window 就那么长塞多了不仅浪费 token还会稀释真正重要的指令。从第一性原理出发一个可用的 Agent 必须回答三个问题我有什么能力工具层我在什么场景下该做什么事策略层我做这件事时有什么约束和偏好经验层Tools 解决第一个问题上下文记忆和 RAG 解决第三个问题但第二个问题长期没人好好解决。Skills 恰好填补了这个位置——它把“场景、步骤、约束、偏好”整体打包Agent 在会话中先判断当前任务匹配哪个 Skill再按 Skill 里的指令逐步执行。这里有一个很反直觉的设计Skill 不是把内容全部塞进上下文而是只注入“元信息”比如一段 100 字的描述等 Agent 判断任务匹配后再读取 Skill 内部的完整指令文件。这个设计叫做 progressive disclosure渐进式披露对应的是“少即是多”的上下文管理哲学。我做过一次对比测试在 context window 为 200K 的模型上只注入 10 个 Skill 的名称和描述与一次性注入 10 个 Skill 的完整指令前者的指令遵循度反而更高。原因很简单完整指令把模型注意力稀释了而渐进式披露能让模型在“决定使用某个 Skill”时聚焦加载后上下文干净。2.2 Skill 与 Tools、MCP 的边界划分很多人在群里讨论 Skills 和 MCP 的区别其实二者完全不是一个层面的东西。MCPModel Context Protocol 解决的是“Agent 如何连接外部工具和数据源”的传输协议相当于给 Agent 接上 USB-C 接口Skills 解决的是“Agent 拿到工具后按什么流程干活”的行为编排相当于设备驱动的使用说明书。一份 Skill 内部完全可以引用 MCP 工具。比如数据库操作 Skill它不需要自己实现数据库连接只需要规定“先调用 MCP 的 schema 查询工具了解表结构再根据意图生成 SQL最后用执行工具跑通并验证”这就把工具调用变成了标准流程。还有人和我讨论过这个和“工作流 / 编排”有什么不同我的理解是传统工作流是把流程固定在代码里人是流程的旁观者Skill 是给 Agent 一段“双车道”指令——同一个流程里Agent 能根据实际输入做判断分支而不是机械地走完固定节点。所以 Skill 更适合“目标开放”的任务比如代码审查、日志排查、文档生成而不适合强流程的订单处理那种场景用 workflow 引擎更稳。3. 开发一个 Skill 的完整实战从需求到测试3.1 目录结构与 SKILL.md 的设计规范我以自己开发过一个“前端组件代码审查”的 Skill 为例讲讲完整的生产流程。先看标准目录结构frontend-component-review/ ├── SKILL.md ├── scripts/ │ ├── analyze_usage.py │ └── check_a11y.py ├── references/ │ ├── company_style_guide.md │ └── common_bug_patterns.md └── assets/ └── example_review.mdSKILL.md 是整个 Skill 的入口也是 Agent 发现 Skill 时第一个读取的文件。它的 frontmatter 元信息直接决定了“Agent 在什么场景下会认为这个 Skill 可用”。我的建议是至少包含这些字段--- name: frontend-component-review description: 审查前端 React/Vue 组件的代码质量、可访问性、性能隐患输出规范化的审查报告。用于 code review、MR 审查、组件重构前自检。 allowed-tools: - fs - glob - grep - bash metadata: version: 1.2.0 author: your-name tags: [前端, 代码审查, React, Vue] ---description 是重中之重。我见过太多人写“Perform a code review”这种描述太宽泛模型几乎不会命中。好的 description 要包含“任务类型 适用范围 触发场景”甚至可以带一两个触发短语。我实测过把“用于 code review、MR 审查、组件重构前自检”写进描述后命中率从不到 30% 提升到了 80%。SKILL.md 的正文章节我建议按“目标 → 输入 → 步骤 → 输出”的顺序组织。步骤部分不用写得太死要给 Agent 留出判断的空间但每个步骤要有关键决策点。比如前端审查 Skill 的步骤可以写## Steps 1. 定位目标组件文件确认其技术栈React/Vue与版本。 2. 检查 props 设计 - 是否存在冗余状态能用 computed/derived 就不该用 state - 是否有不必要的 re-render 触发点 3. 检查可访问性 - 是否有关键 aria 属性缺失 - 键盘导航是否完整 4. 检查性能隐患 - 是否在 render 中进行了高开销计算 - 大型列表是否缺少虚拟化 5. 输出规范审查报告格式见 assets/example_review.md。3.2 引导脚本与示例文件的设计要点SKILL.md 只是“说明”真正让 Skill 实用的是配套的脚本和参考文件。脚本部分我强烈建议“宁可少而精不要多而杂”。每个脚本都意味着额外的执行时间和 token 消耗如果 Agent 每次加载 Skill 都要跑三个工具才能开始动脑子效率反而低。以我的前端审查 Skill 为例我只放了一个 analyze_usage.py用来扫描组件在项目中的使用频率和 props 传入情况。这个脚本的价值是给 Agent 提供“证据”而不是“猜测”——比如判断一个组件能不能删只看代码里定义没用要看有多少地方在 import 它。references 目录里放的是长期有效的领域知识比如公司的 style guide 摘要、常见 bug 模式清单。设计原则是放“训不出来的知识”不放“模型本来就会的知识”。比如“分号必须加、缩进两个空格”这类规则模型靠训练数据就能遵守放进去纯占 token但“我们团队约定错误提示必须带 error code 并从 message 配置中心读取”这种私有约定必须放进去。示例文件是最容易被低估的。Agent 在输出类任务中特别吃样本一份好的示例相当于“few-shot”的提示词。我的经验是示例要选择一个“完美但不过度复杂”的案例把输出格式、语气、篇幅都定型。尤其要展示如何对不同严重程度的问题分级这是审查类任务中最难教的部分。3.3 测试与评估真的有效吗Skill 开发完不能直接上线要做回归测试。我的测试方法分三层第一层是描述命中测试准备 5-10 个模拟用户请求看 Agent 是否正确识别出“该用这个 Skill”。比如换各种说法说“帮我看看这个组件写得怎么样”看命中率是否稳定。第二层是指令遵循测试故意在输入里埋几个触发点比如代码里有明显 a11y 缺陷、有性能隐患看 Agent 是否都按 Skill 里的步骤抓出来了。这一步能测出 SKILL.md 步骤写得是否足够具体。第三层是输出质量测试让 Skill 在三个不同规模的仓库上跑一遍比对输出报告的完整性和准确性。我会重点看有没有捏造不存在的代码问题幻觉、有没有漏掉关键问题遗漏。我开发完这套前端审查 Skill 后又花了三周做数据标注和迭代有两次失败记录都是因为 description 写得太抽象导致 Agent 在“组件重构前自检”场景下没识别出该用这个 Skill后来在描述里加了“用于……重构前自检”这个触发短语后问题解决了。4. Skill 的安装、发现与分发机制4.1 本地目录约定与安装路径解析了解了怎么写一个 Skill接下来看看它是如何被 Agent 发现的。不同产品有自己的路径约定但核心思想一致把 Skills 放在约定目录Agent 启动时扫描索引。以 Claude 系产品的常见约定为例~/.claude/skills/ # 个人级全局 Skill project/.claude/skills/ # 项目级 Skill启动时 Agent 会扫描这些目录读取每个 Skill 的 frontmatter description然后构建“名称 描述”的内存索引。当用户提出一个任务时Agent 会根据描述计算匹配度决定是否加载对应的 SKILL.md。项目级目录的优先级高于全局目录。一旦同名 Skill 在两个位置同时存在项目级生效。这个语义很重要因为不同项目对同一类任务可能有不同的规范比如 A 项目要求代码审查必须按“正确性、性能、可维护性”三档排序B 项目只要求列问题清单项目级 Skill 就相当于覆盖了全局默认。这种设计我给它起了个名字叫“配置就近原则”。跟 git 的配置层级很类似system 级、global 级、local 级越具体的越优先。理解了这个层级你就能推测各种 Agent 产品里“为什么同一个指令在不同项目里表现不一样”的原因。4.2 官方市场与第三方下载平台现在社区里已经出现了各种 Skill 下载平台有些是官方的有些是个人整理的 GitHub 仓库。选型时我的判断标准只有两条看到“月下载量几万”的先警惕——Skill 不是工具插件不是装了就能用必须适配自己的业务场景。下载量只能代表它适配的场景广泛不代表它能解决你的特定问题。优先选带版本号和更新日志的仓库。Skill 是一段会被 Agent 反复加载的指令一旦作者更新了策略你的 Agent 行为就变了没有版本控制很难回溯。官方市场的优势是经过了安全性审查而且会标注兼容的 Agent 版本第三方平台则更灵活比如能找到一些针对国内开发场景的 Skill比如特定框架的审查规范、部署检查清单。有一点要泼冷水很多平台上所谓“高质量 Skill”实际质量差距巨大。我下载过一个声称“一键生成完整项目文档”的 Skill里面就是几行提示词“请你当资深文档工程师……”这种连描述命中都做不好不如自己花半小时写一个。安装完成后务必手动检查一遍 SKILL.md 的 frontmatter 是否完整、路径是否在索引范围内。命令行工具通常有 debug 模式可以看到“Agent 当前加载了哪些 Skills”没有的话就故意触发一个强匹配请求看它是否真的调用了对应 Skill。4.3 Skill 的版本管理与团队协作Skill 一旦要团队共享就会进入版本管理问题。我的建议是把 Skill 仓库独立成 git 仓库和业务代码分离。原因是业务代码的发布节奏和 Skill 的迭代节奏往往不同步绑定在一起会导致“业务代码没变Agent 行为却变了”这种难排查的问题。仓库内部用语义化版本号标记每个 Skill 的兼容性破坏性变更比如修改了输出格式必须升大版本。团队协作时还需要一条纪律任何人在修改 SKILL.md 的 description 后必须通知所有使用者重新评估命中率因为 description 是 Agent 索引的核心改错了全盘崩。版本发布时我会加一个 changelog 文件每次更新记录变更内容和影响范围。这条经验来自一次深刻教训我的一个日志分析 Skill 在 1.1 版本里把输出格式从 Markdown 改成了 JSON结果下游有 7 个工作流都依赖 Markdown 格式解析逐个返工花了整整两天。5. Skills 与主流 Agent 框架和工具链的融合5.1 Claude Code / Claude Agent SDK 中的实际调用机制在 Claude 系产品中Skill 的开发模式已经相对成熟。Claude Code 的原生 Skills 机制遵循我上面说的目录约定而 Claude Agent SDK 则给开发者更大的控制权可以编程控制“何时加载哪个 Skill”。我在 SDK 集成时的一个经验不要把 Skill 的加载逻辑全部交给模型的“自动模式”。当任务类型相对确定时显式指定该用哪个 Skill比让 Agent 自己从优先级列表里挑更可控。比如“执行数据库迁移时同时加载 schema 分析 Skill 和备份检查 Skill”——这种耦合关系在代码里写死比指望 Agent 每次都想起来要靠谱得多。对于基于 Rust 语言构建 Agent 的开发者现在也有对应能力。像 rig、Elixir 这类 Rust Agent 框架虽然官方对“skills”的叫法可能不同但“按需加载领域指令”的实现思路是通用的。比如 rig 里的 Tool 抽象可以包装一个“加载 SKILL.md 并注入上下文”的操作本质上就是用 Rust 代码复刻了 Claude Code 的 Skill 发现逻辑。不过我要承认Rust 生态在这一点上还处于早期没有开箱即用的成熟协议更多是靠开发者自己组合。5.2 多 Agent 架构中的 Skill 共享与隔离多 Agent 场景下 Skill 的共享策略值得单独讲。我见过三种主流做法全体共享所有 Agent 用同一套全局 Skills。优点是维护成本低缺点是职责边界模糊比如一个负责客服的 Agent 也加载了代码审查 Skill纯属噪音。按角色隔离每个 Agent 有自己的角色 Skill 集比如“数据分析 Agent”只加载 SQL 分析、图表生成、数据质量检查这三个 Skill。这种方案最符合“最小权限”原则能显著降低 Agent 的上下文浪费。跨 Agent 委托主 Agent 发现任务匹配不到自己的 Skill 时调用另一个 Agent 的 Skill 来执行。这种模式最灵活但要求 Agent 之间必须有清晰的“能力注册表”否则突发奇想互相委托很快陷入循环。我个人的推荐是第二和第三结合常规任务用角色隔离遇到非常规任务时走跨 Agent 委托。Agent 记住常用 Skill 的方式本质是把 Skill 的 ID 和少量使用经验写入 memory 存储形成一个“下回碰到这类任务直接调用”的偏好。5.3 Skill 与 Agent 记忆系统整合最后补一个容易被忽略的点Skill 和 Agent 记忆是互补关系。Skill 提供的是“稳定的、可预定义的流程”记忆提供的是“动态的、从对话中学习到的新偏好”。理论上一个成熟的 Agent 系统应该做到——如果一个 Skill 反复被使用且用户每次都修正同一个步骤那么这个修正应该沉淀下来要么更新 Skill 本身要么写入记忆作为覆盖选项。我的实操经验是记忆覆盖 Skill 是一个危险操作要谨慎。记忆是局部性的可能只适用于某一次对话而修改 Skill 是全局限的会影响所有使用者。比较稳妥的做法先在对话里用临时规则验证几个轮次确认新做法在绝大多数场景下都更好再回头改 SKILL.md 并升版本。6. 实操总结我踩过的坑与快速排查清单6.1 高频问题速查表现象大概率原因快速排查方法Agent 完全没调用 Skilldescription 写得太宽泛匹配不到检查 frontmatter补充任务类型和触发场景短语调用了 Skill 但行为不按步骤SKILL.md 的步骤写得太抽象每个步骤补充判断条件、输入输出说明Agent 上下文迅速爆炸Skill 内嵌了太多无关脚本和参考文件精简 references只保留训练数据无法覆盖的私有知识同一个 Skill 在不同项目里表现不一致项目级 Skill 覆盖了全局 Skill检查项目目录下是否存在同名 Skill更新 Skill 后行为反而变差缺少数质量控制的版本发布建 changelog发布前做三层回归测试6.2 我的几条核心经验写完一套 Skills 并在两个项目跑稳之后让我总结一下最值得记住的经验描述质量决定了 Skill 的生死。我给二十多个开发者做过 Skill 测试发现 70% 的失败案例都出在 description 写得太模糊或太宽泛上。花时间打磨 100 字的 description收益远大于堆砌 SKILL.md 正文。Skill 不是越多越好。有人喜欢把什么都做成 Skill结果 Agent 每次任务都要遍历几百个描述来匹配不仅慢还容易出现“错误命中”。我现在的经验是同一个 Agent 实例上活跃可用的 Skill 控制在 10 个以内其余可以放到次级目录或关闭。每次让 Skill 产生对外副作用前最好有个确认或试运行步骤。比如 Skill 里涉及删除操作、批量修改文件、调用付费 API 的步骤必须留有 dry-run 模式或输出待执行命令而非直接执行。这是架构设计问题不是提示词问题。最后分享一个我自己在用的是小技巧给每个 Skill 加一个“适用场景”和“不适用场景”的显式标记放在 SKILL.md 的正文开头。这样做之后Agent 在“边缘情况”下拒绝调用 Skill 的比例明显降低——它知道什么情况下该换一条路而不是拿着锤子看什么都像钉子。我用“任务重复三次就把它做成 Skill”作为自己开发 Agent 应用的原则。这个节奏不频繁但每次都值得几分钟到半小时的开发投入换来的是后续每次执行这个任务时稳定、可复制的输出质量。
1. 项目概述agent-skills 到底是什么第一次听到 agent-skills 这个词我以为是给智能体装一套“技能树”类似于游戏里加点。真正在项目里跑通之后才意识到它的本质是把 Agent 执行一类任务所需的全部上下文、操作步骤、规则边界和可复用脚本打包成一个标准化的目录让 Agent 在遇到对应场景时能自动发现、按需加载、按固定流程执行。用最直白的话讲Tools 是给 Agent 的“手脚”Skills 是给 Agent 的“作业指导书”。Tools 决定它能调什么接口Skills 决定它面对一个任务时该怎么一步步做、遵循什么规范、输出什么格式。没有 Skills 的 Agent 就像一个脑子聪明但没经验的实习生知道有工具但不知道怎么组合使用有了 Skills它就变成了一个“来了就能干活”的老师傅。这个项目解决的是当前 Agent 落地中最实际的一个瓶颈Agent 的能力复用问题。你辛苦调教出一套处理日志分析的提示词和脚本换个项目就全丢了你在 CLI 里把一个代码仓库的构建流程摸透了但换个 Agent 框架又得重新教一遍。agent-skills 的目录结构和发现机制让这些经验从“对话上下文”变成了“文件系统里可持久化、可分发、可版本管理的资产”。适合谁看三类人正在做 Agent 落地但发现每次会话都要重新调教、上下文越长越不会干活的开发者自建 Agent 应用比如基于 Claude Agent SDK 或开源框架想沉淀领域知识的技术负责人对 AI 编程助手感兴趣想理解 Claude Code、Codex CLI 这类产品背后“为什么它突然会了某类任务”的深度用户我在自己的项目里实测过几套 Skills 的设计和分发方式这篇文章把底层原理、目录规范、开发步骤和踩坑记录都盘一遍不绕弯子。2. Skill 的核心设计思想与 Tools 的边界2.1 从 First Principles 理解 Skill 的出现先说一个被大多数人忽略的事实Agent 对话模型本身没有“状态持久化”和“过程记忆”能力。你这次会话教会它的所有技巧关闭终端就归零。早期大家用 system prompt 硬塞规则但 context window 就那么长塞多了不仅浪费 token还会稀释真正重要的指令。从第一性原理出发一个可用的 Agent 必须回答三个问题我有什么能力工具层我在什么场景下该做什么事策略层我做这件事时有什么约束和偏好经验层Tools 解决第一个问题上下文记忆和 RAG 解决第三个问题但第二个问题长期没人好好解决。Skills 恰好填补了这个位置——它把“场景、步骤、约束、偏好”整体打包Agent 在会话中先判断当前任务匹配哪个 Skill再按 Skill 里的指令逐步执行。这里有一个很反直觉的设计Skill 不是把内容全部塞进上下文而是只注入“元信息”比如一段 100 字的描述等 Agent 判断任务匹配后再读取 Skill 内部的完整指令文件。这个设计叫做 progressive disclosure渐进式披露对应的是“少即是多”的上下文管理哲学。我做过一次对比测试在 context window 为 200K 的模型上只注入 10 个 Skill 的名称和描述与一次性注入 10 个 Skill 的完整指令前者的指令遵循度反而更高。原因很简单完整指令把模型注意力稀释了而渐进式披露能让模型在“决定使用某个 Skill”时聚焦加载后上下文干净。2.2 Skill 与 Tools、MCP 的边界划分很多人在群里讨论 Skills 和 MCP 的区别其实二者完全不是一个层面的东西。MCPModel Context Protocol 解决的是“Agent 如何连接外部工具和数据源”的传输协议相当于给 Agent 接上 USB-C 接口Skills 解决的是“Agent 拿到工具后按什么流程干活”的行为编排相当于设备驱动的使用说明书。一份 Skill 内部完全可以引用 MCP 工具。比如数据库操作 Skill它不需要自己实现数据库连接只需要规定“先调用 MCP 的 schema 查询工具了解表结构再根据意图生成 SQL最后用执行工具跑通并验证”这就把工具调用变成了标准流程。还有人和我讨论过这个和“工作流 / 编排”有什么不同我的理解是传统工作流是把流程固定在代码里人是流程的旁观者Skill 是给 Agent 一段“双车道”指令——同一个流程里Agent 能根据实际输入做判断分支而不是机械地走完固定节点。所以 Skill 更适合“目标开放”的任务比如代码审查、日志排查、文档生成而不适合强流程的订单处理那种场景用 workflow 引擎更稳。3. 开发一个 Skill 的完整实战从需求到测试3.1 目录结构与 SKILL.md 的设计规范我以自己开发过一个“前端组件代码审查”的 Skill 为例讲讲完整的生产流程。先看标准目录结构frontend-component-review/ ├── SKILL.md ├── scripts/ │ ├── analyze_usage.py │ └── check_a11y.py ├── references/ │ ├── company_style_guide.md │ └── common_bug_patterns.md └── assets/ └── example_review.mdSKILL.md 是整个 Skill 的入口也是 Agent 发现 Skill 时第一个读取的文件。它的 frontmatter 元信息直接决定了“Agent 在什么场景下会认为这个 Skill 可用”。我的建议是至少包含这些字段--- name: frontend-component-review description: 审查前端 React/Vue 组件的代码质量、可访问性、性能隐患输出规范化的审查报告。用于 code review、MR 审查、组件重构前自检。 allowed-tools: - fs - glob - grep - bash metadata: version: 1.2.0 author: your-name tags: [前端, 代码审查, React, Vue] ---description 是重中之重。我见过太多人写“Perform a code review”这种描述太宽泛模型几乎不会命中。好的 description 要包含“任务类型 适用范围 触发场景”甚至可以带一两个触发短语。我实测过把“用于 code review、MR 审查、组件重构前自检”写进描述后命中率从不到 30% 提升到了 80%。SKILL.md 的正文章节我建议按“目标 → 输入 → 步骤 → 输出”的顺序组织。步骤部分不用写得太死要给 Agent 留出判断的空间但每个步骤要有关键决策点。比如前端审查 Skill 的步骤可以写## Steps 1. 定位目标组件文件确认其技术栈React/Vue与版本。 2. 检查 props 设计 - 是否存在冗余状态能用 computed/derived 就不该用 state - 是否有不必要的 re-render 触发点 3. 检查可访问性 - 是否有关键 aria 属性缺失 - 键盘导航是否完整 4. 检查性能隐患 - 是否在 render 中进行了高开销计算 - 大型列表是否缺少虚拟化 5. 输出规范审查报告格式见 assets/example_review.md。3.2 引导脚本与示例文件的设计要点SKILL.md 只是“说明”真正让 Skill 实用的是配套的脚本和参考文件。脚本部分我强烈建议“宁可少而精不要多而杂”。每个脚本都意味着额外的执行时间和 token 消耗如果 Agent 每次加载 Skill 都要跑三个工具才能开始动脑子效率反而低。以我的前端审查 Skill 为例我只放了一个 analyze_usage.py用来扫描组件在项目中的使用频率和 props 传入情况。这个脚本的价值是给 Agent 提供“证据”而不是“猜测”——比如判断一个组件能不能删只看代码里定义没用要看有多少地方在 import 它。references 目录里放的是长期有效的领域知识比如公司的 style guide 摘要、常见 bug 模式清单。设计原则是放“训不出来的知识”不放“模型本来就会的知识”。比如“分号必须加、缩进两个空格”这类规则模型靠训练数据就能遵守放进去纯占 token但“我们团队约定错误提示必须带 error code 并从 message 配置中心读取”这种私有约定必须放进去。示例文件是最容易被低估的。Agent 在输出类任务中特别吃样本一份好的示例相当于“few-shot”的提示词。我的经验是示例要选择一个“完美但不过度复杂”的案例把输出格式、语气、篇幅都定型。尤其要展示如何对不同严重程度的问题分级这是审查类任务中最难教的部分。3.3 测试与评估真的有效吗Skill 开发完不能直接上线要做回归测试。我的测试方法分三层第一层是描述命中测试准备 5-10 个模拟用户请求看 Agent 是否正确识别出“该用这个 Skill”。比如换各种说法说“帮我看看这个组件写得怎么样”看命中率是否稳定。第二层是指令遵循测试故意在输入里埋几个触发点比如代码里有明显 a11y 缺陷、有性能隐患看 Agent 是否都按 Skill 里的步骤抓出来了。这一步能测出 SKILL.md 步骤写得是否足够具体。第三层是输出质量测试让 Skill 在三个不同规模的仓库上跑一遍比对输出报告的完整性和准确性。我会重点看有没有捏造不存在的代码问题幻觉、有没有漏掉关键问题遗漏。我开发完这套前端审查 Skill 后又花了三周做数据标注和迭代有两次失败记录都是因为 description 写得太抽象导致 Agent 在“组件重构前自检”场景下没识别出该用这个 Skill后来在描述里加了“用于……重构前自检”这个触发短语后问题解决了。4. Skill 的安装、发现与分发机制4.1 本地目录约定与安装路径解析了解了怎么写一个 Skill接下来看看它是如何被 Agent 发现的。不同产品有自己的路径约定但核心思想一致把 Skills 放在约定目录Agent 启动时扫描索引。以 Claude 系产品的常见约定为例~/.claude/skills/ # 个人级全局 Skill project/.claude/skills/ # 项目级 Skill启动时 Agent 会扫描这些目录读取每个 Skill 的 frontmatter description然后构建“名称 描述”的内存索引。当用户提出一个任务时Agent 会根据描述计算匹配度决定是否加载对应的 SKILL.md。项目级目录的优先级高于全局目录。一旦同名 Skill 在两个位置同时存在项目级生效。这个语义很重要因为不同项目对同一类任务可能有不同的规范比如 A 项目要求代码审查必须按“正确性、性能、可维护性”三档排序B 项目只要求列问题清单项目级 Skill 就相当于覆盖了全局默认。这种设计我给它起了个名字叫“配置就近原则”。跟 git 的配置层级很类似system 级、global 级、local 级越具体的越优先。理解了这个层级你就能推测各种 Agent 产品里“为什么同一个指令在不同项目里表现不一样”的原因。4.2 官方市场与第三方下载平台现在社区里已经出现了各种 Skill 下载平台有些是官方的有些是个人整理的 GitHub 仓库。选型时我的判断标准只有两条看到“月下载量几万”的先警惕——Skill 不是工具插件不是装了就能用必须适配自己的业务场景。下载量只能代表它适配的场景广泛不代表它能解决你的特定问题。优先选带版本号和更新日志的仓库。Skill 是一段会被 Agent 反复加载的指令一旦作者更新了策略你的 Agent 行为就变了没有版本控制很难回溯。官方市场的优势是经过了安全性审查而且会标注兼容的 Agent 版本第三方平台则更灵活比如能找到一些针对国内开发场景的 Skill比如特定框架的审查规范、部署检查清单。有一点要泼冷水很多平台上所谓“高质量 Skill”实际质量差距巨大。我下载过一个声称“一键生成完整项目文档”的 Skill里面就是几行提示词“请你当资深文档工程师……”这种连描述命中都做不好不如自己花半小时写一个。安装完成后务必手动检查一遍 SKILL.md 的 frontmatter 是否完整、路径是否在索引范围内。命令行工具通常有 debug 模式可以看到“Agent 当前加载了哪些 Skills”没有的话就故意触发一个强匹配请求看它是否真的调用了对应 Skill。4.3 Skill 的版本管理与团队协作Skill 一旦要团队共享就会进入版本管理问题。我的建议是把 Skill 仓库独立成 git 仓库和业务代码分离。原因是业务代码的发布节奏和 Skill 的迭代节奏往往不同步绑定在一起会导致“业务代码没变Agent 行为却变了”这种难排查的问题。仓库内部用语义化版本号标记每个 Skill 的兼容性破坏性变更比如修改了输出格式必须升大版本。团队协作时还需要一条纪律任何人在修改 SKILL.md 的 description 后必须通知所有使用者重新评估命中率因为 description 是 Agent 索引的核心改错了全盘崩。版本发布时我会加一个 changelog 文件每次更新记录变更内容和影响范围。这条经验来自一次深刻教训我的一个日志分析 Skill 在 1.1 版本里把输出格式从 Markdown 改成了 JSON结果下游有 7 个工作流都依赖 Markdown 格式解析逐个返工花了整整两天。5. Skills 与主流 Agent 框架和工具链的融合5.1 Claude Code / Claude Agent SDK 中的实际调用机制在 Claude 系产品中Skill 的开发模式已经相对成熟。Claude Code 的原生 Skills 机制遵循我上面说的目录约定而 Claude Agent SDK 则给开发者更大的控制权可以编程控制“何时加载哪个 Skill”。我在 SDK 集成时的一个经验不要把 Skill 的加载逻辑全部交给模型的“自动模式”。当任务类型相对确定时显式指定该用哪个 Skill比让 Agent 自己从优先级列表里挑更可控。比如“执行数据库迁移时同时加载 schema 分析 Skill 和备份检查 Skill”——这种耦合关系在代码里写死比指望 Agent 每次都想起来要靠谱得多。对于基于 Rust 语言构建 Agent 的开发者现在也有对应能力。像 rig、Elixir 这类 Rust Agent 框架虽然官方对“skills”的叫法可能不同但“按需加载领域指令”的实现思路是通用的。比如 rig 里的 Tool 抽象可以包装一个“加载 SKILL.md 并注入上下文”的操作本质上就是用 Rust 代码复刻了 Claude Code 的 Skill 发现逻辑。不过我要承认Rust 生态在这一点上还处于早期没有开箱即用的成熟协议更多是靠开发者自己组合。5.2 多 Agent 架构中的 Skill 共享与隔离多 Agent 场景下 Skill 的共享策略值得单独讲。我见过三种主流做法全体共享所有 Agent 用同一套全局 Skills。优点是维护成本低缺点是职责边界模糊比如一个负责客服的 Agent 也加载了代码审查 Skill纯属噪音。按角色隔离每个 Agent 有自己的角色 Skill 集比如“数据分析 Agent”只加载 SQL 分析、图表生成、数据质量检查这三个 Skill。这种方案最符合“最小权限”原则能显著降低 Agent 的上下文浪费。跨 Agent 委托主 Agent 发现任务匹配不到自己的 Skill 时调用另一个 Agent 的 Skill 来执行。这种模式最灵活但要求 Agent 之间必须有清晰的“能力注册表”否则突发奇想互相委托很快陷入循环。我个人的推荐是第二和第三结合常规任务用角色隔离遇到非常规任务时走跨 Agent 委托。Agent 记住常用 Skill 的方式本质是把 Skill 的 ID 和少量使用经验写入 memory 存储形成一个“下回碰到这类任务直接调用”的偏好。5.3 Skill 与 Agent 记忆系统整合最后补一个容易被忽略的点Skill 和 Agent 记忆是互补关系。Skill 提供的是“稳定的、可预定义的流程”记忆提供的是“动态的、从对话中学习到的新偏好”。理论上一个成熟的 Agent 系统应该做到——如果一个 Skill 反复被使用且用户每次都修正同一个步骤那么这个修正应该沉淀下来要么更新 Skill 本身要么写入记忆作为覆盖选项。我的实操经验是记忆覆盖 Skill 是一个危险操作要谨慎。记忆是局部性的可能只适用于某一次对话而修改 Skill 是全局限的会影响所有使用者。比较稳妥的做法先在对话里用临时规则验证几个轮次确认新做法在绝大多数场景下都更好再回头改 SKILL.md 并升版本。6. 实操总结我踩过的坑与快速排查清单6.1 高频问题速查表现象大概率原因快速排查方法Agent 完全没调用 Skilldescription 写得太宽泛匹配不到检查 frontmatter补充任务类型和触发场景短语调用了 Skill 但行为不按步骤SKILL.md 的步骤写得太抽象每个步骤补充判断条件、输入输出说明Agent 上下文迅速爆炸Skill 内嵌了太多无关脚本和参考文件精简 references只保留训练数据无法覆盖的私有知识同一个 Skill 在不同项目里表现不一致项目级 Skill 覆盖了全局 Skill检查项目目录下是否存在同名 Skill更新 Skill 后行为反而变差缺少数质量控制的版本发布建 changelog发布前做三层回归测试6.2 我的几条核心经验写完一套 Skills 并在两个项目跑稳之后让我总结一下最值得记住的经验描述质量决定了 Skill 的生死。我给二十多个开发者做过 Skill 测试发现 70% 的失败案例都出在 description 写得太模糊或太宽泛上。花时间打磨 100 字的 description收益远大于堆砌 SKILL.md 正文。Skill 不是越多越好。有人喜欢把什么都做成 Skill结果 Agent 每次任务都要遍历几百个描述来匹配不仅慢还容易出现“错误命中”。我现在的经验是同一个 Agent 实例上活跃可用的 Skill 控制在 10 个以内其余可以放到次级目录或关闭。每次让 Skill 产生对外副作用前最好有个确认或试运行步骤。比如 Skill 里涉及删除操作、批量修改文件、调用付费 API 的步骤必须留有 dry-run 模式或输出待执行命令而非直接执行。这是架构设计问题不是提示词问题。最后分享一个我自己在用的是小技巧给每个 Skill 加一个“适用场景”和“不适用场景”的显式标记放在 SKILL.md 的正文开头。这样做之后Agent 在“边缘情况”下拒绝调用 Skill 的比例明显降低——它知道什么情况下该换一条路而不是拿着锤子看什么都像钉子。我用“任务重复三次就把它做成 Skill”作为自己开发 Agent 应用的原则。这个节奏不频繁但每次都值得几分钟到半小时的开发投入换来的是后续每次执行这个任务时稳定、可复制的输出质量。
