📒 学霸笔记：13｜智能涌现的基石：精通 Agent Skills，为 AI 植入专家能力

Top Student Notes: 13 | The Foundation of Intelligent Emergence: Mastering Agent Skills to Implant Expert Capabilities into AI

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 13
主题 / Topic: Agent Skills、Skill 结构、渐进式披露、Skills vs Slash Commands vs Sub-agents、技能发现机制、能力封装、专家知识植入

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

到第 12 讲为止，我们已经学会了很多“给 AI 加能力”的办法：

• Slash Commands：把流程封装成用户主动调用的命令
• Hooks：在 AI 生命周期关键节点自动触发动作
• MCP：把 AI 连接到外部系统
• CLAUDE.md / constitution.md：给 AI 提供长期规则与原则
• Permissions / Sandbox / Checkpointing：给 AI 加安全边界

这让 Claude Code 变得越来越像一个“通用型强力助手”：

• 会读文件
• 会写代码
• 会跑测试
• 会连 GitHub
• 会操作外部系统
• 会遵守规范

但这里出现了一个新的矛盾：

AI 越通用，就越需要一种优雅的方式，把领域专业知识按需装进去。

因为现实中的专业知识非常碎片化且高度垂直：

• 如何审查 Go 代码
• 如何处理公司财务报表
• 如何遵守团队 Figma 设计规范
• 如何分析 Kubernetes 日志
• 如何生成符合本项目风格的 API 脚手架

这些知识不适合：

方案 1：重新训练一个专门模型

太贵，不现实。

方案 2：全塞到 CLAUDE.md

会导致：

• 上下文膨胀
• 难维护
• 混杂多个领域知识
• 模型“认知污染”

于是问题变成：

如何把领域知识做成可组合、可扩展、可移植、按需加载的能力单元？

Anthropic 的答案就是：

Agent Skills

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

Agent Skills 本质上是一种“让 AI 自主发现并按需加载领域专业能力”的知识封装机制，它把一次性指令升级成可复用、可发现、可组合的专家技能。

三、这一讲最重要的认知升级

The Most Important Cognitive Upgrade in This Lecture

Tony 这一讲最核心的升级，不是“多学一个功能”，而是：

从“给 AI 下命令”，升级为“给 AI 建能力库”。

以前你做的是什么？

你更多是在写：

• Prompt
• Slash Command
• Hook 规则

这些都偏向于：

告诉 AI 现在该做什么

Skills 带来的变化是什么？

你开始写的是：

• 一套专业能力说明
• 一套触发场景
• 一套方法论步骤
• 一套按需加载的知识组织方式

这相当于在告诉 AI：

“当你遇到某类问题时，你可以调用这套专业能力。”

这就是从“命令”到“能力”的变化。

四、从“指令”到“技能”

From “Instruction” to “Skill”

这是整讲的理论核心。

Tony 说得非常准确：

• 指令（如 Slash Command）是祈使句
• 技能（Skill）是陈述句

这两个句子形式其实代表完全不同的调用哲学。

指令是什么？

例如：

/review-go-code

它的意思是：

“去做这件事。”

这是一种外部命令式触发。

技能是什么？

例如：

“我是一个能够根据项目规范审查 Go 代码的能力。”

这是一种能力声明。

本质区别

指令

• 用户主动发起
• AI 被动执行
• 更像快捷命令

技能

• 开发者预先定义能力
• AI 自主发现并决定是否使用
• 更像知识插件 / 能力模块

五、为什么说 Skills 是“智能涌现”的关键？

Why Are Skills the Key to “Intelligent Emergence”?

因为 Skills 改变了调用模式。

Slash Commands 的调用模式

用户 → 明确输入命令 → AI 执行

Skills 的调用模式

用户 → 自然语言提需求 → AI 自主扫描技能库 → 匹配最相关技能 → 加载并执行

这意味着什么？

你不再需要为每个任务都精确记住命令名。
AI 会开始：

