1. 什么是 Agent Skills
这是什么：Agent Skills（智能体技能） = 一个装着 SKILL.md 的文件夹，用 Markdown 写清「某类任务该怎么做」，让 Agent 在需要时自己读进去照着做。
为什么用：同一套流程你天天重复交代，Agent 每次都得从头摸索；写进系统提示词吧，又会一直占着上下文、还挤掉了别的重点。技能把知识按需加载：平时只挂个名字，碰上了再展开。
如何用：本章先搞清楚技能到底是什么、跟 Prompt / 工具 / MCP 怎么分工，再看它凭什么能跨工具复用，最后埋一个「技能加载」的心智模型。
1.1 技能是什么：一个文件夹 + 一份说明书
技能的全部内容就是一个文件夹：
weekly-report/
└── SKILL.md # 必需：元数据 + 说明书SKILL.md 由两部分组成：YAML frontmatter（元数据）+ Markdown 正文（说明书）。最小可用的技能长这样：
---
name: weekly-report
description: 汇总本周 Git 提交与 Issue，生成周报。用户提到「周报」「本周总结」时使用。
---
生成周报的步骤：
1. 进入仓库目录，跑 `git log --since="7 days ago" --oneline`
2. 统计本周关闭的 Issue 数量
3. 按「做了什么 / 有什么风险 / 下周计划」三段输出
4. 写到 `reports/YYYY-WW.md`
就这么多。没有 npm install，没有构建，没有配置文件——技能不是程序，是给模型看的说明书。
1.2 它解决的不是「模型不够聪明」
这一点最容易被误解。技能不会让模型变得更聪明，它解决的是另外三件事：
| 痛点 | 技能怎么解决 |
|---|---|
| 流程只存在于人脑和聊天记录里 | 写成 Markdown 文件，团队共享、可版本控制、可 review |
| 每次都要重复交代同样的步骤 | 描述写对之后，Agent 自己会认出来并去读 |
| 全塞进系统提示词，上下文越滚越胖 | 只有被命中的技能才展开，没用到的一个字都不占 |
打个比方：系统提示词像是贴在墙上的规章，技能像是收在抽屉里的手册。规章天天看得见（也天天占地方），手册只在需要时抽出来。
1.3 技能 vs Prompt vs 工具 vs MCP
这四样经常被混着说，其实分工很清楚：
| 方案 | 形态 | 谁执行 | 什么时候进上下文 |
|---|---|---|---|
| 系统提示词 | 一段文本 | 模型自己读 | 每轮都在，最贵 |
| 技能 Skill | 一个文件夹 | 模型自己读 | 命中才读，按需 |
| 工具 Tool | 一个函数 | 模型调用它 | 调用时才进 |
| MCP | 一套协议 + 服务 | 模型调用远端工具 | 调用时才进 |
一句话区分：
- Prompt 回答「你现在是谁、要干什么」
- 技能 回答「这类活儿具体怎么做」
- 工具 回答「你能动手做些什么」
- MCP 回答「你能连上外面的哪些服务」
技能和工具最容易混。区别在于：工具是能力（能读文件、能跑命令），技能是用法（这个仓库发版要走哪几步）。技能里完全可以写「先跑 npm test，通过了才 npm run deploy」——它自己不执行任何东西，只是把该调的工具按顺序告诉 Agent。
1.4 渐进式披露：技能为什么省上下文
这是技能机制最核心的设计。Agent 分三层拿技能的内容：
| 层级 | 加载什么 | 大概多少 | 什么时候加载 |
|---|---|---|---|
| L1 元数据 | name + description |
约 100 token / 个 | 启动时全部加载 |
| L2 说明书 | SKILL.md 正文全文 |
建议 < 5000 token | 技能被激活时 |
| L3 资源 | scripts/、references/、assets/ 里的文件 |
按需 | 正文里引用到时 |
第一层最关键：启动时，Agent 看到的是一长串技能的名字和简介，像一份目录。它靠这份目录判断「这个任务要不要翻哪本手册」。
这也解释了为什么 description 写得臭会要命——它是 Agent 唯一的检索依据。下一章会专门讲怎么写。
1.5 为什么能跨工具复用
因为规范本身是开放的、厂商中立的。Agent Skills 规范只规定了 SKILL.md 的格式和目录约定，不规定谁来实现。各家 Agent 工具选择兼容这套规范，所以同一份技能文件夹换个地方照样能用：
| 工具 | 技能目录（在项目根下） |
|---|---|
| Claude Code | .claude/skills/<name>/SKILL.md |
| opencode | .opencode/skills/<name>/SKILL.md（也认 .claude/skills/、.agents/skills/） |
| Hermes | ~/.hermes/skills/<name>/SKILL.md |
| OpenClaw | <workspace>/skills/<name>/SKILL.md |
2025 年 12 月 Anthropic 发布了这份开放规范，之后 Claude Code、opencode、OpenClaw 这类工具陆续接入。技能不是某个产品的特性，是一份正在形成共识的「经验封装格式」——就像 package.json 之于 JS 生态。
🤝 记忆口诀：技能 = 目录 + 说明书，按需加载，跨工具复用。
动手改
- 找出你每次都要跟 Agent 重复交代的三句话（比如「先跑测试再提交」「数据库改动要同步迁移文件」「周报按三段写」），把它们写进一个叫
my-first-skill的SKILL.md草稿 - 用
grep -r "目录"之类的关键词在你常用的 AI 工具配置目录里翻一翻，看看它认哪些技能目录（Claude Code 认~/.claude/skills/，opencode 认~/.config/opencode/skills/） - 拿第 1 章那个
weekly-report技能当模板，给它写一句更精确的description，对比改之前和改之后，Agent 更容易选中哪个
小结
- 技能 = 一个装着
SKILL.md的文件夹，SKILL.md= YAML frontmatter + Markdown 正文 - 它解决的是「流程没沉淀」和「上下文太贵」，不是「模型不够聪明」
- Prompt 管身份和目标，技能管具体做法，工具管能力，MCP 管外部服务
- 渐进式披露三层：元数据常驻（≈100 token）、说明书命中才读、资源按需拉取
- 规范开放中立，所以一份技能能跨 Claude Code / opencode / Hermes / OpenClaw 复用
下一章：SKILL.md 的结构，把规范里那几个字段一个个拆开看 🐸