Skill 不是提示词的高级写法，而是把「你做事的方法」封装成一份可复用的操作说明书。

在 Claude Code、OpenClaw 这类 AI 工程工具里，Skill（技能） 指的是一个可被智能体按需加载的能力包。它的物理形态通常就是一个文件夹，里面至少有一个 SKILL.md 文件，外加可选的 scripts/、references/、assets/ 等子目录。

SKILL.md 的格式很像前端项目里的 README.md 加上 package.json 的混合体：

  • 顶部的 YAML Frontmatter 写 name 和 description，告诉系统「我是谁、什么时候该用我」。
  • 下面的 Markdown 正文写「该怎么做、输出什么格式、遇到异常怎么办」。

Anthropic 官方把它描述为 procedural memory for AI（AI 的程序化记忆）。翻译成人话：以前你每次都要口头教实习生怎么干活，现在你把流程写成一份手册，他入职第一天就能按手册出活。

和 Skill 经常一起出现的几个词有必要先区分清楚，不然后面容易混：

  • Prompt：一次性指令，聊完就丢。它解决的是「这次怎么说」。
  • Skill：可复用的标准化流程，存成文件，系统能自动识别并加载。它解决的是「这类事以后都按这个规矩做」。
  • Plugin/工具：一段确定性代码，点一下就执行固定逻辑。它解决的是「执行某个动作」。
  • MCP（Model Context Protocol）：让 Agent 连上外部系统的通用接口标准，类似 USB-C。它解决的是「怎么连」。
  • Agent：带角色、记忆、规划和执行循环的智能体。它解决的是「以什么身份、怎么把事做完」。

一句话总结：MCP 负责连工具，Skill 负责把工具用好，Agent 负责决定什么时候用哪个 Skill。

我做前端这么多年，第一次看到 Skill 的文件夹结构时，第一反应是：这不就是我们项目里的 utils/formatDate.ts 加上同目录的 README.md 吗？

回想一下你写工具函数的经历：

  • 你先把「格式化日期」这个需求抽象出来；
  • 你定义好入参、出参、默认值、异常处理；
  • 你写几个测试用例，防止同事改错；
  • 最后你把它 export 出去，谁 import 谁用。

Skill 的逻辑几乎一模一样：

  • name/description = 函数签名 + JSDoc，告诉别人这是什么、什么时候用。
  • instructions = 函数体，告诉 AI 一步一步怎么做。
  • examples = 单元测试，给 AI 看正确输入应该得到什么输出。
  • scripts/ = 你不放心让 AI 写的确定性逻辑，比如正则匹配、数学计算、文件解析。

再打个比方：Agent 是一个刚入职的全栈实习生，能力很强但不知道你团队的规矩。Skill 就是你写给他的一份 SOP + 检查清单。以后每次要做代码 Review，他不需要你再说一遍「先看安全、再看性能、最后看可读性」，只要加载 code-review 这个 Skill，输出就是你们团队风格的 Review 报告。

Skill 还有个很关键的设计叫 Progressive Disclosure（渐进式加载）：

什么是 Skill？-卖坚果的怪叔叔

也就是说，系统启动时只读每个 Skill 的 name 和 description（约 100 token），真正命中触发时才加载正文，额外资源只在需要时才拉取。这相当于前端里的 Code Splitting + Lazy Loading：没必要一次性把所有组件都打包进首页。

Skill 之所以能火起来，是因为它真的解决了几类老痛点。

1. 输出不稳定

同一个需求，昨天让 AI 写周报它给了三段式，今天给了五段式。不是你 prompt 写错了，而是模型每次都在「自由发挥」。Skill 通过固定输出模板和校验点，把发挥空间框死。

2. 重复写 Prompt

你每周都要写「拉取 GitHub 本周提交 → 按模块分类 → 生成周报」，每次都重新描述一遍不现实。把这套流程写进 weekly-report Skill，以后一句话就能跑。

3. 团队经验无法沉淀

老前端知道怎么 Review 代码、怎么写发布 checklist、怎么处理线上故障。这些经验以前存在脑子里或某个 wiki 里，新人看不到。Skill 把这些经验结构化，变成 Agent 能直接调用的资产。