• 主动判断任务类型
• 主动匹配相关能力
• 主动加载专业知识

也就是说，AI 的“工作方式”从：

等你告诉它怎么做

变成：

自己想起“这个问题我有现成技能可用”

这就是 Tony 所说的“智能涌现”的关键。

六、Skill 的具体形态是什么？

What Does a Skill Look Like Concretely?

Skill 不是抽象概念，而是一个非常明确的文件系统结构。

七、基础结构：一个目录 + 一个 SKILL.md

Basic Structure: A Directory + a SKILL.md

最简单的 Skill 长这样：

my-first-skill/
└── SKILL.md

这里真正的核心是：

SKILL.md

它就是这个 Skill 的“大脑”。

八、SKILL.md 的两部分结构

The Two Parts of SKILL.md

1. YAML Frontmatter

位于最顶部，由 --- 包起来。

它是这个 Skill 的“身份证”。

最关键的字段有：

• name
• description

有时还可以有：

• allowed-tools

2. Markdown Body

后面正文部分。

这里写的是：

• 该技能的职责
• 触发条件
• 执行步骤
• 输出格式
• 示例
• 规则约束

学霸理解

可以这样记：

• Frontmatter = 技能索引卡片
• Body = 技能说明书 / 操作手册

九、进阶结构：Skill 不只是一个文件

Advanced Structure: A Skill Can Be More Than One File

当 Skill 复杂起来时，可以扩展成一个完整知识胶囊：

pdf-processing-skill/
├── SKILL.md
├── forms.md
├── reference.md
└── scripts/
    ├── fill_form.py
    └── ...

这意味着什么？

Skill 不只是“写一点 Prompt”。

它可以包含：

• 主说明书
• 子主题文档
• 深度参考资料
• 可执行脚本
• 模板文件

学霸理解

这就是一种：

知识 + 方法 + 工具 的打包封装

所以 Skill 更像：

• 小型专业知识包
• 可安装能力模块
• AI 领域插件

十、Skill 的部署位置

Where Skills Are Deployed

Skills 有两个主要放置位置。

1. Project Skills

位置：

./.claude/skills/<skill-name>/

特点

• 跟项目走
• 可提交 Git
• 团队共享
• 适合项目特定能力

适合放什么？

• Go 代码审查 Skill
• 本项目部署流程 Skill
• 本项目微服务生成 Skill
• 本项目架构规范 Skill

2. Personal Skills

位置：

~/.claude/skills/<skill-name>/

特点

• 个人专属
• 跨项目可用
• 不进仓库

适合放什么？

• Git diff 摘要 Skill
• 英文润色 Skill
• 私人写作模板 Skill
• 通用分析工具 Skill

学霸理解

这和前面：

• Commands
• Settings
• 规则体系

一样，依然是：

项目级共享 + 用户级个性化

十一、Skills 真正厉害的机制：渐进式披露

The Truly Powerful Mechanism Behind Skills: Progressive Disclosure

这是本讲最核心、最值得深刻理解的技术思想。

Tony 给出的关键词是：

Progressive Disclosure（渐进式披露）

十二、为什么需要“渐进式披露”？

Why Do We Need Progressive Disclosure?

因为领域知识很多，但模型上下文有限。

你不能把所有专业知识：

• 一次性塞进上下文
• 永远挂在 system prompt 里
• 和所有任务一起参与推理

否则会出现：

• Token 爆炸
• 推理效率下降
• 无关知识干扰
• 模型混乱

所以 Skills 的关键设计目标是：

只在需要时，按层次、按深度加载相关知识。

十三、三层加载模型

The Three-Level Loading Model

Tony 用三层结构解释得非常清楚。

Level 1：元数据层（发现层 / 能力索引）

Metadata Layer (Discovery Layer / Capability Index)

Claude Code 启动时，不会完整加载所有 Skill 内容。
它只加载每个 Skill 顶部的 Frontmatter，尤其是：

• name
• description

这些信息会进入系统提示，形成一个“能力索引”。

