别再重复写提示词了：给你的 AI Agent 做一个 Skill
提示词只在当前会话生效，Skill 才能把一套工作流沉淀到项目里。本文翻译整理一套从设计、加载到安全审查的 Agent Skill 方法。
如何为你的 AI Agent 创建合适的 Skill
你的 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 以及其他数十种工具都采用了同一种格式。
截至 2026 年年中，已有 40 多款产品支持 SKILL.md 标准。只需编写一次 Skill，就能在所有主流编码 Agent 中运行，无需修改。
本指南涵盖全部关键内容：Skill 是什么、如何从零开始编写 Skill 、如何避开社区共享 Skill 中的安全陷阱，以及当你开始构建 Skill 后，日常工作会发生哪些变化。
把它保存下来。接下来一周你都会用到它。
Skill 到底是什么
Skill 是一个文件夹。里面有一个名为 SKILL.md 的文件。这个文件由两部分组成：一段简短的头部信息，用 YAML 写成，包含 Skill 的名称和描述；以及一个正文，用普通 Markdown 写成，包含 Agent 应该遵循的实际指令。
my-skill/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
└── assets/ # 可选：模板、资源
SKILL.md 是唯一必需的组件。其他内容都是可选的，只有在 Agent 需要时才会加载。
Skill 如何加载：渐进式披露
你的 Agent 不会在每次会话开始时读取所有已安装的 Skill 。那会淹没它的上下文窗口，让它变得更迟钝。相反，Skill 会分为三个层级加载：
第 1 层：仅加载名称和描述。 会话开始时，Agent 只读取每个已安装 Skill 的名称和一行描述。每个 Skill 消耗 30 至 50 个 Token 。这样既能让 Agent 知道有哪些能力可用，又不会过度占用上下文。
第 2 层：加载完整指令。 当 Agent 判断某个 Skill 与当前任务相关时，它会把完整的 SKILL.md 正文载入上下文。此时，它就拥有了完整的工作流。
第 3 层：加载参考文件。 如果指令中引用了外部文件（脚本、模板、文档），Agent 只会在执行到需要它们的步骤时加载这些文件。
正是这套三层系统，让你可以安装几十个 Skill，而不会拖慢 Agent 。它只在需要时加载最低限度的内容。
Skill 、提示词与配置文件的区别
这三者经常被混淆。区别其实很简单。
提示词是你输入聊天窗口的一次性指令，例如：“检查这段代码中的 Bug 。”会话结束后，它就消失了。
配置文件（例如 CLAUDE.md 、 AGENTS.md 或 .cursorrules）是一组在每次会话开始时都会被推送给 Agent 的指令，例如：“始终使用 TypeScript 。遵循我们的命名规范。绝不要推送到 main 分支。”
这些是始终生效的规则，适用于 Agent 执行的所有任务。
Skill 位于两者之间。它不是始终开启的规则（那会浪费上下文），也不是一次性的指令（那会浪费你编写它的精力）。只有当任务匹配时，它才会按需加载。
Agent 会读取 Skill 的描述并做出判断：“这个任务符合该 Skill 。”随后，它会加载完整指令，并遵循其中定义的工作流。
这种区别的技术术语是“推送”与“拉取”。配置文件无论 Agent 是否需要，都会把指令推送给它；Skill 则允许 Agent 在识别到合适时机后，再主动拉取相应指令。
两种类型的 Skill
用户调用型 Skill 是由你主动触发的 Skill 。你输入 /grill-me 或 /tdd，Agent 就会启动相应工作流。这类 Skill 用于编排：在确定的时刻启动一套确定的流程。
模型调用型 Skill 是 Agent 在任务匹配时可以自行调用的 Skill 。你不需要输入命令。
Agent 会读取 Skill 的描述，识别出匹配关系，然后将它拉取进来。这类 Skill 用于纪律性约束：把无需额外提醒就能执行的良好实践嵌入工作流。
两种类型都使用相同的 SKILL.md 格式。区别在于触发方式，而不是构建方式。
默认跨平台
在 Agent Skills 标准出现之前，每种工具都有自己的定制格式。 Cursor 使用 .cursorrules，Claude Code 使用 /commands，Copilot 使用指令文件。
一旦切换工具，你的定制内容就无法迁移。
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 在《设计的设计》中将其描述为“设计树”。每个设计都有一系列需要解决的决策分支，只有在这些分支得到处理后，才能决定开始构建。跳过这些分支，就等于建立在假设之上。
解决办法是使用一个“追问式” Skill 。它要告诉 Agent：“在编写任何代码之前，先采访我。针对计划的每个方面提出详细问题。沿着决策树逐一走完每个分支。在我们都同意要构建什么之前，不要停下来。”
这一模式最流行的版本只有三句话。它可以运行在 Claude Code 、 Codex 和 Gemini CLI 中。用户反馈，在 Agent 开始编码之前，往往会经历 16 至 50 个问题。
听起来很慢。但经过充分追问后，一次成功的概率远高于另一种做法：先开始编码，等造成损失后再修正理解偏差。
失败模式 2：Agent 过于啰嗦
Agent 被放进项目后，会一边工作一边理解项目中的本地术语。你的代码库把某个概念称作“materialization cascade”，但 Agent 不知道这个术语，于是写下：“使课程某个章节中的一节课在文件系统中获得实际位置的过程。”这相当于用 24 个词解释一个 2 个词的概念。
这个问题会不断累积。每次会话中，Agent 都要从头重新发现你的词汇。它消耗 Token，重复说明上一次已经理解过的内容；冗长的描述还会挤占真正有用的工作空间。
解决办法是使用一个共享语言 Skill，在项目中维护一个术语表文件（通常称为 CONTEXT.md）。 Agent 会在每次会话开始时读取它。
变量、函数和文件会获得一致的命名。由于可以使用更紧凑的语言，Agent 在思考时需要消耗的 Token 更少。
Eric Evans 在 2003 年出版的《领域驱动设计》中，将其称为“通用语言”。这个概念早于 AI Agent，而 Skill 可以将它自动化。
失败模式 3：代码无法运行
你的 Agent 写出的代码看起来合理，却在运行时崩溃。它没有收到任何关于输出是否能够运行的反馈。没有测试、类型检查或浏览器可供观察时，Agent 就是在盲目编码。
解决办法是使用反馈回路 Skill 。最有效的版本是一个强制执行 TDD（测试驱动开发）的 Skill，要求遵循“红—绿—重构”循环：Agent 先写出失败的测试，再编写让测试通过的最少代码，最后进行整理。
实现开始之前，测试必须先失败。这是一道结构性关卡，而不是建议。
为什么这很重要？因为 Agent 往往先写代码，之后再补测试。这样就违背了测试驱动开发的目的。
一份写得好的 TDD Skill 会让顺序变得不可协商：先红，再绿，最后重构。 Skill 把提醒变成了规则。
失败模式 4：代码库变成一团乱麻
AI Agent 能够加快编码速度，这正是它的卖点。但它也会加速软件熵增。
每次变更如果没有考虑代码库的整体结构，就会引入一些细小的不一致。这些不一致会不断累积。几周时间里，如果放任 AI 生成代码而不加监督，你的项目就可能变成一堆脆弱、细小且相互交织的文件，无论人还是 Agent 都很难进行推理。
John Ousterhout 在《软件设计哲学》中，将其描述为深模块与浅模块的区别。深模块拥有简单的接口，却隐藏了大量功能；浅模块几乎没有隐藏任何内容，只是对极少功能进行薄薄的包装。
Agent 往往会生成浅模块，因为它们容易产生。但浅层代码库难以测试、难以修改，也难以让其他 Agent 继续工作。
解决办法是使用一个架构 Skill，定期扫描代码库，寻找可以加深模块的地方：理解一个概念是否需要在十个文件之间来回跳转？
是否为了便于测试而抽离了纯函数，但真正的 Bug 却隐藏在调用方式中？紧耦合的模块是否越过边界彼此泄漏？
每周运行一次这样的 Skill，可以让代码库同时保持对人和 Agent 都友好的状态。
编写你的第一个 SKILL.md
你已经找到了代价最大的失败模式。现在，构建一个能够解决它的 Skill 。
头部信息（YAML Frontmatter）
每个 SKILL.md 都以三条短横线包围的 YAML 区块开头。必需字段有两个：name 和 description 。
---
name: code-review-checklist
description: >
对当前变更集执行结构化代码审查。
在审查 PR 或合并任何分支之前触发。
不要用于架构级审查。请改用 architecture skill。
---
description 字段是整个 Skill 中最重要的文本。 Agent 会读取它，以决定当前任务是否应该加载这个 Skill 。
把关键词和触发条件放在最前面。明确说明 Skill 什么时候不应该触发。模糊的描述会导致错误匹配，浪费上下文，还会让 Agent 感到困惑。
正文（Markdown 指令）
在头部信息下方，写出 Agent 应该遵循的工作流。使用普通 Markdown，无需特殊语法。
# Code Review Checklist
审查变更集时：
1. 在发表评论之前完整阅读 diff。
2. 检查每个新增函数是否都有测试覆盖。
3. 标记任何超过 40 行的函数。
4. 验证命名是否遵循 CONTEXT.md 中的约定。
5. 如果某个模块的公共接口发生变化，确认是否存在
对应的变更日志条目。
6. 用结构化评论总结发现：
每项检查标注通过/失败，并附上行号引用。
这就是一个完整的 Skill：一个文件，六个步骤。现在，每当你审查代码时，无论使用哪一种兼容工具，Agent 都会运行这份完全相同的检查清单。
保持简短
GitHub 上最受欢迎的 Skill 仓库中，影响力最大的 Skill 只有三句话。它告诉 Agent：围绕计划采访用户，沿着设计树的每个分支逐一推进，并在向用户提问之前先从代码库中寻找答案。
这三句话已经被安装超过 25 万次。
Skill 不需要很长。它需要在正确的时刻选择正确的措辞。
如果你发现自己写出的 Skill 超过了两页打印纸，那么你很可能把两个 Skill 合并成了一个。把它们拆开。一个 Skill，只做一件事。
先从无状态开始，再逐步引入状态
无状态 Skill 不会在会话之间保存任何内容。它运行、完成任务，然后不留下痕迹。
每次调用都会从头开始。你的第一个 Skill 应该是无状态的，因为这样出错的地方更少。
有状态 Skill 会将文件保存到磁盘（术语表、进度跟踪器、上下文文档），这些文件会跨会话持续存在。它们更强大，但也更复杂。
前面介绍的共享语言 Skill 就是有状态的，因为它会维护 CONTEXT.md 。教学 Skill 也可以是有状态的，因为它会跟踪学习者已经掌握的内容。
先构建无状态 Skill 。当你真正感受到每次会话都从头开始的限制后，再添加状态。
不要下载有害 Skill
在 SkillsMP 等社区中心，已经有超过 190 万个公开 Skill 被索引；这些 Skill 抓取自世界各地的 GitHub 仓库。大多数没有问题，但其中也有一些并非如此。
2026 年 2 月，prplbx.com 的安全研究人员在公开目录中发现了 341 个恶意 Skill 。这些 Skill 包含隐藏载荷：数据外泄、凭据窃取，以及将 Agent 重定向去执行未经授权命令的提示词注入。随后，Snyk 进行了一项更广泛样本的审计，在名为“ ToxicSkills ”的报告中指出，受检 Skill 中有 36% 存在提示词注入漏洞。
质量也并非有保障
除了安全问题，还有质量问题。 SkillsBench 研究团队在为基准测试挑选经过整理的 Skill 之前，审计了超过 47,150 个公开 Skill 。大多数公开 Skill 都不够完善：描述模糊，容易在错误任务上触发；指令过于笼统，无法产生稳定输出；也没有清晰的工作流结构。
当 SkillsBench 对比使用整理后的 Skill 与由 Agent 自行生成的 Skill 时，那些尝试自己编写 Skill 的模型没有表现出任何可靠的提升。 Skill 是否存在并不是关键，关键在于它的质量。
一个经过整理、结构良好的 Skill，与从社区目录中随手找来的 Skill 之间的差距，就像训练有素的流程与一次猜测之间的差距。如果你打算使用社区 Skill，请从有良好基础、安装数量公开且维护者活跃的来源中选择。或者，自己编写。
采用前先审计
在安装任何社区 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 当作聊天窗口的人，会继续每天早上粘贴同样的指令。把 AI 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 技巧、指南与资源。