Agent Skills 概览与实践
Agent Skills（技能） 是一种开放格式，把 领域知识、工作流、脚本 打包成可版本管理的目录，供 AI Agent 按需加载。核心是 SKILL.md（YAML 元数据 + Markdown 指令），规范见 agentskills.io。本篇建立最小心智模型：它和 MCP、Rules、Prompt 各管什么层。工具接入见 MCP 概览与实践；Agent 循环见 Agent 核心概念与架构；加载全文如何占用上下文预算见 上下文工程。
Skills 解决什么问题
| 痛点 | 没有 Skills | 有 Skills |
|---|---|---|
| 团队规范 | 每次对话重复讲一遍 | 写一次，多会话复用 |
| 跨编辑器 | Cursor / Claude Code / Copilot 各一套规则 | 同一 SKILL.md 多宿主可读 |
| 上下文膨胀 | 全量 system prompt 塞满 | 渐进披露：先摘要，命中再加载全文 |
| 可维护性 | Prompt 散落在聊天里 | Git 管理、Code Review、版本迭代 |
一句话：Skills 是「教 Agent 怎么做事」的可移植说明书，不是可调用的 API。
目录结构
skill-name/
├── SKILL.md # 必需：元数据 + 主指令
├── references/ # 可选：详细参考，按需读取
├── scripts/ # 可选：可执行脚本（Python / Bash / …）
└── assets/ # 可选：模板、图片、数据文件
Pi 等 coding harness 也按需加载 Skills（见 [Pi Agent Harness 实践](/docs/ai/Agent/Pi Agent Harness 实践)）。常见放置路径（因宿主而异，格式相同）：
| 范围 | 典型路径 | 说明 |
|---|---|---|
| 个人 | ~/.cursor/skills/、~/.claude/skills/ | 跨项目通用 |
| 项目 | .cursor/skills/、.agents/skills/ | 跟仓库共享，团队对齐 |
| 跨客户端标准 | .agents/skills/ | 多编辑器约定的通用路径 |
name 字段须与 父目录名 一致（小写、数字、连字符）。
SKILL.md 最小形态
---
name: expense-report
description: 按公司政策填报与校验报销单。用户提到报销、差旅费、报销额度时使用。
---
# 报销填报
## 步骤
1. 确认费用类型与对应上限（见 references/policy.md）
2. 校验发票日期与金额
3. 生成标准格式摘要
## 输出格式
- 表格：日期 | 类型 | 金额 | 是否合规
元数据字段
| 字段 | 必填 | 作用 |
|---|---|---|
name | 是 | 唯一标识，≤64 字符，小写+数字+连字符 |
description | 是 | 发现与触发：写什么、何时用；≤1024 字符 |
license | 否 | 许可证 |
compatibility | 否 | 环境要求（产品、系统包、网络等） |
metadata | 否 | 自定义键值（版本、作者等） |
allowed-tools | 否 | 预批准工具列表（实验性） |
description 要写清 WHAT + WHEN，并含触发关键词——多数宿主靠它做自动匹配，而不是文件 glob。
渐进披露（Progressive Disclosure）
启动时：所有 Skill 的 name + description（约每条 ~100 tokens）
↓ 任务命中某 Skill 域
加载：完整 SKILL.md 正文（建议 < 5000 tokens）
↓ 需要细节时
按需：references/、scripts/、assets/ 中的文件
设计原则：
- SKILL.md 保持精简（建议 < 500 行），详文放
references/ - 引用 一层深度 即可，避免嵌套过深导致只读片段
- 默认假设 Agent 已很聪明，只写它 不知道 的团队/业务知识
vs MCP / Rules / Prompt
| Agent Skills | MCP | Rules（如 .cursor/rules） | 一次性 Prompt | |
|---|---|---|---|---|
| 本质 | 工作流与领域知识 | 工具与数据接入协议 | 宿主级行为约束 | 当轮指令 |
| 载体 | SKILL.md 目录 | JSON-RPC Server | .mdc / 规则文件 | 用户消息 |
| 可移植 | 跨多编辑器（开放格式） | 跨多 Host | 常绑定单一宿主 | 不持久 |
| 触发 | description 语义匹配 | Host 连接 Server | alwaysApply / globs 等 | 用户当场说 |
| 典型内容 | 「怎么审 PR」「怎么写 commit」 | run_sql、read_file | 「用中文回复」「别改无关文件」 | 「帮我把这个函数改了」 |
记忆口诀：Rules 管脾气，Skills 管手艺，MCP 管伸手拿什么工具。
vs A2A
| Skills | A2A | |
|---|---|---|
| 层级 | 单 Agent 内部能力包 | Agent 与 Agent 协作协议 |
| 交换什么 | 指令与参考文档 | Task、Message、Agent Card |
| 关系 | 互补 | 远程 Agent 也可内置 Skills |
写好 description 的要点
- 第三人称（会注入系统提示）：✅「处理 Excel 并生成报表」；❌「我可以帮你处理 Excel」
- 具体 + 触发词：✅「…Use when user mentions PDF, forms, or document extraction」
- 域要窄：一个 Skill 一件事；「万能开发助手」很难被正确触发
自由度与写法
| 自由度 | 何时用 | 例子 |
|---|---|---|
| 高（原则性文字） | 多种解法都可 | 代码审查清单 |
| 中（伪代码 / 模板） | 有偏好但可变通 | 提交信息模板 |
| 低（固定脚本） | 易错、需确定性 | scripts/validate.sh |
易碎流程用 脚本 + 明确步骤；开放任务用 检查清单 + 示例。
何时用 / 不用
| 信号 | 建议 |
|---|---|
| 团队重复讲解同一流程（发布、CR、合规填表） | 写成 Skill |
| 需要跨 Cursor / Claude Code / Copilot 共享 | 用标准 SKILL.md |
| 只是调外部 API、读数据库 | MCP Server，不是 Skill |
| 全局「别删测试」类约束 | Rules |
| 一次性任务 | 直接 Prompt，不必建 Skill |
| Skill 超过 500 行仍塞在 SKILL.md | 拆 references/，保持主文件可扫描 |
与 MCP 组合
常见分工：
Skill：规定「发布前要跑哪些检查、输出什么格式」
MCP：提供 git、CI、Issue 跟踪等实际工具调用
Agent：读 Skill → 按步骤规划 → 通过 MCP 执行
Skill 可声明 allowed-tools（实验性）缩小工具面，降低误调用风险。
常见误解
- 「Skill = MCP Tool」——Skill 是 说明书，不替代可执行工具协议
- 「description 随便写」——触发全靠 description，含糊等于永远唤不醒
- 「把所有知识塞进一个 Skill」——应拆分域，利于发现与 token 控制
- 「Skills 取代 RAG」——私有知识库检索仍走 RAG；Skill 适合 流程与规范
- 「和 Rules 二选一」——可并存：Rules 管全局约束，Skills 管专项工作流
面试速记
- Agent Skills 是什么？ 开放格式，用
SKILL.md打包领域工作流；渐进披露，按需加载。 - 必填字段？
name（与目录同名）、description（含何时触发）。 - 和 MCP 区别？ Skills 教 怎么做；MCP 连 工具与数据。
- 和 Rules 区别？ Rules 偏宿主全局行为；Skills 偏可移植的任务手册，靠 description 触发。
- 怎么写得好？ 一事一 Skill、description 含关键词、正文精简、详文外置、易碎步骤脚本化。