作用

AI 相当于脑子里记住：

• 我有哪些技能
• 各技能大致做什么
• 什么时候该用

但此时它还没真正去读完整说明书。

学霸理解

这就像图书馆目录卡片。
你先知道“有这本书”，但不会先把整本书背下来。

Level 2：核心指令层（触发层 / 即时加载）

Core Instruction Layer (Trigger Layer / Just-in-Time Loading)

当用户提出任务后，AI 会根据任务语义去匹配这些 description。

一旦匹配成功，才真正读取对应 SKILL.md 的正文。

作用

只有在任务相关时，技能主体才进入上下文。

这就是：

Just-in-Time Loading

学霸理解

不是所有专家知识都随身携带，
而是遇到某类问题时，才把对应专业手册翻开。

Level 3+：辅助资源层（执行层 / 深度按需加载）

Auxiliary Resource Layer (Execution Layer / Deep On-Demand Loading)

如果 SKILL.md 又提到：

• forms.md
• reference.md
• scripts/fill_form.py

那么只有在执行到这些步骤时，AI 才进一步加载这些文件。

作用

这使得一个 Skill 可以很复杂，但不会一开始就爆上下文。

学霸理解

这就是“目录 → 章节 → 工具箱”的层层展开。

十四、渐进式披露真正解决了什么矛盾？

What Fundamental Tension Does Progressive Disclosure Solve?

它解决的是：

海量专业知识 vs 有限上下文窗口

如果没有这套机制

你只能二选一：

1. 全塞进去

信息太多，AI 很乱

2. 完全不塞

AI 又不专业

Skills 的答案

先加载索引，任务来时再加载正文，必要时再加载深层资源。

这就同时获得了：

• 可扩展性
• 高效率
• 强能力
• 低上下文负担

十五、Skills 的四个关键词

Four Keywords for Skills

Tony 总结得很好：

• Composable
• Portable
• Efficient
• Powerful

十六、为什么说它“可移植”？

Why Is It Portable?

因为一个 Skill 本质上就是一个标准化目录。

所以它可以：

• Git 复制
• 项目间迁移
• 团队共享
• 跨环境复用

一句话

Build once, use everywhere.

十七、为什么说它“可组合”？

Why Is It Composable?

因为 AI 可以根据任务，同时命中多个技能的 description，并组合它们。

也就是说，不同 Skill 不是孤岛，而是：

可被模型协调使用的能力单元。

例如

一个复杂任务可能同时涉及：

• Go 代码审查 Skill
• API 契约检查 Skill
• K8s 部署检查 Skill

AI 可以串联这些 Skill 去完成一个更复杂的目标。

十八、核心辨析：Skills vs Slash Commands vs Sub-agents

Core Distinction: Skills vs Slash Commands vs Sub-agents

这是这一讲考试式最容易出的点。

十九、Slash Commands 的定位

The Role of Slash Commands

本质

用户显式触发的固定流程命令

适合

• 高频
• 流程固定
• 你知道自己要什么
• 你希望一键执行

心智模型

快捷操作入口

二十、Skills 的定位

The Role of Skills

本质

AI 可自主发现和调用的领域能力单元

适合

• 某个专业领域
• 你希望 AI 根据语义自动想起它
• 你想植入方法论和知识体系

心智模型

AI 的专家知识插件

二十一、Sub-agents 的定位

The Role of Sub-agents

虽然下一讲才会展开，但这一讲已经先做了定位区分。

本质

拥有独立上下文的“AI 分身 / 专家分工体”

适合

• 复杂独立子任务
• 深度推理
• 不想污染主会话上下文
• 并行处理

心智模型

独立上下文中的 AI 专家分身

二十二、怎么选？

How to Choose?

Tony 给了一个非常实用的判断标准。

当你希望自己快捷触发一个固定流程

用：

Slash Command

当你希望 AI 在某个领域更聪明、更主动

用：

Skill

当你希望 AI 把复杂任务分包给独立分身处理

