先说结论：Skill 是一套标准化的、可复用的、跨 Agent 平台共享的「知识包」。它不是系统 prompt 的包装纸，不只是给 AI 加一段指令，而是一个自带上下文、脚本、参考资料的完整文件夹。
一个 Skill 的目录结构长这样：
my-skill/ ├── SKILL.md # 必需：元数据 + 指令 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：参考文档 └── assets/ # 可选：模板、图片等资源核心只有一个：SKILL.md 文件。它用 YAML frontmatter 声明自己的名字和触发条件，正文里写清楚做这件事的步骤和注意事项。
一个最简单的 Skill 只需要 10 行：
--- name: roll-dice description: Roll dice using a random number generator. --- To roll a die, use the following command that generates a random number from 1 to the given number of sides: echo $((RANDOM % <sides> + 1)) Replace <sides> with the number of sides on the die.就这么简单。但就是这套极简的约定，催生了一个 13.6 万星的项目和一个 25+ 平台的生态系统。
为什么「文件夹」这个设计是刻意为之
这里有一个设计决策，大多数写 Skills 教程的人不会提，但我觉得它是整个架构里最聪明的一步：渐进式加载（Progressive Disclosure）。
Skill 分三层加载：
- 第一层：元数据（约 100 tokens）。Agent 启动时，只读取每个 Skill 的
name和description，够它判断「这个 Skill 能不能用在这里」就行。 - 第二层：指令正文（推荐 < 5000 tokens）。当 Agent 判断 Skills 匹配当前任务，才把完整的 SKILL.md 加载进上下文。
- 第三层：附属资源（按需加载）。
scripts/里的脚本、references/里的详细文档，只有实际用到的时候才读。
这意味着什么？意味着你可以在一个项目里放 50 个 Skill，Agent 启动时的上下文开销只比放 1 个 Skill 多那么一点点——因为每次只加载元数据。相比之下，如果你把同样的 50 段说明书直接塞进系统 prompt，上下文早就爆了。
这个设计让 Skills 的「可堆叠性」成为现实。你不需要在「功能丰富」和「上下文不够」之间做取舍——这是 MCP Server 和 Plugin 做不到的。
一个更贴近真实开发的例子
上面那个掷骰子的 Skill 只是一个入门演示。来看看一个真实的、在生产环境里能用的 Skill 长什么样。
假设你的团队有一个 Java 项目，所有数据库查询都要加deleted_at IS NULL做软删除过滤，但新来的 AI Agent 根本不知道这个约定。于是它生成的 SQL 会把已删除的数据也算进来——这种事情在生产环境里发生一次，后果不用我说。
把这个约定写成 Skill：
--- name: java-db-query description: Write database queries for our Java project. Use when writing SQL, JPA, or MyBatis queries involving database tables that use soft deletes. --- ## Database Query Conventions ### Soft Delete Rule (CRITICAL) All tables use soft deletes via a `deleted_at` column. Every SELECT query MUST include `WHERE deleted_at IS NULL` unless the user explicitly asks for deleted records. ### Gotchas - The `users` table uses `user_id` in the DB, but `uid` in the auth service. Both refer to the same value. Never confuse them. - The `/health` endpoint returns 200 even if the DB is down. Always use `/ready` for health checks. ### Example - Correct Query SELECT * FROM orders WHERE user_id = ? AND deleted_at IS NULL ORDER BY created_at DESC; ### Example - Wrong (Will Include Deleted Records) SELECT * FROM orders WHERE user_id = ?;这个 Skill 放到项目里的.claude/skills/目录下，每次 AI 写 SQL 的时候，它会自动加载这些约束。一个团队在 CI 里跑了 100 次 SQL 生成的测试，有 Skill 的情况下，SQL 的正确率从 42% 提升到了 91%。
这就是为什么这个「文件夹」值 13.6 万星——它解决的不是一个技术问题，而是一个范式问题：怎么让 AI 真正理解你的项目，而不是每次都从零开始猜。
Skill vs MCP vs Plugin：三者的本质区别
这个话题必须讲清楚，因为我在各种技术群里看到太多人在问同样的问题：「Skills 和 MCP Server 到底什么关系？是不是竞品？」
答案是：它们是不同层面的东西，互补关系，不是替代关系。
打个类比：
| Skill | MCP Server | Plugin | |
|---|---|---|---|
| 本质 | 做事的方法论 | 外部工具的接口 | 平台的扩展模块 |
| 给 Agent 什么 | 「怎么干」的 know-how | 「能调用什么」的工具能力 | 「多了什么功能」的扩展 |
| 类比 | 老师傅的操作手册 | 工具箱里的新工具 | 给车装的新零件 |
| 格式标准 | SKILL.md（开放标准） | JSON-RPC over stdio/SSE | 各平台自定义 |
| 跨平台 | 任意兼容 Agent Skills 的平台 | 任意支持 MCP 的客户端 | 仅限特定平台 |
| 上下文开销 | 渐进式加载，极低 | 每次调用固定开销 | 取决于平台 |
更具体地说：
Skill 告诉你「怎么把一件事做对」。比如「写 SQL 的时候记得加deleted_at IS NULL」「用 pdfplumber 做 PDF 文本提取」「做 code review 的时候重点看认证检查和安全漏洞」。它是知识层面的东西。
MCP Server 给你「能做一件新的事」。比如「去数据库里查这张表」「往 Slack 发一条消息」「调一下 GitHub API 创建 Issue」。它是能力层面的东西——Agent 本来不会连接外部系统，MCP 给了它那个连接。
Plugin 给平台加「一个新功能模块」。比如 VS Code 的 GitLens 插件、Claude Code 的 plugin marketplace。它是平台层面的扩展。
三者可以协同工作：一个 Skill 里可以写「用 MCP Server X 去查数据库，然后按这个格式输出」。Skill 是大脑，MCP 是手，Plugin 是装备栏。
为什么这件事值得花时间理清？因为我在好几个技术群里看到同一个误解：「有了 MCP Server 就够了，要 Skill 干嘛？」——这就像你说「有了扳手就够了，要维修手册干嘛」。工具和知识从来不是二选一。
开发你的第一个 Skill：从零到可用
好，理论讲够了。这一节我带你从头写一个真实可用的 Skill。
场景设定
你的项目是一个 Spring Boot 微服务，所有 REST API 都有统一的响应格式：
{ "code": 200, "message": "success", "data": { ... } }你希望 AI Agent 在写 Controller 的时候，自动遵循这个格式，而不是写出五花八门的响应结构。
第一步：创建 Skill 目录
mkdir -p .claude/skills/spring-api-response cd .claude/skills/spring-api-response目录名必须全小写，用连字符分隔。这个名字就是 Skill 的name。
第二步：写 SKILL.md
--- name: spring-api-response description: Write Spring Boot REST API controllers with the project's standard response format. Use when creating or modifying REST endpoints in a Spring Boot project. --- ## Standard API Response Format All REST endpoints MUST return `ApiResponse<T>`: ```java @Data @AllArgsConstructor @NoArgsConstructor public class ApiResponse<T> { private int code; private String message; private T data; public static <T> ApiResponse<T> success(T data) { return new ApiResponse<>(200, "success", data); } public static <T> ApiResponse<T> error(int code, String message) { return new ApiResponse<>(code, message, null); } }Controller Pattern
@RestController @RequestMapping("/api/users") @RequiredArgsConstructor public class UserController { private final UserService userService; @GetMapping("/{id}") public ApiResponse<UserDTO> getUser(@PathVariable Long id) { UserDTO user = userService.findById(id); return ApiResponse.success(user); } @PostMapping public ApiResponse<UserDTO> createUser(@Valid @RequestBody CreateUserRequest request) { UserDTO user = userService.create(request); return ApiResponse.success(user); } }Gotchas
- Never return raw
ResponseEntityunless you have a specific reason
(like setting custom HTTP headers). TheApiResponsewrapper IS your
HTTP body. - The
codefield follows HTTP status semantics: 200 = success,
400 = bad request, 500 = internal error. Don't invent custom codes. - All DTOs go in
dto/subpackage, not in the controller class as
inner classes.
### 第三步：验证 Skill 是否被加载 在 Claude Code 中安装 Skills 后，启动时会看到技能列表。或者直接让 Agent 帮你写一个 Controller，看它是否自动返回 `ApiResponse<T>`。 ```bash # 在 Claude Code 中测试 > 帮我写一个查询订单列表的 Controller，支持分页如果 Skill 工作正常，Agent 生成的代码会自动包含ApiResponse<PageResult<OrderDTO>>的返回类型和正确的静态方法调用。
第四步：迭代优化
Skills 不是写一次就完事的。我的建议是：每次 Agent 犯了你想纠正的错误，就把纠正规则加到 Skill 里。这是 Skill 积累价值最快的方式。
比如写了上面那个 Skill 后，Agent 还是偶尔忘记在@Valid注解的请求体上处理MethodArgumentNotValidException，那就加一条 Gotcha：
### Gotchas (追加) - When using `@Valid @RequestBody`, ALWAYS add a global `@ExceptionHandler` for `MethodArgumentNotValidException` that returns `ApiResponse.error(400, fieldErrors)`. Without this, validation errors return a raw 400 with Spring's default HTML error page.这就是 Skills 开发的核心循环：发现问题 → 写成 Skill → Agent 不再犯 → 遇到新问题 → 追加规则 → 持续收敛。两周下来，你的 Agent 就会比第一天聪明一大截。
生态全景：从 13.6 万星到 25+ 平台，Skills 正在成为标准
OK，到此为止我们只聊了「Skills 是什么」和「怎么写」。但真正让我觉得这个话题值得专门写一篇文章的，是它的生态——这场爆发来势之快超出了大多数人的预期。
数据层面
截至 2026 年 5 月：
)