第 33 节 · Skills 系统：为什么需要、SKILL.md 标准、加载机制
一句话回答
Skills = 可热插拔的领域知识包。 它把团队规范、操作流程、参考资料和小脚本打包成文件夹，让同一个 Agent 面对不同项目时按需加载正确能力，而不是把所有规则都塞进 system prompt。
为什么 system prompt 不够
想象你在同一家公司接了 3 个项目：
| 项目 | 代码规范 | 测试要求 | 提交格式 |
|---|---|---|---|
| 前端 React | 函数组件 + hooks + 禁止 class | vitest | feat(ui): xxx |
| 后端 Go | 错误必须用 sentinel + wrap | go test -race | fix(api): xxx |
| 数据流水线 | PEP8 + type hint 100% | pytest --cov ≥80% | chore(etl): xxx |
如果把 3 套规范全塞进 system prompt：
- token 炸裂（每次都付 3 倍钱）
- LLM 容易"串台"
- 规则没人敢维护（prompt 变成一坨巨型文档）
Skills 的解法：
- 每套规范 = 一个 skill 文件夹
- 启动时只加载索引（name + description，极小）
- 用户问题匹配到哪个 skill，才加载对应的完整指令
- 更大的参考资料和脚本放在旁边，等真的需要时再读或执行
2026 年的 Skills 标准：渐进式披露
Anthropic 在 2025-2026 年把 Agent Skills 推成了一个很清晰的格式：文件夹 + SKILL.md + 渐进式披露。
add-docstring/
├── SKILL.md # 元数据 + 核心规则
├── reference.md # 更长的参考资料，可选
├── examples.md # 示例，可选
└── scripts/
└── check.py # 可执行脚本，可选| 层级 | 什么时候进入上下文 | 内容 |
|---|---|---|
| Level 1：元数据 | 启动时总是加载 | name + description |
| Level 2：核心指令 | 匹配到 skill 时加载 | SKILL.md body |
| Level 3+：资源 / 脚本 | 需要时再读或执行 | 参考文档、模板、Python / Bash 脚本 |
这叫 progressive disclosure（渐进式披露）：先给目录，再给章节，最后才打开附录。它解决的是 Day4 的上下文问题：让 Agent 知道有这些能力，但不要一上来把所有内容塞进窗口。
SKILL.md 格式标准
markdown
---
name: add-docstring
description: 给 Python 函数添加 Google 风格 docstring；当用户要求加注释、补文档、写 docstring 时使用
---
# 使用规则
当用户要求"加注释""加文档""补 docstring"时，遵循以下规范：
## 格式
- Google 风格 docstring
- 第一行是简短描述（不超 72 字符）
- Args / Returns / Raises 三段
## 示例
```python
def fetch_user(user_id: int, timeout: float = 5.0) -> dict:
"""根据 ID 获取用户信息。
Args:
user_id: 用户唯一标识符。
timeout: HTTP 超时（秒），默认 5.0。
Returns:
用户信息字典，包含 name / email / role。
Raises:
NotFoundError: user_id 不存在时。
"""
```frontmatter 字段
| 字段 | 必填 | 作用 |
|---|---|---|
name | ✅ | Skill 唯一标识（用于匹配 + 加载） |
description | ✅ | 一句话描述（注入 system prompt 索引里，也是触发质量的关键） |
description 不是随便写的广告语，而是匹配提示。写得太泛会误触发，写得太窄又触发不到。
渐进式加载机制
Level 1（启动时）：
扫描 skills/ → 解析 frontmatter → 生成索引
注入到 system prompt：
"可用 Skills: add-docstring(给函数加 docstring) / go-sentinel(Go 错误规范) / ..."
Level 2（运行时）：
用户问 "帮我给这个函数加文档"
→ 匹配到 add-docstring
→ 加载完整 SKILL.md body 注入到 system prompt
→ LLM 按照 body 里的格式规范生成 docstring
Level 3（进阶）：
SKILL.md 里写 "复杂场景请阅读 reference.md"
→ Agent 按需 read reference.md
→ 或运行 scripts/check.py 做确定性校验好处：
- 启动 token 极小（索引只有几十个 token）
- 只付当次真正需要的 skill 的 token 成本
- 新增 skill 不用改代码——放一个文件夹进去就行
- 领域专家也能维护——Markdown 比改 Python 代码容易
Skills、Memory、MCP 到底有什么区别
| 机制 | 解决什么问题 | 例子 |
|---|---|---|
| Skills | 流程和规范怎么做 | "写 commit message 要按这个模板" |
| Memory | 长期事实记什么 | "用户偏好中文提交信息" |
| MCP / Tools | 外部能力怎么调用 | 查 issue、读数据库、跑浏览器 |
一句话：Skills 教 Agent 怎么做，Memory 告诉它以前发生过什么，Tools 让它真的能做。
给 Agent 加 list_skills 和 load_skill 工具
最小实现只要 2 个新工具：
python
@registry.tool("列出所有可用的 Skills 名称和描述")
def list_skills() -> str:
return skills.to_index_prompt()
@registry.tool("加载指定 skill 的完整规范到上下文中")
def load_skill(name: str) -> str:
return skills.load(name)这样 LLM 就可以自己决定什么时候该加载哪个 skill。课程里的简化版也演示了关键词匹配：先用 query 匹配 skill 索引，再加载最相关的 body。
安全提醒：Skill 也是供应链
Skill 很像"给 Agent 装插件"，所以要按供应链看待：
- 只安装可信来源的 skill
- 先读
SKILL.md，再决定是否启用 - 特别审查
scripts/里的脚本和联网行为 - 不要把 API key、token、密码写进 skill
- 对团队共享 skill 做版本管理和 code review
一个恶意 skill 可以诱导 Agent 泄露文件、乱跑命令或连接陌生网络。Skills 提升能力，也扩大攻击面。
动手试试
- 在
my_coding_agent/skills/下建一个add-docstring/SKILL.md - 给 ToolRegistry 添加
list_skills+load_skill两个工具，或复用skills_loader.py的匹配逻辑 - 用 Agent 问"帮我给 bash.py 里的函数加 docstring"
- 观察 Agent 是否自动
load_skill("add-docstring")→ 按规范生成
小结
- Skills = 热插拔的领域规范包，解决"多项目多规范"问题
SKILL.md= YAML frontmatter（元数据）+ Markdown body（完整指令）- 2026 的核心思想是渐进式披露：索引常驻，正文按需，资源和脚本再按需
- Skills 教流程，Memory 存事实，Tools 接外部能力
- Skill 也要审计，不要把不可信脚本直接交给 Agent 跑