4. 和 MCP 配合形成闭环

MCP 给了 Agent 一堆接口（查 Jira、读数据库、发邮件），Skill 告诉 Agent 什么时候调用哪个接口、参数怎么填、失败怎么办。两者一结合，Agent 才能真正干活而不是乱调用。

最小可行的 Skill 只需要一个文件：

my-skill/
└── SKILL.md

稍微完整一点的结构：

my-skill/
├── SKILL.md          # 核心：触发条件 + 执行流程
├── scripts/          # 辅助脚本（只做执行，不进入上下文）
│   └── validate.py
├── references/       # 参考资料（按需加载）
│   └── api-docs.md
└── assets/           # 模板、图片等静态资源
    └── report-template.md

下面是一个贴近前端场景的示例：一个帮你按团队规范生成组件文档的 Skill。

---
name: component-doc
description: 为 React/Vue 组件生成标准化文档。当用户要求写组件说明、
  文档、Storybook 描述或组件使用示例时触发。
---

# 组件文档生成器

## 规则

1. 先读取组件源码，识别 props、emits/slots、类型定义。
2. 每个 prop 必须包含：名称、类型、是否必填、默认值、用途说明。
3. 给出至少一个完整使用示例，示例中的变量名要与源码一致。
4. 禁止编造源码中不存在的 API。
5. 输出结构固定为：概述 → Props → 事件/插槽 → 示例 → 注意事项。

## 输出格式

```markdown
## {{ComponentName}}

### 概述
...

### Props
| 名称 | 类型 | 必填 | 默认值 | 说明 |
...

### 示例
...
```

## 异常处理

- 读不到源码时，提示用户提供文件路径。
- props 类型无法推断时，标记为 unknown 并说明原因。

真正决定你的 Skill 能不能在正确场景被触发的，是 description 这一小段。它直接决定你的 Skill 会不会在正确的场景被触发。描述里要包含具体动词和场景词，比如「组件文档」「Storybook」「props 说明」，而不是泛泛地说「帮助编程」。

我从写过十几个 Skill 的经验里提炼出 5 步，适合你从 0 开始。

步骤 1：选一个高频、重复、容易出错的任务

不要一上来就想做一个「万能 Skill」。第一个 Skill 最好是你们团队每周都在做、且流程相对固定的事，比如：

  • 代码 Review
  • 组件文档生成
  • 周报/月报
  • 线上故障 Runbook
  • 接口文档补全

步骤 2：新建目录并写出最小 Frontmatter

mkdir -p ~/.claude/skills/code-review
# 或项目内共享
mkdir -p .claude/skills/code-review

然后写 SKILL.md：

---
name: code-review
description: 按团队规范检查代码安全、性能和可维护性。
  当用户要求 review 代码、检查 bug 或审计安全时触发。
---

步骤 3：把流程拆成可执行的步骤

不要写愿景，写动作。每条规则都要回答：

  • 第一步做什么？
  • 第二步做什么？
  • 输出格式是什么？
  • 出错怎么办？

比如代码 Review Skill 可以写成：

  1. 检查 OWASP Top 10 安全风险；
  2. 识别性能瓶颈（循环、请求、重渲染）；
  3. 评估可读性和命名；
  4. 输出「严重/建议/可选」三级结论。

步骤 4：补 2-3 个输入输出示例

示例是 Skill 的灵魂。AI 看示例比看规则学得更快。示例越多，输出越稳定。

步骤 5：安装、测试、迭代

Claude Code 把 Skill 放在 ~/.claude/skills/（个人）或 .claude/skills/（项目）即可自动识别。装好后，用一个真实任务跑一遍，看输出是否偏离预期。偏离了就去改 description、补约束、加示例。

很多前端同学第一次听说 Skill 会以为它是「更复杂的 prompt」。其实不是。

Prompt 解决的是「一句话让 AI 回答」，Skill 解决的是「把一类事的流程固定下来，让 AI 每次都能按你的方式执行」。它更像是你在团队里沉淀的一套 工程规范 + 自动化脚本 + 检查清单。

如果你已经会用 MCP 给 Agent 接工具，别急着换更牛的模型——先把工具用好更划算。而 Skill，就是把工具用好的关键。