1. 从“skills”这个热词说起它到底指什么最近一段时间不管是在技术社区还是各类开发者群组里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某个新出的编程语言特性或者某个框架的插件系统。但如果你稍微深入了解一下就会发现这里说的“skills”其实是一个更具体、也更有意思的东西——它指的是给 AI Agent智能体使用的技能包。简单来说你可以把 AI Agent 想象成一个刚入职的新员工脑子很聪明但对你公司的具体业务流程、工具链、代码规范一无所知。而 skills 就是给这个新员工的一本本“操作手册”——每一本手册教它做一件具体的事比如“如何用 Playwright 做浏览器自动化测试”“如何按照团队规范生成 API 文档”“如何从零搭建一个前端项目脚手架”。Agent 加载了这些 skills 之后就能按照你预设的流程和规范去执行任务而不是每次都要你从头解释一遍。这个概念的流行跟最近 AI Agent 生态的爆发有直接关系。从 Claude 的 Agent Skills 到 Codex 的 skills 体系再到 Google Cloud 上各种 Agent 相关的工具链大家都在试图解决同一个问题怎么让 AI 从“能聊天”变成“能干活”。而 skills 就是这个问题的一个关键答案。我最初接触 skills 是因为一个很实际的需求——团队里几个项目都需要做前端自动化测试每次都要跟 AI 反复描述测试框架的配置、目录结构、命名规范效率极低。后来把这一套东西固化成一个 skillAgent 每次执行测试任务时自动加载省掉了大量重复沟通的成本。从那以后我就开始系统性地研究 skills 的开发、安装、管理和最佳实践踩了不少坑也积累了一些真正有用的经验。这篇文章适合几类人看如果你刚开始接触 AI Agent想搞清楚 skills 到底是什么、怎么用那前面的基础部分会对你有帮助如果你已经在用 skills 但遇到了安装失败、加载不生效、多个 skill 冲突等问题中间的排查部分可以直接参考如果你打算自己开发 skills 并分享给团队或社区后面的开发和分发部分是我实际踩过坑之后总结出来的经验。提示本文讨论的 skills 是指 AI Agent 生态中的技能包概念不涉及任何特定平台的敏感内容。所有操作均基于公开可获取的工具和文档。2. skills 的核心机制为什么它不是简单的“提示词模板”2.1 从提示词到技能包解决的是什么问题很多人第一次听说 skills 的时候第一反应是“这不就是提示词模板吗我写一段 system prompt 不就行了”我一开始也是这么想的但实际用下来发现skills 和提示词模板之间有本质区别。提示词模板是扁平的、静态的——你写一段话AI 每次按照这段话的指示去做。但 skills 是结构化的、可组合的、带上下文的。一个完整的 skill 通常包含几个部分元数据名称、描述、触发条件、指令正文具体怎么做、附属资源脚本、配置文件、参考文档。当 Agent 需要执行某个任务时它会根据任务描述自动匹配对应的 skill加载其中的指令和资源然后按照 skill 定义的流程去执行。这个机制解决的核心问题是知识复用和流程标准化。举个例子你团队有一套特定的代码审查规范——变量命名用驼峰、注释必须包含 JSDoc 格式、提交信息遵循 Conventional Commits。如果你每次都用提示词告诉 AI 这些规则一来容易遗漏二来不同人写的提示词质量参差不齐。但如果你把这套规范做成一个 skill所有人在需要代码审查时都调用同一个 skill输出的质量就是一致的。2.2 Agent 是怎么找到并加载 skills 的理解 skills 的加载机制对排查问题和优化使用体验非常关键。不同平台的实现细节有差异但核心逻辑大同小异。Agent 在接收到一个任务后会先分析任务意图然后在其可访问的 skills 目录中搜索匹配的 skill。匹配的依据主要是 skill 的元数据——名称和描述字段。所以你在写 skill 描述的时候一定要把“这个 skill 是做什么的”“什么场景下应该使用它”写清楚否则 Agent 可能找不到它或者在不该用的时候用了它。加载过程通常是这样的Agent 读取 skill 的指令文件一般是一个 Markdown 格式的文件把其中的内容作为上下文注入到当前对话中同时把附属的脚本和资源文件放到一个可访问的路径下。之后 Agent 在执行任务时就会按照 skill 指令中定义的步骤来操作需要运行脚本时也能直接调用。这里有一个容易被忽略的细节skill 的指令文件不是越长越好。我见过有人写了一个 3000 字的 skill 指令结果 Agent 加载后反而不知道该关注哪些重点了。好的 skill 指令应该像一份精炼的 SOP——步骤清晰、关键点突出、必要的上下文交代清楚但不要堆砌无关信息。一般来说核心指令控制在 500 到 1500 字之间比较合适超出的部分可以拆成参考文档放在附属资源里。2.3 skills 和 MCP Server 的关系与边界在讨论 skills 的时候经常会有人把它和 MCP Server 搞混。这两个概念确实有关联但定位完全不同。MCP Server 解决的是能力接入的问题——它让 Agent 能够调用外部工具和服务比如读写数据库、调用 API、操作文件系统。你可以把 MCP Server 理解为给 Agent 装的“手和脚”让它有了与外部世界交互的能力。而 skills 解决的是流程编排的问题——它告诉 Agent 在拥有这些能力之后应该按照什么步骤、什么规范去完成一个具体任务。skills 更像是“操作手册”指导 Agent 如何组合使用已有的能力。举个具体的例子假设你要让 Agent 帮你做一次数据库迁移。MCP Server 提供了连接数据库、执行 SQL、读取 schema 的能力。但具体怎么迁移——先备份、再对比 schema 差异、生成迁移脚本、在测试环境验证、最后上生产——这一套流程就是 skill 要定义的内容。两者配合使用才能发挥最大价值。只有 MCP Server 没有 skillAgent 有工具但不知道怎么用只有 skill 没有 MCP ServerAgent 知道步骤但执行不了。所以在实际项目中我通常会同时规划这两块先确定需要哪些工具能力MCP Server再把这些能力编排成具体的操作流程skills。3. 安装与配置 skills从零跑通的完整路径3.1 环境准备中最容易忽略的三个细节安装 skills 本身不复杂但有几个环境层面的细节如果没注意到后面会浪费大量时间排查。第一个是 Node.js 版本。很多 skills 工具链依赖 Node.js 运行时而且对版本有要求。我遇到过好几次npx命令执行失败最后发现是 Node 版本太老导致的。建议至少使用 Node 18 LTS 以上的版本如果用到一些较新的工具链可能需要 Node 20。检查版本用node -v切换版本可以用nvm或fnm这类版本管理工具。第二个是网络代理配置。如果你在公司内网环境或者网络条件特殊的情况下操作npx下载包可能会超时。这时候需要检查 npm 的 registry 配置和代理设置。不过要注意这里说的代理是指正常的网络请求转发不是其他任何特殊用途。你可以通过npm config get registry查看当前使用的源如果默认源访问慢可以换成国内镜像源来加速。第三个是目录权限。skills 通常需要安装到一个特定的目录下Agent 才能找到它们。如果你用的是全局安装方式可能需要管理员权限如果是项目级安装要确保项目目录有写入权限。在 Linux 或 macOS 上用ls -la检查目录权限在 Windows 上注意不要安装到需要特殊权限的系统目录。# 检查 Node 版本 node -v # 检查 npm 配置 npm config get registry # 查看全局安装目录 npm root -g3.2 用 npx 安装 skills 的实操流程npx是目前安装 skills 最常用的方式之一因为它不需要预先全局安装包直接运行即可。但实际用下来npx安装 skills 有几个坑需要注意。最基本的安装命令通常长这样npx skills-installer install skill-name或者有些平台用的是npx anthropic/skills install skill-name具体命令取决于你使用的平台和工具链。执行之后安装器会从远程仓库拉取 skill 包解压到指定的 skills 目录下。这里最常见的问题是npx playwright install失败——这个命令经常出现在需要浏览器自动化能力的 skill 安装过程中。失败的原因通常有三个一是下载浏览器二进制文件时网络超时二是系统缺少必要的依赖库在 Linux 上尤其常见三是磁盘空间不足。针对网络超时可以设置更长的超时时间# 设置 npm 超时时间为 120 秒 npm config set fetch-timeout 120000 # 或者临时使用环境变量 NPX_FETCH_TIMEOUT120000 npx playwright install针对系统依赖缺失在 Ubuntu 或 Debian 系统上可以运行# 安装 Playwright 所需的系统依赖 npx playwright install-deps这个命令会自动安装 Chromium、Firefox、WebKit 所需的系统库。如果这个命令也失败了可以尝试手动安装常见的缺失库sudo apt-get update sudo apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound23.3 安装后的验证确认 skill 真的被加载了安装完成不等于 skill 就能用了。我踩过好几次“安装成功但 Agent 找不到”的坑后来总结了一套验证流程。第一步确认文件确实存在。进入 skills 安装目录看看对应的文件夹和文件是否都在# 假设 skills 安装在项目目录下 ls -la .skills/ # 或者全局安装目录 ls -la ~/.skills/第二步检查 skill 的元数据文件是否完整。一个标准的 skill 至少应该包含一个描述文件通常是SKILL.md或skill.json里面定义了名称、描述、触发条件等信息。如果这个文件缺失或格式错误Agent 就无法正确识别这个 skill。第三步在 Agent 中实际测试。最直接的方式是给 Agent 一个应该触发该 skill 的任务描述看它是否会加载对应的 skill。比如你安装了一个“代码审查”的 skill就可以给 Agent 一段代码并说“帮我审查这段代码”观察它的回复中是否引用了该 skill 的规范。如果 Agent 没有加载 skill可以尝试以下几个排查方向排查项检查方法常见问题安装路径确认 skills 目录是否在 Agent 的搜索路径中路径配置错误元数据格式检查 SKILL.md 的 YAML frontmatter 是否合法缩进错误、字段缺失描述匹配度看 skill 描述是否与任务意图匹配描述太模糊或太窄权限问题确认 Agent 进程有读取 skill 文件的权限文件权限不足缓存问题尝试重启 Agent 或清除缓存旧缓存未刷新4. 开发自己的 skills从需求到可分发4.1 什么样的任务值得做成 skill不是所有事情都值得做成 skill。我一开始兴致勃勃地把各种小任务都封装成 skill结果发现维护成本比收益还高。后来总结了一个判断标准高频、标准化、多步骤的任务才值得做成 skill。高频是指这个任务你会反复执行比如每周至少做一次。标准化是指任务的执行流程相对固定不需要每次根据情况做大量调整。多步骤是指任务不是一步就能完成的需要按照一定的顺序执行多个操作。举个例子“生成 API 文档”就是一个典型的适合做成 skill 的任务——每次新加了接口都要做流程固定读取代码注释、提取接口信息、按照模板生成文档、输出到指定目录步骤明确。而“帮我起个变量名”这种任务就不适合因为太简单、太随机做成 skill 反而增加了不必要的开销。还有一个容易被忽略的维度这个任务是否需要特定的领域知识或团队规范。如果任务本身需要大量上下文才能做好那做成 skill 的价值就很大因为你可以把这些上下文固化在 skill 里不用每次都重复解释。4.2 skill 文件的结构与编写要点一个标准的 skill 通常包含以下部分my-skill/ ├── SKILL.md # 核心指令文件 ├── scripts/ # 附属脚本 │ └── helper.py ├── references/ # 参考文档 │ └── api-spec.md └── assets/ # 静态资源 └── template.htmlSKILL.md是最关键的文件它的结构一般包括 YAML frontmatter 和正文两部分。Frontmatter 定义元数据--- name: api-doc-generator description: 根据代码注释自动生成 API 文档。当用户需要生成、更新或审查 API 文档时使用此 skill。 version: 1.0.0 ---正文部分写具体的操作指令。这里有一个编写技巧用“步骤 检查点”的方式组织内容而不是写一大段描述性文字。比如## 执行步骤 1. 扫描 src/api/ 目录下所有 .ts 文件 2. 提取每个文件中带有 api 注释的函数 3. 按照 references/api-spec.md 中的模板生成 Markdown 文档 4. 将生成的文档输出到 docs/api/ 目录 ## 检查点 - 确认所有公开接口都被覆盖 - 检查参数类型是否与代码一致 - 验证生成的 Markdown 语法正确这种结构的好处是 Agent 执行时有明确的步骤可循同时检查点可以帮助它自我验证输出质量。4.3 让 skill 被正确触发的描述写法skill 的描述字段直接决定了 Agent 能不能在正确的时机找到它。我见过太多 skill 因为描述写得太差而“隐身”的情况。好的描述应该包含三个要素做什么、什么时候用、不做什么。比如根据代码注释自动生成 API 文档。当用户需要生成、更新或审查 API 文档时使用此 skill。不适用于生成用户手册或教程类文档。这个描述清楚地告诉 Agent功能是生成 API 文档触发场景是用户提到 API 文档相关需求边界是不处理用户手册。这样 Agent 在匹配时就能准确判断。反面例子是只写一句“生成文档”。太模糊了Agent 不知道是什么文档、什么时候该用、和别的文档类 skill 怎么区分。还有一个技巧是在描述中加入用户可能使用的关键词。比如用户可能会说“帮我导出接口文档”“更新一下 API 说明”“生成 swagger”这些变体都应该能在描述中有所体现提高匹配率。5. 多 skill 管理与冲突排查实战5.1 skill 之间的优先级与互斥问题当你安装了多个 skill 之后冲突就不可避免了。最常见的冲突场景是两个 skill 的触发条件有重叠Agent 不知道该用哪个。比如你同时安装了“代码审查”和“代码重构”两个 skill。当用户说“帮我看看这段代码”时两个 skill 都可能被触发——代码审查是检查问题代码重构是改进结构。Agent 如果选错了输出就不是用户想要的。解决这个问题的核心方法是在描述中明确边界。代码审查的 skill 描述可以写“当用户需要检查代码质量、发现潜在问题时使用”代码重构的描述写“当用户需要改进代码结构、优化可读性时使用”。这样虽然还是有重叠但 Agent 有了更明确的判断依据。另一个方法是设置优先级。有些平台支持在 skill 元数据中定义优先级当多个 skill 匹配时优先级高的先被考虑。但优先级不能滥用如果所有 skill 都设成高优先级就等于没有优先级。5.2 排查 skill 不生效的完整链路Skill 不生效是最高频的问题之一。我总结了一套排查链路按顺序走一遍基本能定位到原因。第一步确认 skill 是否被 Agent 感知到。有些平台提供了查看已加载 skill 列表的命令或界面。如果没有可以尝试给 Agent 一个明确应该触发该 skill 的任务看它的回复中是否提到了 skill 名称或遵循了 skill 中定义的流程。第二步检查元数据格式。YAML frontmatter 对缩进和格式非常敏感。一个常见的错误是用了 Tab 而不是空格或者冒号后面没有加空格。可以用在线 YAML 校验工具检查一下格式是否合法。第三步检查文件编码。这个问题很隐蔽但确实存在。如果 SKILL.md 文件保存成了带 BOM 的 UTF-8 格式某些解析器会读取失败。确保文件保存为无 BOM 的 UTF-8 格式。第四步检查路径和权限。确认 skill 安装目录确实在 Agent 的搜索路径中并且 Agent 进程有读取权限。在 Linux 上可以用namei -l /path/to/skill查看完整路径的权限链。第五步查看日志。大多数 Agent 平台会输出加载日志。如果前面的步骤都没发现问题日志里通常会有线索。关注关键词如 “skill not found”“failed to parse”“permission denied” 等。5.3 版本更新与回滚策略Skills 也是代码也需要版本管理。我吃过亏之后现在给每个 skill 都加了版本号并且保留历史版本以便回滚。版本号建议遵循语义化版本规范主版本号.次版本号.修订号。修复 bug 时递增修订号新增功能时递增次版本号有不兼容的变更时递增主版本号。更新 skill 时不要直接覆盖旧版本。先把旧版本备份到一个backup/目录再安装新版本。如果新版本有问题可以快速回滚。# 备份当前版本 cp -r .skills/my-skill .skills/backup/my-skill-v1.0.0 # 安装新版本 npx skills-installer install my-skill1.1.0 # 如果出问题回滚 rm -rf .skills/my-skill cp -r .skills/backup/my-skill-v1.0.0 .skills/my-skill另外建议在 skill 的 SKILL.md 中维护一个简短的变更日志记录每个版本改了什么。这样团队其他人更新时能快速了解变化。6. 高频场景下的 skills 组合实践6.1 前端开发场景的 skill 组合前端开发是我用得最多的场景也是 skills 组合效果最明显的地方。我目前维护了一套前端开发相关的 skill 组合覆盖从项目初始化到部署的完整流程。项目脚手架 skill负责根据团队规范生成新项目结构。它定义了目录结构、配置文件模板、依赖版本范围、ESLint 和 Prettier 配置等。新项目初始化时调用这个 skill生成的结构和配置就是统一的。组件生成 skill负责按照团队规范生成 React 或 Vue 组件文件。它定义了组件文件的命名规则、文件结构组件文件、样式文件、测试文件、story 文件、导出方式等。开发新组件时调用这个 skill省去了手动创建多个文件和写样板代码的时间。代码审查 skill负责在提交前检查代码质量。它集成了团队的 ESLint 规则、命名规范、注释要求等。Agent 审查时会按照这些规则逐项检查输出结构化的审查报告。构建部署 skill负责执行构建和部署流程。它定义了构建命令、环境变量检查、产物验证、部署步骤等。需要发布时调用这个 skillAgent 会按步骤执行并报告每步结果。这几个 skill 组合使用基本覆盖了前端日常开发的主要环节。关键是它们之间共享同一套规范定义不会出现“脚手架生成的代码不符合审查规则”这种矛盾。6.2 自动化测试场景的 skill 设计自动化测试是另一个 skills 发挥大价值的场景。测试代码的编写和维护有很多重复性工作而且对规范性要求高。我设计的测试 skill 组合包括测试用例生成 skill、测试执行 skill、失败分析 skill。测试用例生成 skill 根据接口定义或页面结构自动生成测试用例骨架。它定义了测试文件的组织方式、断言风格、mock 数据的构造方法等。生成的不是完整可运行的测试而是结构正确、需要填充具体断言的骨架这样既保证了规范性又保留了灵活性。测试执行 skill 负责运行测试并收集结果。它定义了测试命令、环境准备步骤、结果解析方式等。执行完成后输出结构化的测试报告包括通过率、失败用例列表、耗时统计等。失败分析 skill 在测试失败时触发负责分析失败原因。它会读取失败用例的错误信息、相关代码变更、历史执行记录尝试定位是代码问题、环境问题还是测试本身的问题。这个 skill 的价值在于把排查经验固化了不用每次从头分析。6.3 文档生成与知识管理场景文档类任务是我最早做成 skill 的场景也是收益最直观的。以前每次写文档都要跟 AI 反复沟通格式和风格现在一个 skill 搞定。API 文档 skill从代码注释生成接口文档前面已经详细说过。变更日志 skill从 Git 提交记录生成格式化的 CHANGELOG。架构决策记录 skill按照 ADR 模板生成架构决策文档。知识库同步 skill把项目中的文档同步到内部知识库处理格式转换和链接替换。这几个 skill 的共同点是输入源明确代码、Git、现有文档输出格式固定团队模板中间处理逻辑标准化。这种任务最适合做成 skill因为每次的差异只在内容层面流程和格式完全一致。7. 我踩过的那些坑与对应的解法7.1 skill 描述太宽泛导致误触发这个问题我踩得最多。早期写 skill 描述时总想“覆盖面广一点”结果就是 Agent 在不该用的时候用了这个 skill。有一次我写了一个“代码优化”的 skill描述是“帮助改进代码”。结果用户只是问了一句“这段代码什么意思”Agent 也触发了这个 skill开始给代码提优化建议。用户很困惑我也很尴尬。后来我把描述改成了“当用户明确要求优化代码性能、改进代码结构或重构代码时使用。不适用于代码解释、代码审查或问题排查。”加了明确的触发条件和排除条件之后误触发就很少了。经验就是描述要像 API 文档一样精确明确输入条件、输出结果和边界。宁可写窄一点也不要写太宽。7.2 附属脚本的路径问题Skill 中引用的脚本文件路径是一个很容易出错的地方。因为 skill 被加载时工作目录可能和 skill 所在目录不一致用相对路径引用脚本就会找不到文件。我最初的写法是在 SKILL.md 中写python scripts/helper.py结果 Agent 执行时工作目录是项目根目录而脚本在 skill 目录下路径就错了。正确的做法是使用相对于 skill 目录的路径或者在指令中明确说明先切换到 skill 目录再执行。有些平台提供了环境变量来指向 skill 目录可以用这个变量来构造绝对路径。## 执行脚本 先切换到 skill 目录 bash cd $SKILL_DIR python scripts/helper.py如果平台不支持 $SKILL_DIR 这样的变量可以在指令中写明“脚本位于本 skill 的 scripts/ 目录下执行前请先定位到该目录”。 ### 7.3 多平台兼容性的取舍 不同的 AI Agent 平台对 skills 的支持方式有差异。有的用 Markdown 格式的 SKILL.md有的用 JSON 配置有的对附属资源的处理方式不同。如果你想让自己的 skill 在多个平台上都能用就需要做一些兼容性处理。 我的做法是**核心逻辑与平台适配分离**。把 skill 的核心指令写成平台无关的 Markdown然后在不同平台的分发版本中只改元数据格式和资源引用方式。这样维护一份核心内容生成多个平台的适配版本。 但也要接受一个现实**不可能做到 100% 兼容**。有些平台特有的能力比如特定的工具调用方式无法在其他平台上复现。这种情况下我会在 skill 描述中注明适用的平台避免用户在不支持的环境中使用。 ### 7.4 团队协作中的 skill 分发与同步 当团队多人使用 skills 时分发和同步就成了问题。每个人本地安装的 skill 版本可能不一致导致同样的任务在不同人那里表现不同。 我们的解决方案是**把 skills 纳入版本控制**。在项目仓库中建一个 .skills/ 目录把团队共用的 skill 都放在里面通过 Git 管理版本。每个人拉取代码后就自动获得了最新的 skill。更新 skill 时走正常的代码审查流程确保变更经过审核。 对于跨项目的通用 skill我们单独建了一个 skill 仓库通过 Git submodule 的方式引入到各个项目中。这样通用 skill 只需要维护一份所有项目都能受益。 另外建议在团队内建立一个 skill 使用公约明确哪些 skill 是必须使用的、哪些是可选的、更新 skill 时怎么通知其他人。这些管理层面的约定比技术方案更能保证 skill 体系的长期有效运行。 ## 8. 关于 skills 生态的一些个人观察 Skills 这个方向目前还在快速演进中。从最早的简单提示词模板到现在有完整元数据、附属资源、版本管理的技能包体系变化速度非常快。我自己的感受是**skills 的价值不在于技术有多复杂而在于它把“如何做好一件事”的经验固化和复用了**。 以前这些经验散落在每个人的脑子里、聊天记录里、零散的文档里。现在通过 skill 把它们结构化地保存下来Agent 可以随时调用新人可以快速上手团队的整体效率就上来了。 如果你还没开始用 skills我的建议是从一个你最高频、最标准化的任务开始把它做成一个简单的 skill跑通整个流程。不用一开始就追求大而全先解决一个具体问题有了体感之后再逐步扩展。踩坑是必然的但每个坑踩完之后你对 Agent 工作方式的理解就会深一层。 这个领域变化很快今天好用的方法明天可能就有更好的替代方案。保持关注、持续迭代比一次性做到完美更重要。