如何为你的 AI Agent 创建合适的 Skill
AI Guides (@free_ai_guides)
2026-06-30
D
原文
---
title: "如何为你的 AI Agent 创建合适的 Skill"
author: "AI Guides (@free_ai_guides)"
source_url: "https://x.com/free_ai_guides/status/2071666929451094227"
published_at: "2026-06-29T18:47:40.000Z"
fetched_at: "2026-06-30T15:23:11Z"
updated_at: "2026-06-30T15:26:37Z"
language: "zh"
review_status: "draft"
---
# 如何为你的 AI Agent 创建合适的 Skill
你的 AI agent 不需要再多一个 prompt。它需要的是一个 skill。
Prompt 是一次性指令。你输入它，agent 照着做；到了下一次会话，整段对话都没了。你每次都要从零开始。
Skill 是放在项目里的可复用工作流文件。你只写一次。每当这个任务再次出现，agent 就会加载它，并反复遵循同一套已定义流程。
数据也支持这一点。SkillsBench 是第一个经过同行评审的 agent skill 基准测试（发表于 2026 年 2 月，覆盖 11 个领域的 84 项任务）。它发现，经过整理的 skills 能让 agent 的平均通过率提高 16.2 个百分点。由 agent 自己尝试生成的 skills 则完全没有表现出可靠提升。
变量在于 skill 的质量。随着 agent 越来越强，会写好 skill 的人，会比那些只是在聊天窗口里输入指令然后碰运气的人领先得更远。
Skill 格式本身也不再是某个厂商的单独功能。Anthropic 于 2025 年 12 月在 [agentskills.io](http://agentskills.io/) 发布了 Agent Skills 规范，作为开放标准。三个月内，OpenAI 的 Codex、Google 的 Gemini CLI、GitHub Copilot、Cursor、VS Code，以及数十种其他工具，都采用了同一种格式。
截至 2026 年中，已有 40 多款产品支持 SKILL.md 标准。写一次 skill，它就能在所有主流 coding agent 中无需修改地运行。
这篇指南会覆盖全部内容：什么是 skill，如何从零写一个 skill，如何避开社区共享 skills 中的安全陷阱，以及当你开始构建 skills 后，日常工作会发生什么变化。
把这篇存下来。这一周你都会用到它。
### Skill 到底是什么
Skill 是一个文件夹。里面有一个叫 [SKILL.md](http://skill.md/) 的文件。这个文件分成两部分：一个简短的头部，包含 skill 的名称和描述（用 YAML 写）；以及正文，包含 agent 应该遵循的实际指令（用普通 Markdown 写）。
```markdown
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
```
[SKILL.md](http://skill.md/) 文件是唯一必需的组成部分。其他所有内容都是可选的，并且只会在 agent 需要时加载。
### Skills 如何加载（渐进式披露）
你的 agent 不会在每次会话开始时读取所有已安装的 skills。那样会塞满它的上下文窗口，让它变得更笨。相反，skills 会分三层加载：
**第一层：只有名称和描述。** 会话开始时，agent 只读取每个已安装 skill 的名称和一行描述。每个 skill 大约消耗 30 到 50 个 token。足以知道有哪些可用内容，又不会烧掉上下文。
**第二层：完整指令。** 当 agent 判断某个 skill 与当前任务相关时，它会把完整的 SKILL.md 正文拉进上下文。此时它就拥有了完整工作流。
**第三层：参考文件。** 如果指令引用了外部文件（脚本、模板、文档），agent 只会在执行到需要它们的步骤时才加载这些文件。
这套三层系统解释了为什么你可以安装几十个 skills，而不会拖慢 agent。它会在需要的时候，只加载最少的必要内容。
### **Skill、Prompt 和配置文件的区别**
这三者经常被混淆。区别其实很直接。
**Prompt** 是你输入到聊天里的单次指令。比如：“检查这段代码有没有 bug。”会话结束后它就消失了。
**配置文件**（比如 CLAUDE.md、AGENTS.md 或 .cursorrules）是一组在每次会话开始时都会推给 agent 的指令。比如：“始终使用 TypeScript。遵循我们的命名约定。永远不要 push 到 main。”
这些是一直开启的规则，适用于 agent 做的所有事情。
**Skill** 介于两者之间。它不是一直开启的（那会浪费上下文），也不是一次性的（那会浪费你写它的精力）。它会在任务匹配时按需拉取。
Agent 会读取描述并判断：“这个任务适合那个 skill。”然后它会加载完整指令，并遵循已定义的工作流。
这种区别的技术术语是 **push vs. pull**。配置文件会把指令推给 agent，不管它需不需要。Skills 让 agent 在识别出合适时机时，自己拉取指令。
### **两类 Skills**
**用户调用的 skills** 是由你自己触发的。你输入 /grill-me 或 /tdd，agent 就开始执行这个工作流。这类 skill 用于编排：在一个明确时刻启动一个已定义流程。
**模型调用的 skills** 是 agent 可以在任务匹配时自行调用的。你不需要输入命令。
Agent 会读取 skill 的描述，识别匹配项，然后把它拉进来。这类 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 agents 会以可预测的方式失败。任何和 coding agent 相处过一个月的开发者，都会遇到同样四类问题。理解哪一类问题让你损失最多，就能告诉你应该先构建哪个 skill。
### 失败模式 1：Agent 没有做你想要的事
这是最常见的一类。你描述想要什么。Agent 接受任务并开始构建。
你回来后发现，它理解成了和你本意不同的东西。
根因是对齐不足。在跳到写代码之前，你和 agent 没有就问题形成共同理解。
Frederick P. Brooks 在 *The Design of Design* 中用“设计树”描述过这一点。每个设计都有一系列决策分支，需要先解决，才能投入构建。跳过这些分支，你就是在假设上构建。
解决办法是一个追问式 skill（grilling skill）。这个 skill 告诉 agent：“在你写任何代码之前，先采访我。就这个计划的每个方面向我提出详细问题。沿着决策树的每个分支走下去。在我们都同意要构建什么之前，不要停。”
这个模式最流行的版本只有三句话。它可以在 Claude Code、Codex 和 Gemini CLI 中运行。用户反馈称，在 agent 开始写代码之前，会有 16 到 50 个问题的会话。
这听起来很慢。但经过充分追问之后的一次成功率，要远高于另一种做法：直接开始写代码，然后在损害已经造成之后再修正错位。
### 失败模式 2：Agent 太啰嗦了
Agents 被扔进你的项目后，会边做边摸索本地术语。你的代码库把某个东西叫作 “materialization cascade”，但 agent 不知道这个术语，于是它会写成 “the process by which a lesson inside a section of a course is made real, given a spot in the file system”。一个 2 个词的概念，被写成了 24 个词。
这个问题会不断叠加。每次会话里，agent 都会从头重新发现你的词汇。它消耗 token，重复说明上次已经搞明白的东西，而这些冗长描述会挤占真正有用的工作。
解决办法是一个共享语言 skill（shared language skill）。这个 skill 在你的项目中维护一个术语表文件（通常叫 CONTEXT.md）。Agent 会在每次会话开始时读取它。
变量、函数和文件的命名会保持一致。Agent 用于思考的 token 会更少，因为它能使用一套更紧凑的语言。
Eric Evans 早在 2003 年的 *Domain-Driven Design* 中就把这称为“通用语言”（ubiquitous language）。这个概念比 AI agents 老得多。Skill 把它自动化了。
### 失败模式 3：代码跑不起来
你的 agent 写出了看起来合理、但运行时会坏的代码。它没有得到任何关于输出能否运行的反馈。没有测试、没有类型检查，也没有浏览器可看时，agent 就是在闭眼写代码。
解决办法是一个反馈循环 skill（feedback loop skill）。最有效的版本是一个 TDD（测试驱动开发）skill，它强制执行红-绿-重构循环：agent 先写一个失败测试，再写最少的代码让测试通过，然后清理代码。
测试必须在实现开始之前失败。这是一个结构性关卡，不是建议。
为什么这很重要？因为 agents 会跳过测试，先写代码，再回头补测试。那就违背了测试的目的。
写得好的 TDD skill 会把顺序变成不可协商：先红，再绿，再重构。Skill 会把一个提醒变成一条规则。
### 失败模式 4：代码库变成泥潭
AI agents 会加快编码速度。这是它们的卖点。但它们也会加快软件熵增。
任何没有考虑代码库整体结构的改动，都会引入小的不一致。这些不一致会叠加。经过几周无人监督的 AI 生成代码之后，你的项目会变成一团脆弱混乱、彼此缠绕的小文件，人类和 agent 都无法推理。
John Ousterhout 在 *A Philosophy of Software Design* 中把这描述为深模块和浅模块的区别。深模块用简单接口隐藏大量功能。浅模块几乎只是围着一点点东西包了一层薄壳。
Agents 倾向于生成浅模块，因为它们容易生成。但浅代码库难以测试，难以修改，也难以让其他 agents 接手。
解决办法是一个架构 skill（architecture skill），它会定期扫描代码库，寻找可以把模块做深的地方：理解一个概念是否需要在十个文件之间来回跳转？
是否为了可测试性抽出了纯函数，但真正的 bug 却藏在它们的调用方式里？紧耦合模块是否跨越边界泄漏？
每周运行一次这样的 skill，可以让代码库对人类和 agents 都保持健康。
---
### 写你的第一个 SKILL.md
你已经识别出最大的失败模式。现在构建一个能修复它的 skill。
**头部（YAML Frontmatter）**
每个 SKILL.md 都以一个包在三条短横线之间的 YAML 块开头。两个字段是必需的：**name** 和 **description。**
```yaml
---
name: code-review-checklist
description: >
Run a structured code review on the current changeset.
Trigger when reviewing PRs or before merging any branch.
Do not use for architecture-level reviews. Use the
architecture skill instead.
---
```
Description 字段是整个 skill 中最重要的一段文字。Agent 会读取它，以判断是否应该为当前任务加载这个 skill。
把关键词和触发条件放在最前面。明确说明什么时候这个 skill 不应该触发。含糊的描述会导致错误匹配，浪费上下文并让 agent 困惑。
**正文（Markdown 指令）**
在头部下面，写下 agent 应该遵循的工作流。普通 Markdown 即可。不需要特殊语法。
```markdown
# Code Review Checklist
When reviewing a changeset:
1. Read the diff in full before commenting.
2. Check for test coverage on every new function.
3. Flag any function longer than 40 lines.
4. Verify naming follows CONTEXT.md conventions.
5. If a module's public interface changed, confirm
the changelog entry exists.
6. Summarize findings in a structured comment:
pass/fail per check, with line references.
```
这就是一个完整的 skill：一个文件，六个步骤。现在，每次它审查代码时，agent 都会在你使用的所有兼容工具中运行这份完全相同的 checklist。
### 保持简短
GitHub 上最流行 skills 仓库里，影响最大的 skill 只有三句话。它告诉 agent 采访用户关于计划的细节，沿着设计树的每个分支走下去，并在向用户提问之前先探索代码库寻找答案。
这三句话已经被安装超过 25 万次。
Skill 不需要很长。它需要在合适的时刻选对词。
如果你发现自己写的 skill 超过两页纸，很可能是把两个 skills 合到了一起。拆开。一个 skill，只做一件事。
### 先从无状态开始，之后再做有状态
无状态 skill 不会在会话之间保存任何东西。它运行、完成任务，然后不留下痕迹。
每次调用都是重新开始。你的第一个 skill 应该是无状态的，因为出错的地方更少。
有状态 skill 会把文件保存到磁盘上（术语表、进度追踪器、上下文文档），并在会话之间持续存在。它们更强大，但也更复杂。
前面描述的共享语言 skill 是有状态的，因为它会维护 CONTEXT.md。教学 skill 也可以是有状态的，因为它会追踪学习者已经学过什么。
先构建无状态 skills。当你真正感受到每次会话都从零开始的限制时，再加入状态。
---
## 不要下载有毒内容
社区中心（如 SkillsMP）索引了超过 190 万个公开 skills，它们是从世界各地的 GitHub 仓库抓取来的。大多数没问题。有些则不是。
2026 年 2 月，[prplbx.com](http://prplbx.com/) 的安全研究人员在公开目录中发现了 341 个恶意 skills。这些 skills 包含隐藏 payload（载荷）：数据外泄、凭证盗窃，以及把 agent 重定向到执行未授权命令的 prompt injection（提示注入）。Snyk 后续的一项审计（“ToxicSkills”报告）测试了更广泛的样本，并发现受检 skills 中有 36% 存在 prompt injection 漏洞。
### 质量也没有保证
除了安全，还有质量问题。SkillsBench 研究团队在为基准测试挑选精选 skills 之前，审计了超过 47,150 个公开 skills。大多数公开 skills 都不达标：描述含糊，会在错误任务上触发；指令太泛，无法产生一致输出；没有清晰的工作流结构。
当 SkillsBench 比较 agent 使用精选 skills 和自生成 skills 时，那些尝试自己写 skills 的模型没有表现出任何可靠提升。Skill 的质量比“有一个 skill”这件事本身更重要。
一个经过整理、结构良好的 skill，和从社区目录随手拉来的随机 skill 之间的差距，就是受过训练的流程和猜测之间的差距。如果你要使用社区 skills，就从有可见安装量、活跃维护者的成熟来源中挑选。或者自己写。
### 先审计，再采用
安装任何社区 skill 之前：
1. 阅读完整的 SKILL.md。不要只看名称和描述。
2. 如果存在 scripts/ 文件夹，打开它。阅读每个文件。如果脚本会从互联网下载东西，或访问环境变量，你需要理解为什么。
3. 检查发布者是谁。一个只有一个 repo、零粉丝的匿名 GitHub 账号，和一个有多年公开工作的成熟开发者，风险画像不同。
4. 先在一次性项目上测试它。永远不要把未经测试的 skill 直接安装进生产代码库。
这和你对 npm 包或 VS Code 扩展应用的卫生习惯一样。Skills 是在你的 agent 内部运行的代码。也要按这个标准对待它们。
---
### 当你开始构建 Skills，会发生什么变化
一开始，这个转变感觉很小。你写一个 [SKILL.md](http://skill.md/)，安装它，然后你的 agent 会遵循一份它过去经常跳过的 checklist。
这很有用。但真正重要的是复利效应。
**你不再重复自己**
在 skills 之前，每次会话都从你重新解释偏好开始。“使用 TypeScript。遵循我们的命名约定。先写测试。不要使用 any-types。”
有了 skills，这些指令会存在文件里。你写一次，agent 每次都会把它们拉进来。你每次会话的第一句话可以直接是任务本身，而不是设定仪式。
**你的 Agent 变得可预测**
没有 skills 的 agent 是一个很能干的即兴发挥者。它能处理大多数任务，但每次会话的方法都会变化。
有时它先写测试。有时不写。有时它会问澄清问题。有时它直接开始构建。
有 skills 的 agent 会遵循已定义流程。TDD skill 确保测试先于代码。Grilling skill 确保在实现前先对齐。
Architecture skill 确保代码库不会腐烂。你不再希望 agent 做出好选择，而是知道它会遵循好流程。
**你的工具变得可以互换**
因为 skills 遵循开放的 SKILL.md 标准，所以当你切换 agents 时，工作流也会随之迁移。从 Claude Code 转到 Codex，或者在 Gemini CLI 旁边再加上 Cursor，你的 skills 都会跟着你。
你的流程是可移植的。无论你最终选择哪款工具，写好 skills 的投入都会继续回报你。
**你开始编码自己的工作方式**
这是更深层的转变。Skill 不只是给 agent 的指令。它是你如何思考一项任务的形式化版本。
写 skill 这件事会迫使你把流程说清楚：你会遵循哪些步骤？顺序是什么？决策点在哪里？
大多数工程师把这些知识作为直觉带在身上。把它写成 skill，会让它可以转移给 agents、队友，以及未来的你自己。
---
### 从这里开始
选出最耗费你时间的失败模式。写一个解决它的 [SKILL.md](http://skill.md/)。控制在 30 行以内。安装它。运行一周。然后再写下一个。
把 AI agents 当作聊天窗口的人，会每天早上继续粘贴同样的指令。把它们当作带有编码流程的团队成员的人，则会一轮会话接一轮会话、一个 skill 接一个 skill 地积累生产力复利。
Skills 可以跨工具移植，可以跨工作流组合，并且会随着时间复利增长。这就是使用 AI 和用 AI 构建之间的区别。
---
**资源：**
→ Agent Skills 规范：[agentskills.io](http://agentskills.io/)
→ [SKILL.md](http://skill.md/) 格式参考和示例：[github.com/agentskills/agentskills](http://github.com/agentskills/agentskills)
→ 浏览社区 skills：[skills.sh](http://skills.sh/)
→ 安全审计发现：搜索 “ToxicSkills Snyk 2026” 查看完整报告
→ SkillsBench 研究论文：[arxiv.org/abs/2602.12670](http://arxiv.org/abs/2602.12670)（84 项任务、11 个领域、同行评审）
关注 @free_ai_guides，获取每日 AI 技巧、指南和资源。