如何为你的 AI Agent 创建合适的技能

你的 AI 智能体不需要另一个提示。它需要一个技能。

提示是一次性指令。你输入它，智能体遵循它，到了下一轮会话，整个对话就消失了。你每次都从零开始。

技能是一个可重复使用的工作流文件，放在你的项目中。你编写一次。每次任务出现时，智能体加载它，并重复执行相同的定义流程。

数据也支持这一点。SkillsBench 是第一个经过同行评审的智能体技能基准测试（2026年2月发布，涵盖11个领域84项任务），它发现精选的技能使智能体平均通过率提高了16.2个百分点。而智能体尝试自己生成的技能，则没有任何可靠的改进。

技能的质量是关键变量。随着智能体能力越来越强，懂得如何编写好技能的人，会远远甩开那些只在聊天窗口里输入指令、听天由命的人。

技能格式本身不再是单一供应商的功能。Anthropic 于2025年12月在 agentskills.io 上发布了 Agent Skills 规范作为开放标准。三个月内，OpenAI 的 Codex、Google 的 Gemini CLI、GitHub Copilot、Cursor、VS Code 以及数十种其他工具都采用了相同的格式。

截至2026年中，已有超过40款产品支持 SKILL.md 标准。技能只需编写一次，即可在所有主流编码智能体中无需修改地运行。

本指南涵盖所有内容：技能是什么，如何从头编写一个，如何避免社区共享技能中的安全陷阱，以及一旦开始构建它们，你的日常工作会发生什么变化。

保存好这个。你整周都会用到它。

技能到底是什么

技能是一个文件夹。里面有一个名为 SKILL.md 的文件。该文件包含两部分：一个简短的头部，包含技能的名称和描述（用 YAML 编写），以及一个主体，包含智能体应遵循的实际指令（用纯 Markdown 编写）。

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
└── assets/           # 可选：模板、资源

SKILL.md 文件是唯一必需的组件。其他所有内容都是可选的，并且仅在智能体需要时加载。

技能如何加载（渐进式披露）

你的智能体不会在每个会话开始时读取所有已安装的技能。那会充斥它的上下文窗口，使其变得更笨。相反，技能分三个层级加载：

第一层：仅名称和描述。 当会话开始时，智能体只读取每个已安装技能的名称和一行描述。这每个技能消耗30到50个 token。足以了解可用内容，而不会烧毁上下文。

第二层：完整指令。 当智能体判断某个技能与当前任务相关时，它会将完整的 SKILL.md 主体拉入上下文。现在它有了完整的工作流程。

第三层：参考文件。 如果指令引用了外部文件（脚本、模板、文档），智能体仅在执行到需要它们的步骤时才加载这些文件。

正是这种三级系统，让你可以安装几十个技能而不减慢智能体的速度。它只在需要时加载所需的最小内容。

技能 vs. 提示 vs. 配置文件

这三者经常被混淆。区别很直接。

提示是你输入到聊天中的一次性指令。“检查这段代码的 bug。”它会在会话后消失。

配置文件（如 CLAUDE.md、AGENTS.md 或 .cursorrules）是一组指令，在每个会话开始时总是被推送给智能体。“始终使用 TypeScript。遵循我们的命名约定。永远不要推送到主分支。”

这些是始终开启的规则，适用于智能体所做的一切。

技能介于两者之间。它不是始终开启的（那会浪费上下文），也不是一次性的（那会浪费你编写它的精力）。当任务匹配时，它按需被拉入。

智能体读取描述并判断：“这个任务适合那个技能。”然后它加载完整指令并遵循定义的工作流程。

这个区别的技术术语是推送 vs. 拉取。配置文件将指令推送给智能体，无论它是否需要。技能让智能体在识别到合适时机时拉取指令。

两种类型的技能

用户调用的技能是你自己触发的。你输入 /grill-me 或 /tdd，智能体开始工作流程。这些用于编排，用于在特定时刻启动一个定义好的流程。

模型调用的技能是智能体在任务匹配时自己使用的。你不需要输入命令。

智能体读取技能描述，识别到匹配，然后将其拉入。这些用于纪律，用于嵌入无需询问即可触发的良好实践。

两种类型都使用相同的 SKILL.md 格式。区别在于它们的触发方式，而不是构建方式。

默认跨平台

在 Agent Skills 标准之前，每个工具都有自己定制的格式。Cursor 使用 .cursorrules。Claude Code 使用 /commands。Copilot 使用指令文件。

如果你切换工具，你的定制不会转移。

