如何为你的 AI Agent创建合适的Skill

如何为你的 AI Agent创建合适的Skill 如何为你的 AI Agent创建合适的Skill Modified July 2 每一次没有考虑代码库整体结构的改动，都会引入小的不一致。这些不一致会叠加。几周无人监督的 AI 生成代码之后，你的项目就会变成一团脆弱、细碎、互相缠绕的文件，无论人类还是Agent都很难推理。 John Ousterhout 在 A Philosophy of Software Design 中描述过深模块和浅模块的区别。深模块用简单接口隐藏大量功能。浅模块则只是包在几乎没有内容之上的薄壳。 Agent倾向于产出浅模块，因为它们容易生成。但浅代码库难测试、难修改，也让其他Agent难以协作。 修复方式是架构Skill。它会定期扫描代码库，寻找可以加深模块的地方：理解一个概念是否需要在十个文件之间来回跳？ 是否有一些纯函数只是为了可测试性被抽取出来，而真正的 bug 藏在调用方式里？紧耦合模块是否跨边界泄漏？ 每周运行一次这样的Skill，可以让代码库同时适合人类和Agent继续工作。 写你的第一个 SKILL.md 你已经识别出最大的失败模式。现在构建能修复它的Skill。 头部：YAML Frontmatter 每个 SKILL.md 都以三条短横线包裹的 YAML 块开头。必需字段有两个：name 和 description。 代码块 YAML Copy name: code review checklist description: 对当前变更集执行结构化代码审查。 在审查 PR 或合并任何分支之前触发。 不用于架构级审查；架构级审查请使用 架构Skill。 description 字段是整个Skill中最重要的一段文字。Agent会读取它，判断是否应该为当前任务加载该Skill。 把关键词和触发条件放在最前面。明确写出Skill不应该在什么时候触发。模糊描述会导致错误匹配，浪费上下文，也会让Agent混乱。 正文：Markdown 指令 在头部下面，写出Agent应该遵循的工作流。普通 Markdown 即可，不需要特殊语法。 Code block Markdown Copy Code Review Checklist 审查变更集时： 1. 评论前先完整阅读 diff。 2. 检查每个新函数是否有测试覆盖。 3. 标出任何超过 40 行的函数。 4. 验证命名是否符合 CONTEXT.md 约定。 5. 如果模块公开接口发生变化，确认 changelog 条目存在。 6. 用结构化评论输出发现： 每项检查给出通过/未通过，并附带行号引用。 这就是一个完整的Skill：一个文件，六个步骤。现在，每次它审查代码时，都会在你使用的每个兼容工具中运行这份精确清单。 保持简短 GitHub 上最受欢迎的Skill仓库里，影响力最大的Skill只有三句话。它告诉Agent要围绕用户计划采访用户，沿着设计树的每个分支走下去，并在向用户提问前先探索代码库寻找答案。 这三句话已经被安装超过 250,000 次。 Skill不需要很长。它需要在正确时刻选择正确的词。 如果你发现自己写的Skill超过两页打印纸，你很可能把两个Skill合成了一个。拆开它们。一个Skill，一个工作。 先从无状态开始，再进入有状态 无状态Skill不会在会话之间保存任何内容。它运行、完成工作，然后不留下痕迹。 每次调用都从新开始。你的第一个Skill应该是无状态的，因为出错空间更小。 有状态Skill会把文件保存到磁盘，例如术语表、进度跟踪器或上下文文档，并在会话之间保留。这类Skill更强，但也更复杂。 前面提到的共享语言Skill是有状态的，因为它维护 CONTEXT.md。教学Skill也可以是有状态的，因为它会追踪学习者已经学过什么。 先构建无状态Skill。等你真正感受到每次会话都从零开始的限制后，再加入状态。 不要下载有害内容 像 SkillsMP 这样的社区中心，已经索引了超过 190 万个公开Skill，它们从世界各地的 GitHub 仓库中抓取而来。大多数都没问题。有些则不是。 2026 年 2 月，prplbx.com 的安全研究人员在公开目录中识别出 341 个恶意Skill。这些Skill包含隐藏载荷：数据外泄、凭证盗取，以及会诱导Agent执行未授权命令的提示词注入。Snyk 后续审计，也就是 “ToxicSkills” 报告，测试了更大样本，并发现 36% 的被检Skill存在提示词注入漏洞。 质量也没有保证 除了安全，还有质量问题。SkillsBench 研究团队在为基准选择经过整理的Skill之前，审计了超过 47,150 个公开Skill。大多数公开Skill都不达标：描述含糊，导致在错误任务上触发；指令太泛，无法稳定地产生一致输出；没有清晰的工作流结构。 当 SkillsBench 比较使用经过整理的Skill与自生成Skill的Agent表现时，那些试图自己写Skill的模型没有表现出可靠提升。Skill的质量，比“存在一个Skill”这件事本身更重要。 一个经过整理、结构良好的Skill，与从社区目录随手拉来的随机Skill之间的差距，就是训练过的流程和猜测之间的差距。如果你要使用社区Skill，请从成熟来源选择，要看得到安装量，并且有活跃维护者。或者，自己写。 采用前审计规则 安装任何社区Skill之前： 1. 阅读完整 SKILL.md。不要只看名称和描述。 2. 如果存在 scripts/ 文件夹，打开它。阅读每个文件。如果脚本会从互联网下载内容，或访问环境变量，你必须理解原因。 3. 检查发布者是谁。一个只有一个仓库、零粉丝的匿名 GitHub 账号，和一个拥有多年公开工作的成熟开发者，风险画像完全不同。 4. 先在一次性项目里测试。永远不要把未经测试的Skill直接安装到生产代码库里。 这和你对 npm 包或 VS Code 扩展采取的卫生习惯一样。Skill是会在你的Agent内部运行的代码。应该按这个标准对待它。 当你开始构建Skill，会发生什么变化 一开始，这种变化感觉很小。你写一个 SKILL.md，安装它，然后Agent会遵循一份它以前总会跳过的清单。 这很有用。但真正重要的是复利效应。 你不再重复自己 在Skill之前，每次会话都要从重新解释偏好开始：“使用 TypeScript。遵循我们的命名约定。先写测试。不要使用 any 类型。” 有了Skill，这些指令会存在文件里。你只写一次，Agent每次都会拉取。每次会话的第一句话可以直接是任务本身，而不是启动仪式。 你的Agent变得可预测 没有Skill的Agent，是一个有能力的即兴发挥者。它能处理大多数任务，但每次会话的方法都不同。 有时它先写测试。有时不会。有时它会问澄清问题。有时它直接开始构建。 有Skill的Agent会遵循定义好的流程。TDD Skill确保测试先于代码。拷问式Skill确保实现前先对齐。 架构Skill确保代码库不会腐烂。你不再只是希望Agent做出好选择，而是知道它会遵循好流程。 你的工具变得可以互换 因为Skill遵循开放 SKILL.md 标准，当你切换Agent时，工作流也会迁移。你从 Claude Code 切到 Codex，或者在 Gemini CLI 旁边加上 Cursor，你的Skill都会跟着你。 你的流程是可移植的。无论你最终选择哪个工具，写好Skill的投入都会继续回报你。 你开始编码自己的工作方式 这是更深层的变化。Skill不只是给Agent的指令。它是你如何看待某个任务的形式化版本。 写Skill这件事，会迫使你说清楚自己的流程：你会遵循哪些步骤？顺序是什么？决策点在哪里？ 大多数工程师把这类知识当成直觉带在身上。把它写成Skill，能让它迁移给Agent、队友，以及未来的你。 从这里开始 选择最消耗你时间的失败模式。写一个 SKILL.md 来解决它。控制在 30 行以内。安装它。运行一周。然后再写下一个。 把 AI Agent当成聊天窗口的人，会每天早上继续粘贴同一套指令。把Agent当作拥有编码流程的团队成员的人，会让生产力在一次又一次会话、一个又一个Skill中复利增长。 Skill可以跨工具迁移，可以跨工作流组合，也会随着时间复利。这就是“使用 AI”和“用 AI 构建”之间的区别。 资源： → Agent Skills 规范：agentskills.io → SKILL.md 格式参考与示例：github.com/agentskills/agentskills → 浏览社区Skill：skills.sh → 安全审计发现：搜索 “ToxicSkills Snyk 2026” 获取完整报告 → SkillsBench 研究论文：arxiv.org/abs/2602.12670（84 个任务、11 个领域，经过同行评审） 关注 @free ai guides，获取每日 AI 技巧、指南和资源。 prplbx.com SKILL.md SKILL.md agentskills.io SKILL.md github.com/agentskills/agentskills skills.sh arxiv.org/abs/2602.12670 每一次没有考虑代码库整体结构的改动，都会引入小的不一致。这些不一致会叠加。几周无人监督的 AI 生成代码之后，你的项目就会变成一团脆弱、细碎、互相缠绕的文件，无论人类还是Agent都很难推理。 John Ousterhout 在 A Philosophy of Software Design 中描述过深模块和浅模块的区别。深模块用简单接口隐藏大量功能。浅模块则只是包在几乎没有内容之上的薄壳。 Agent倾向于产出浅模块，因为它们容易生成。但浅代码库难测试、难修改，也让其他Agent难以协作。 修复方式是架构Skill。它会定期扫描代码库，寻找可以加深模块的地方：理解一个概念是否需要在十个文件之间来回跳？ 是否有一些纯函数只是为了可测试性被抽取出来，而真正的 bug 藏在调用方式里？紧耦合模块是否跨边界泄漏？ 每周运行一次这样的Skill，可以让代码库同时适合人类和Agent继续工作。 写你的第一个 SKILL.md 你已经识别出最大的失败模式。现在构建能修复它的Skill。 头部：YAML Frontmatter 每个 SKILL.md 都以三条短横线包裹的 YAML 块开头。必需字段有两个：name 和 description。 description 字段是整个Skill中最重要的一段文字。Agent会读取它，判断是否应该为当前任务加载该Skill。 把关键词和触发条件放在最前面。明确写出Skill不应该在什么时候触发。模糊描述会导致错误匹配，浪费上下文，也会让Agent混乱。 正文：Markdown 指令 在头部下面，写出Agent应该遵循的工作流。普通 Markdown 即可，不需要特殊语法。 这就是一个完整的Skill：一个文件，六个步骤。现在，每次它审查代码时，都会在你使用的每个兼容工具中运行这份精确清单。 保持简短 GitHub 上最受欢迎的Skill仓库里，影响力最大的Skill只有三句话。它告诉Agent要围绕用户计划采访用户，沿着设计树的每个分支走下去，并在向用户提问前先探索代码库寻找答案。 这三句话已经被安装超过 250,000 次。 Skill不需要很长。它需要在正确时刻选择正确的词。 如果你发现自己写的Skill超过两页打印纸，你很可能把两个Skill合成了一个。拆开它们。一个Skill，一个工作。 先从无状态开始，再进入有状态 无状态Skill不会在会话之间保存任何内容。它运行、完成工作，然后不留下痕迹。 每次调用都从新开始。你的第一个Skill应该是无状态的，因为出错空间更小。 有状态Skill会把文件保存到磁盘，例如术语表、进度跟踪器或上下文文档，并在会话之间保留。这类Skill更强，但也更复杂。 前面提到的共享语言Skill是有状态的，因为它维护 CONTEXT.md。教学Skill也可以是有状态的，因为它会追踪学习者已经学过什么。 先构建无状态Skill。等你真正感受到每次会话都从零开始的限制后，再加入状态。 不要下载有害内容 像 SkillsMP 这样的社区中心，已经索引了超过 190 万个公开Skill，它们从世界各地的 GitHub 仓库中抓取而来。大多数都没问题。有些则不是。 2026 年 2 月，prplbx.com 的安全研究人员在公开目录中识别出 341 个恶意Skill。这些Skill包含隐藏载荷：数据外泄、凭证盗取，以及会诱导Agent执行未授权命令的提示词注入。Snyk 后续审计，也就是 “ToxicSkills” 报告，测试了更大样本，并发现 36% 的被检Skill存在提示词注入漏洞。 prplbx.com 质量也没有保证 除了安全，还有质量问题。SkillsBench 研究团队在为基准选择经过整理的Skill之前，审计了超过 47,150 个公开Skill。大多数公开Skill都不达标：描述含糊，导致在错误任务上触发；指令太泛，无法稳定地产生一致输出；没有清晰的工作流结构。 当 SkillsBench 比较使用经过整理的Skill与自生成Skill的Agent表现时，那些试图自己写Skill的模型没有表现出可靠提升。Skill的质量，比“存在一个Skill”这件事本身更重要。 一个经过整理、结构良好的Skill，与从社区目录随手拉来的随机Skill之间的差距，就是训练过的流程和猜测之间的差距。如果你要使用社区Skill，请从成熟来源选择，要看得到安装量，并且有活跃维护者。或者，自己写。 采用前审计规则 安装任何社区Skill之前： 1. 阅读完整 SKILL.md。不要只看名称和描述。 2. 如果存在 scripts/ 文件夹，打开它。阅读每个文件。如果脚本会从互联网下载内容，或访问环境变量，你必须理解原因。 3. 检查发布者是谁。一个只有一个仓库、零粉丝的匿名 GitHub 账号，和一个拥有多年公开工作的成熟开发者，风险画像完全不同。 4. 先在一次性项目里测试。永远不要把未经测试的Skill直接安装到生产代码库里。 这和你对 npm 包或 VS Code 扩展采取的卫生习惯一样。Skill是会在你的Agent内部运行的代码。应该按这个标准对待它。 当你开始构建Skill，会发生什么变化 一开始，这种变化感觉很小。你写一个 SKILL.md，安装它，然后Agent会遵循一份它以前总会跳过的清单。 SKILL.md 这很有用。但真正重要的是复利效应。 你不再重复自己 在Skill之前，每次会话都要从重新解释偏好开始：“使用 TypeScript。遵循我们的命名约定。先写测试。不要使用 any 类型。” 有了Skill，这些指令会存在文件里。你只写一次，Agent每次都会拉取。每次会话的第一句话可以直接是任务本身，而不是启动仪式。 你的Agent变得可预测 没有Skill的Agent，是一个有能力的即兴发挥者。它能处理大多数任务，但每次会话的方法都不同。 有时它先写测试。有时不会。有时它会问澄清问题。有时它直接开始构建。 有Skill的Agent会遵循定义好的流程。TDD Skill确保测试先于代码。拷问式Skill确保实现前先对齐。 架构Skill确保代码库不会腐烂。你不再只是希望Agent做出好选择，而是知道它会遵循好流程。 你的工具变得可以互换 因为Skill遵循开放 SKILL.md 标准，当你切换Agent时，工作流也会迁移。你从 Claude Code 切到 Codex，或者在 Gemini CLI 旁边加上 Cursor，你的Skill都会跟着你。 你的流程是可移植的。无论你最终选择哪个工具，写好Skill的投入都会继续回报你。 你开始编码自己的工作方式 这是更深层的变化。Skill不只是给Agent的指令。它是你如何看待某个任务的形式化版本。 写Skill这件事，会迫使你说清楚自己的流程：你会遵循哪些步骤？顺序是什么？决策点在哪里？ 大多数工程师把这类知识当成直觉带在身上。把它写成Skill，能让它迁移给Agent、队友，以及未来的你。 从这里开始 选择最消耗你时间的失败模式。写一个 SKILL.md 来解决它。控制在 30 行以内。安装它。运行一周。然后再写下一个。 SKILL.md 把 AI Agent当成聊天窗口的人，会每天早上继续粘贴同一套指令。把Agent当作拥有编码流程的团队成员的人，会让生产力在一次又一次会话、一个又一个Skill中复利增长。 Skill可以跨工具迁移，可以跨工作流组合，也会随着时间复利。这就是“使用 AI”和“用 AI 构建”之间的区别。 资源： → Agent Skills 规范：agentskills.io agentskills.io → SKILL.md 格式参考与示例：github.com/agentskills/agentskills SKILL.md github.com/agentskills/agentskills → 浏览社区Skill：skills.sh skills.sh → 安全审计发现：搜索 “ToxicSkills Snyk 2026” 获取完整报告 → SkillsBench 研究论文：arxiv.org/abs/2602.12670（84 个任务、11 个领域，经过同行评审） arxiv.org/abs/2602.12670 关注 @free ai guides，获取每日 AI 技巧、指南和资源。 原帖链接：https://x.com/free ai guides/status/2071666929451094227 原帖链接：https://x.com/free ai guides/status/2071666929451094227 你的 AI Agent不需要又一个提示词。它需要一个Skill。 提示词是一次性指令。你输入它，Agent照做；到了下一次会话，整段对话都消失了。每一次都要从零开始。 Skill是一个放在项目里的可复用工作流文件。你只写一次。每次出现对应任务时，Agent都会加载它，并重复执行同一套明确流程。 数据也支持这一点。SkillsBench 是第一个经过同行评审的Agent Skill基准，发布于 2026 年 2 月，覆盖 11 个领域的 84 个任务。它发现，经过整理的Skill能让Agent平均通过率提高 16.2 个百分点。而让Agent自己生成Skill，并没有表现出可靠提升。 Skill的质量才是变量。随着Agent能力越来越强，知道如何写好Skill的人，会进一步拉开与那些只在聊天窗口里输入指令、然后期待最好结果的人之间的差距。 Skill格式本身也不再是某一家厂商的功能。Anthropic 于 2025 年 12 月在 agentskills.io 发布了 Agent Skills 规范，把它作为开放标准。三个月内，OpenAI 的 Codex、Google 的 Gemini CLI、GitHub Copilot、Cursor、VS Code，以及几十种其他工具，都采用了同一格式。 agentskills.io 截至 2026 年中，已有 40 多个产品支持 SKILL.md 标准。写一次Skill，它就能在所有主流编码Agent中无需修改地运行。 这篇指南会覆盖全部内容：什么是Skill，如何从零写一个，如何避开社区共享Skill中的安全陷阱，以及一旦你开始构建Skill，日常工作会发生什么变化。 收藏这篇。本周你会反复用到。 Skill到底是什么 Skill是一个文件夹。里面有一个名为 SKILL.md 的文件。这个文件包含两部分：一个简短头部，写着Skill的名称和描述，用 YAML 编写；以及正文，写着Agent应该遵循的实际指令，用普通 Markdown 编写。 SKILL.md SKILL.md 文件是唯一必需组件。其他内容都是可选的，而且只有在Agent需要时才会加载。 SKILL.md Skill如何加载：渐进式披露 你的Agent不会在每次会话开始时读取所有已安装的Skill。那会淹没上下文窗口，让它变笨。相反，Skill分三层加载： 第 1 层：只加载名称和描述。 会话开始时，Agent只读取每个已安装Skill的名称和一句话描述。每个Skill大约消耗 30 到 50 个 token。这样足以知道有哪些能力可用，又不会烧掉上下文。 第 2 层：完整指令。 当Agent判断某个Skill与当前任务相关时，它会把完整的 SKILL.md 正文拉进上下文。此时它就拥有完整工作流。 第 3 层：参考文件。 如果指令引用了外部文件，例如脚本、模板或文档，Agent只会在执行到需要它们的步骤时加载。 这个三层系统解释了为什么你可以安装几十个Skill，而不会拖慢Agent。它只在需要时加载所需的最小内容。 Skill、提示词与配置文件 这三者总是被混淆。区别其实很直接。 提示词 是你输入聊天的一次性指令。例如：“检查这段代码有没有 bug。” 会话结束后，它就消失了。 配置文件，例如 CLAUDE.md、AGENTS.md 或 .cursorrules，是一组会在每次会话开始时始终推送给Agent的指令。例如：“始终使用 TypeScript。遵循我们的命名约定。绝不要 push 到 main。” 这些是始终开启的规则，适用于Agent做的所有事情。 Skill 介于两者之间。它不是始终开启的，因为那会浪费上下文；也不是一次性的，因为那会浪费你写它的精力。它会在任务匹配时按需拉取。 Agent读取描述并判断：“这个任务适合那个Skill。” 然后它加载完整指令，并按照定义好的工作流执行。 这一区别的技术术语是推送与拉取。配置文件会把指令推给Agent，不管它需不需要。Skill则让Agent在识别出正确时机时主动拉取指令。 两类Skill 用户调用型Skill 是你自己触发的Skill。你输入 /grill me 或 /tdd，Agent就启动对应工作流。它们适合编排，也就是在明确时刻启动一个定义好的流程。 模型调用型Skill 是Agent在任务匹配时可以自己调用的Skill。你不需要输入命令。 Agent读取Skill的描述，识别到匹配，然后把它拉进来。它们适合建立纪律，把好的实践嵌入系统，让它们在不被要求时也能触发。 两类Skill使用同一种 SKILL.md 格式。区别在于触发方式，而不是构建方式。 默认跨平台 在 Agent Skills 标准出现之前，每个工具都有自己的自定义格式。Cursor 使用 .cursorrules。Claude Code 使用 /commands。Copilot 使用 instruction files。 如果你切换工具，自定义内容无法迁移。 SKILL.md 开放标准改变了这一点。为 Claude Code 写的Skill，可以不经修改地在 Codex、Gemini CLI、Cursor、Copilot 和 VS Code 中运行。兼容工具列表现在已经超过 40 个产品，从终端Agent，到完整 IDE，再到云端自主系统都有。 你只写一次Skill。它可以到处运行。 从问题开始，而不是从工具开始 不要坐下来想着“我要写一个Skill”。你应该坐下来修复一个失败模式。 AI Agent会以可预测的方式失败。任何和编码Agent相处过一个月的开发者，都会遇到同样四类问题。理解哪一类问题最消耗你的时间，就能告诉你应该先构建哪个Skill。 失败模式 1：Agent没有做你想要的事 这是最常见的问题。你描述想要什么。Agent接受任务并开始构建。 你回来后发现，它理解成了另一个意思。 根本原因是对齐不足。你和Agent在跳进代码之前，没有达成对问题的共同理解。 Frederick P. Brooks 在 The Design of Design 中把这描述为“设计树”。每个设计都有一系列需要先解决的决策分支，然后你才能承诺开始构建。跳过这些分支，就是在假设上建东西。 修复方式是一个“拷问式”Skill。这个Skill告诉Agent：“写任何代码之前，先采访我。围绕这个计划的每个方面问我详细问题。沿着决策树的每个分支走下去。直到我们都同意要构建什么为止，不要停。” 这个模式最受欢迎的版本只有三句话。它可以在 Claude Code、Codex 和 Gemini CLI 中运行。用户反馈，Agent在开始编码前会连续问 16 到 50 个问题。 这听起来很慢。但一次充分拷问后的单次成功率，远高于另一种选择：先开始编码，然后在损害已经发生后再修正错位。 失败模式 2：Agent太啰嗦 Agent进入你的项目后，会边做边理解本地术语。你的代码库把某个东西叫作 “materialization cascade”，但Agent不知道这个术语，于是它写成“课程某个章节里的某节课在文件系统中给定位置变成真实内容的过程”。一个 2 个词的概念，被写成了 24 个词。 这个问题会复利增长。每次会话，Agent都会从零重新发现你的词汇。它会消耗 token，不断重述上一次其实已经弄明白的东西，而冗长描述会挤占真正有用的工作。 修复方式是共享语言Skill。它会在你的项目中维护一个术语表文件，通常叫 CONTEXT.md。Agent在每次会话开始时读取它。 变量、函数和文件会以一致方式命名。Agent因为能使用更紧凑的语言，思考时消耗的 token 更少。 Eric Evans 早在 2003 年的 Domain Driven Design 中就把这称为“通用语言”。这个概念比 AI Agent更早。Skill只是把它自动化了。 失败模式 3：代码不能运行 你的Agent写出的代码看起来合理，但运行时会坏。它没有反馈告诉自己输出能不能跑。如果没有测试、类型检查，或浏览器可供观察，Agent就是在盲写代码。 修复方式是反馈循环Skill。最有效的版本是 TDD（测试驱动开发）Skill，它强制执行 red green refactor 循环：Agent先写一个失败测试，再写通过测试所需的最少代码，然后清理。 实现开始之前，测试必须先失败。这是结构性门槛，不是建议。 为什么这重要？因为Agent会跳过这一步，先写代码，再补测试。那会破坏测试驱动的意义。 写得好的 TDD Skill会把顺序变成不可协商：先 red，再 green，再 refactor。Skill把提醒变成规则。 失败模式 4：代码库变成泥潭 AI Agent会加快编码速度。这是卖点。但它们也会加快软件熵增。