用：

Sub-agent

口诀

人点按钮用 Command，
AI 自主想起用 Skill，
复杂分工隔离用 Sub-agent。

二十三、实战：把 /review-go-code 升维成 Skill

Practical Example: Elevating /review-go-code into a Skill

这个实战很有代表性，因为它不是从零做，而是“升维改造”。

原来的 Slash Command 是什么？

一个显式指令，例如：

/review-go-code

本质是：

你得记住它，主动调用它。

现在做成 Skill 后会怎样？

你只要自然说：

帮我看看 internal/converter/ 目录下的 Go 代码是否符合我们的项目规范

AI 就会：

• 识别“这是 Go 代码审查任务”
• 匹配 go-code-reviewer Skill
• 主动加载该 Skill
• 按 Skill 流程执行

二十四、这个 Skill 的结构值得怎么学？

What Should We Learn from the Structure of This Skill?

Tony 给出的 go-code-reviewer Skill 里有几个特别重要的点。

1. name

唯一标识技能

2. description

这是最关键字段之一。
它告诉 AI：

• 这个 Skill 做什么
• 什么时候应该使用它

例如：

• review Go code
• check best practices
• analyze code quality

这些关键词实际上是在帮 AI 建立匹配索引。

3. allowed-tools

限制此 Skill 可以用哪些工具

这是很好的治理措施。

4. 主体中的“触发条件”

手动补充语义线索，例如：

• “审查 Go 代码”
• “看看写得怎么样”
• “是否符合规范”

这进一步增强触发精度。

5. 主体中的“执行步骤”

让 Skill 不只是“知道做什么”，而是“知道怎么做”。

例如：

1. 先读 constitution.md
2. 再定位目标代码
3. 再逐条审查
4. 最后输出结构化报告

6. 主体中的“输出格式”

强制 AI 结果更稳定。

这对于 Skill 特别重要，因为：

Skill 是 AI 自主调用的，所以你必须把流程和结果模板写得更清楚。

二十五、这次“升维”到底升了什么？

What Exactly Was Elevated in This “Upgrade”?

Tony 提到得非常好，可以总结成三点。

1. 从“被动执行”到“主动思考”

Slash Command 是：

• 用户发命令
• AI 执行

Skill 是：

• AI 先判断
• 再决定是否调用能力

2. description 成了能力发现入口

这就像：

Skill 的 API 文档 / 搜索索引 / 广告语

3. 流程控制更严格

因为 AI 自主调用能力时，必须给它更强的工作流约束，否则会漂。

二十六、如何验证 Skill 是否生效？

How to Verify That a Skill Works?

Tony 提供了两个很关键的验证方式。

1. 用 --debug 启动 Claude Code

可以在日志里看到 Skill 是否被加载，例如：

[DEBUG] Skills and commands included in Skill tool: Go Code Reviewer

2. 用自然语言而不是 Slash Command 测试

如果你不输入 /review-go-code，而只自然表达需求，AI 还能触发该 Skill，就说明它真的完成了“自主发现”。

二十七、官方 PDF Skill 示例的高级意义

The Advanced Significance of the Official PDF Skill Example

Tony 最后专门分析官方 PDF Skill，是为了说明：

真正强大的 Skill 往往不是单文件，而是一个层次化知识系统。

这个例子体现了什么？

SKILL.md

像目录 / 总纲 / 路由器

forms.md

像具体章节，专讲一种子任务

reference.md

像深度参考资料