SKILL.md 开放标准改变了这一点。为 Claude Code 编写的技能可以在 Codex、Gemini CLI、Cursor、Copilot 和 VS Code 中无需修改地运行。兼容工具列表现在超过40种，从终端智能体到完整 IDE 再到基于云的自主系统。

你只需编写一次技能。它能在任何地方运行。

从问题开始，而不是从工具开始

不要坐下来“写一个技能”。而是坐下来修正一个失败模式。

AI 智能体会以可预测的方式失败。每个与编码智能体相处了一个月的开发者都会遇到同样的四个问题。理解哪一个让你损失最大，告诉你应该先构建哪个技能。

失败模式 1：智能体没有做你想做的事

这是最常见的一种。你描述你想要什么。智能体接受任务并开始构建。

你回来发现它理解的意思与你不同。

根本原因是错位。你和智能体在跳到编码之前没有对问题达成共同理解。

Frederick P. Brooks 在《设计的设计》中将其描述为“设计树”。每个设计都有决策分支，需要在着手构建之前解决。跳过这些分支，你就是在假设上构建。

解决办法是盘问技能。一个告诉智能体的技能：“在你编写任何代码之前，先采访我。问我关于这个计划每个方面的详细问题。沿着决策树的每个分支走下去。直到我们都同意我们在构建什么才停下来。”

这个模式最流行的版本只有三句话长。它在 Claude Code、Codex 和 Gemini CLI 中运行。用户报告说，在智能体开始编码之前，会话有16到50个问题。

这听起来很慢。但是，在适当的盘问会话之后的一次性成功率远高于另一种方式：开始编码并在造成损害后修复错位。

失败模式 2：智能体过于啰嗦

智能体被投入你的项目，边做边学习本地行话。你的代码库把某物称为“物化级联”，但智能体不知道这个术语，所以它写下了“课程中某部分内的课程内容变得真实、在文件系统中拥有位置的过程”。这是用24个词来表达一个2个词的概念。

这个问题会累积。每个会话，智能体都会从零开始重新发现你的词汇表。它会消耗令牌，重复陈述它上次已经弄清楚的内容，而冗长的描述会挤占有用的工作。

解决办法是共享语言技能。一个在你的项目中维护一个词汇表文件（通常叫 CONTEXT.md）的技能。智能体在每个会话开始时读取它。

变量、函数和文件命名一致。智能体由于能使用更精炼的语言，从而在思考上花费更少的令牌。

Eric Evans 在2003年的《领域驱动设计》中将其称为“通用语言”。这个概念比 AI 智能体还要古老。这个技能将其自动化。

失败模式 3：代码不工作

你的智能体编写的代码看起来合理，但在运行时崩溃。它没有关于其输出是否运行的反馈。没有测试、类型检查或浏览器查看，智能体是在盲目编码。

解决办法是反馈循环技能。最有效的版本是一个 TDD（测试驱动开发）技能，它强制执行红-绿-重构循环：智能体先写一个会失败的测试，然后写最少的代码使其通过，最后清理。

测试必须在实现开始之前失败。这是一个结构性的门禁，而不是一个建议。

为什么这很重要？因为智能体会先跳到写代码，然后补做测试。这违背了目的。

一个编写良好的 TDD 技能通过使顺序不可协商来防止这种情况：先红，再绿，然后重构。这个技能把一个提示变成了一个规则。

失败模式 4：代码库变得混乱

AI 智能体加速了编码速度。这是卖点。但它们也加速了软件熵。

每个不考虑代码库整体结构的更改都会引入小的不一致。这些会累积。经过几周无监督的 AI 生成代码后，你的项目会变成一个脆弱混乱的、微小文件交织在一起的烂摊子，无论是人类还是智能体都无法理解。

John Ousterhout 在《软件设计的哲学》中将其描述为深层模块和浅层模块的区别。深层模块有一个简单的接口，隐藏了大量功能。浅层模块是几乎不包含任何东西的薄包装。

智能体倾向于产生浅层模块，因为它们很容易生成。但是浅层代码库难以测试、难以更改，并且难以让其他智能体在其中工作。

解决办法是一个架构技能，它定期扫描代码库，寻找可以加深模块的地方：在哪里理解一个概念需要在十个文件之间跳转？

在哪里为了可测试性而提取了纯函数，而真正的 bug 却隐藏在它们被调用的方式中？在哪里紧密耦合的模块跨越了边界？

每周运行一次这样的技能，可以保持代码库对人和智能体都处于良好状态。

编写你的第一个 SKILL.md

你已经确定了最大的失败模式。现在构建修复它的技能。

头部（YAML 前置元数据）

每个 SKILL.md 都以三个破折号之间的 YAML 块开始。两个字段是必需的：name 和 description。

---
name: code-review-checklist
description: >
  对当前变更集执行结构化代码审查。
  在审查 PR 或合并任何分支之前触发。
  不要用于架构级审查。请使用
  架构技能。
---

description 字段是整个技能中最重要的文本。智能体读取它来决定是否为当前任务加载该技能。

将关键词和触发条件前置。明确说明何时不应触发该技能。模糊的描述会导致错误匹配，浪费上下文并混淆智能体。

主体（Markdown 指令）

在头部下方，编写智能体应遵循的工作流程。纯 Markdown。不需要特殊语法。

# 代码审查清单

审查变更集时：

1. 在评论之前完整阅读差异。
2. 检查每个新函数的测试覆盖率。
3. 标记任何超过40行的函数。
4. 验证命名是否符合 CONTEXT.md 约定。
5. 如果模块的公共接口发生变化，确认
   变更日志条目存在。
6. 在结构化评论中总结发现：
   每个检查项通过/失败，并附上行号参考。

这就是一个完整的技能，包含一个文件和六个步骤。现在，智能体每次审查代码时都会运行这个确切的清单，并在你使用的所有兼容工具中执行。

保持简短

GitHub 上最受欢迎的技能仓库中最有影响力的技能只有三句话长。它告诉智能体采访用户了解他们的计划，沿着设计树的每个分支走下去，并在询问用户之前探索代码库寻找答案。

这三句话已经被安装了超过25万次。

技能不需要很长。它需要在正确的时刻选择正确的词语。

如果你发现自己编写的技能超过了两页打印纸，那么你可能正在将两个技能合并成一个。分开它们。一个技能，一个任务。

从无状态开始，稍后变为有状态

无状态技能不会在会话之间保存任何东西。它运行，完成工作，不留痕迹。

每次调用都是全新的开始。你的第一个技能应该无状态，因为出错的可能性更少。

有状态技能将文件保存到磁盘（词汇表、进度跟踪器、上下文文档），这些文件在会话之间持久存在。这些更强大，但也更复杂。

前面描述的共享语言技能是有状态的，因为它维护了 CONTEXT.md。教学技能可以是有状态的，因为它跟踪学习者已经覆盖的内容。

先构建无状态技能。当你感觉到每次会话都从零开始的限制时，再添加状态。

不要下载毒药

社区中心（如 SkillsMP）上索引了超过190万个公共技能，这些技能来自世界各地的 GitHub 仓库。其中大部分没问题。有些则不是。

2026年2月，prplbx.com 的安全研究人员在公共目录中识别出341个恶意技能。这些技能包含隐藏的有效载荷：数据窃取、凭证窃取以及提示注入，这些会重定向智能体以执行未经授权的命令。Snyk 进行的后续审计（“ToxicSkills”报告）测试了更广泛的样本，发现所检查的技能中有36%存在提示注入漏洞。

质量也不保证

除了安全性，还有质量问题。SkillsBench 研究团队在为其基准测试选择精选技能之前，审计了超过47,150个公共技能。大多数公共技能都不达标：描述模糊导致错误触发，指令过于泛泛无法产生一致输出，以及没有清晰的工作流程结构。

当 SkillsBench 比较使用精选技能与自我生成技能的智能体性能时，那些试图自行编写技能的模型没有任何可靠的改进。技能的质量比是否存在一个技能更重要。

精心策划、结构良好的技能与从社区目录中随便拉来的技能之间的差距，是训练有素的流程与猜测之间的差距。如果你要使用社区技能，请从有可见安装计数和活跃维护者的成熟来源中选择。或者自己编写。

采用前审计规则

在安装任何社区技能之前：

• 阅读完整的 SKILL.md。不要只看名称和描述。

• 如果存在 scripts/ 文件夹，请打开它。阅读每个文件。如果脚本从互联网下载东西或访问环境变量，你需要理解原因。

• 检查发布者是谁。一个只有一个仓库、零粉丝的匿名 GitHub 账户与一个拥有多年公开工作的成熟开发者相比，风险状况不同。

• 先在一个可废弃的项目上测试。切勿直接将未测试的技能安装到生产代码库中。

这与你对 npm 包或 VS Code 扩展所采取的卫生做法相同。技能是在你的智能体内部运行的代码。请相应对待。

构建技能会带来什么变化

起初这种感觉很微小。你编写一个 SKILL.md，安装它，你的智能体遵循它过去忽略的清单。

这很有用。但重要的是累积效应。

你不再重复自己

在技能出现之前，每个会话都以你重新解释你的偏好开始。“使用 TypeScript。遵循我们的命名约定。先写测试。不要使用 any 类型。”

有了技能，这些指令就存在于文件中。你编写