scripts/*.py

像可调用工具箱

这是一种什么设计方式？

像写一本结构清晰的专业书。

• SKILL.md 是目录
• 辅助文档是章节
• 脚本是工具附录

这就是高级 Skill 设计范式。

二十八、Skills 的四大最佳实践

Four Best Practices for Skills

Tony 这一讲最后给出了非常重要的方法论。

二十九、最佳实践一：保持单一职责

Best Practice 1: Keep Skills Single-Responsibility

一个 Skill 应该像好函数一样，只做一件事。

反模式

一个 document-processing Skill 包含：

• PDF
• Word
• Markdown
• OCR
• 表格生成

这样会导致：

• description 模糊
• 触发不精准
• 上下文污染
• 维护困难

最佳实践

拆成多个 Skill：

• pdf-form-filling
• word-doc-analysis
• markdown-table-generator

原因

• 提升发现准确率
• 节省上下文
• 提高可组合性

三十、最佳实践二：精心撰写 description

Best Practice 2: Write the description Carefully

Tony 说得很对：

description 是 AI 发现技能的唯一入口。

一个好的 description 要回答两个问题：

1. 这个技能能做什么？
2. 什么时候该用它？

反模式

description: For files

完全没有发现价值。

最佳实践

明确写出：

• 能力
• 关键词
• 触发场景
• 文件类型 / 任务类型 / 领域术语

学霸理解

description 其实就是：

给 AI 写的技能广告语 + 检索标签 + 触发说明

三十一、最佳实践三：和团队一起测试与演进

Best Practice 3: Test and Evolve Skills with the Team

Skill 不是写完就完了，它需要在真实任务里反复调优。

团队要反馈什么？

• 为什么这次没触发？
• 为什么触发错了？
• 输出哪里不稳定？
• 哪些关键词需要补充？
• 哪些步骤不够明确？

学霸理解

Skill 和 Prompt 一样，也需要：

持续迭代、回测、调优

三十二、最佳实践四：做版本化维护

Best Practice 4: Maintain Version History

尤其是团队共享 Skill，非常需要版本历史。

例如：

## Version History
- v2.0: Added support for ...
- v1.0: Initial release ...

为什么有价值？

因为 Skill 本质上已经是：

• 团队方法论资产
• AI 工作流基础设施
• 可复用能力单元

它值得像代码一样被管理。

三十三、这一讲的真正方法论价值

The Real Methodological Value of This Lecture

13 讲真正厉害的地方，是把 AI 使用方式又推进了一层。

前面你做的是：

• 调 AI
• 管 AI
• 限 AI
• 扩 AI

这一讲开始做的是：

教 AI 在什么场景下该成为哪类专家。

这意味着什么？

你不再是在写一堆 Prompt，而是在做：

• 能力工程
• 知识模块化
• 场景驱动能力注入
• 专家方法论封装

所以这一讲的本质是

从工具使用工程，走向 AI 能力设计工程。

三十四、这一讲和前面课程怎么串起来？

How Does This Lecture Connect to the Earlier Ones?

可以这样看整条主线：

01-08

让 AI 进入工程系统并形成规则化工作流

09-10

让 AI 安全可控、可反悔

11

让 AI 在关键节点自动触发动作

12

让 AI 连到外部世界

13

让 AI 不只是会调用工具，而是会按领域能力思考

一句话

前面更多在给 AI：

• 眼睛
• 手脚
• 规则
• 外部接口

这一讲开始给 AI：

专业脑回路

三十五、本讲知识结构图

Knowledge Structure of This Lecture

AI 已经很通用
        ↓
但缺少领域专业化能力封装方式
        ↓
不能靠重训模型
也不能全塞进 CLAUDE.md
        ↓
需要可组合、可移植、按需加载的能力单元
        ↓
Agent Skills
        ↓
从“指令”到“技能”
├── Slash Commands：用户调用
└── Skills：模型调用
        ↓
Skill 的形态
├── 一个目录
├── SKILL.md
│   ├── YAML Frontmatter
│   └── Markdown Body
└── 可扩展辅助文档和脚本
        ↓
核心机制：渐进式披露
├── Level 1 元数据索引
├── Level 2 SKILL.md 主体即时加载
└── Level 3+ 深层资源按需加载
        ↓
核心对比
├── Slash Commands：固定流程入口
├── Skills：领域能力插件
└── Sub-agents：独立上下文分身
        ↓
实战
└── /review-go-code 升维为 go-code-reviewer Skill
        ↓
最佳实践
├── 单一职责
├── 精写 description
├── 团队测试迭代
└── 版本化维护

三十六、学霸速记表

Quick Revision Table

三十七、学霸自检题

Self-Check Questions

基础题

1. 为什么不能把所有领域知识都塞进 CLAUDE.md？
2. Skill 的最小文件结构是什么？
3. description 字段为什么如此关键？

进阶题

4. 什么是“渐进式披露”？它解决了什么问题？
5. 为什么说 Skill 是“模型调用”，而不是“用户调用”？
6. 为什么 Skill 应该尽量保持单一职责？

思辨题

7. 在你的项目里，哪些高价值流程适合从 Slash Command 升维成 Skill？
8. 如果你为一个 Go 微服务项目设计 3 个 Skills，你会如何拆分职责？
9. 你会怎样写一个能高精度触发的 description？

三十八、学霸总结

Top-Student Summary

这一讲讲的是 Claude Code 中一个非常关键的能力扩展机制：Agent Skills。
它解决的核心矛盾是：

如何在不牺牲 AI 通用性的前提下，为其高效、优雅地植入领域专业能力。

前面课程中，我们通过 Slash Commands、Hooks 和 MCP，为 AI 提供了大量可调用的流程、事件自动化和外部能力接口；但这些能力大多仍停留在“工具层”或“命令层”。AI 虽然更强了，却还缺少一种可以自主发现、按需加载的“专家知识封装方式”。

Agent Skills 正是这个问题的答案。
它不是一次性的 Prompt，也不是用户必须记住并主动输入的命令，而是一种：

• 可发现
• 可复用
• 可组合
• 可移植
• 可按需加载

的能力模块。

它最根本的认知升级在于：
从“指令”转向“技能”。

• Slash Commands 是祈使句：用户明确命令 AI 去做什么
• Skills 是陈述句：开发者向 AI 声明“这里有一项能力，在这些场景下你可以使用”

这就使得调用模式发生了根本变化：
不再是用户手动选择命令，而是 AI 根据自然语言任务，自主扫描技能库，通过 description 匹配最合适的 Skill，并加载执行。

Skill 的物理形态非常清晰：

• 一个目录
• 一个核心 SKILL.md
• 可选的辅助文档与脚本

而其真正强大的地方，在于“渐进式披露（Progressive Disclosure）”机制：

1. 启动时只加载 metadata，形成轻量能力索引
2. 命中场景时才加载 SKILL.md 主体
3. 执行中才进一步按需读取辅助文档和脚本

这套机制优雅地解决了“海量专业知识”与“有限上下文窗口”之间的根本矛盾。

在工程定位上，Skills 与其他扩展能力的区别也非常清楚：

• Slash Commands：用户主动触发的固定流程入口
• Skills：AI 自主发现和调用的领域能力插件
• Sub-agents：拥有独立上下文、可并行工作的专家分身

通过把 /review-go-code 升维为 go-code-reviewer Skill 的实战，Tony 展示了这种变化的真正价值：
用户不再需要记住命令名，而可以用自然语言描述目标，AI 则会像一个真正“知道自己会什么”的系统一样，自主选择并执行最合适的专业能力。

最后，Tony 还总结了设计 Skills 的关键最佳实践：

• 保持单一职责
• 精心撰写 description
• 在团队中持续测试和迭代
• 进行版本化管理

因此，这一讲最核心的思想不是“又多了一个配置文件”，而是：

我们开始不再只是给 AI 下指令，而是在为它建设一座可成长、可检索、可组合的专家能力库。

这标志着开发者角色再次升级：
你从 Prompt 的编写者，进一步成为了：

AI 专家能力系统的设计者。

三十九、一句话记忆

One-Sentence Memory Hook

Agent Skills 的本质，是把领域知识做成 AI 可自主发现、按需加载、可组合复用的能力胶囊，让 AI 从“听话执行”升级为“知道何时该像专家一样工作”。