第 7 章 · M7 Skills 渐进式披露的可复用技能
第 7 章 · M7 Skills 渐进式披露的可复用技能
- 7.1 M7 功能说明:按需调用可复用技能
- 7.2 M7 总体架构:包结构与组件协作
- 7.3 技能的磁盘布局与 SKILL.md 格式
- 7.4 SkillLoader:扫描、解析、去重
- 7.5 SkillStage:把技能清单注入上下文
- 7.6 技能正文按需加载 + skills命令 + 配置
7.1 M7 功能说明:按需调用可复用技能
本篇涉及到的源码列表:
com.minicc.skill.Skill.java
com.minicc.skill.SkillLoader.java
com.minicc.skill.SkillPromptText.java
com.minicc.context.SkillStage.java
com.minicc.cli.command.SkillsCommand.java
M6 我们已经做完了,现在这个 Agent 已经能够读取代码、修改代码、做权限确认、持久化会话、跨会话记忆,还能在上下文快满时自动压缩。
但它目前的专业知识只有一份固定的系统提示词,还没有可复用、可按任务选用的能力。
从这一章开始,我们进入第七个里程碑 M7,为 Agent 增加一套可复用的能力,也就是 Skills。
我们先说清楚 Skills 要解决什么
我们在实际使用 Agent 的时候,会有一类需求反复出现。
比如"怎么生成一条规范的 git 提交信息""发布之前要跑哪几步检查""怎么把一次调研沉淀成一份可复用的流程"。
这些能力有一个共同点:它们可以复用,但又不必每一次都加载进上下文。
你今天要提交代码,才用得上"怎么写提交信息";你今天只是修改样式,这条知识就完全用不上。
全部写进系统提示词为什么不行
我们最直接的想法,是把这些专业能力全部写进系统提示词。
这个做法马上就会出问题。
系统提示词是每一轮都要带上的。你把十几项专业能力都写进去,就等于每一轮都要为用不上的内容占用上下文。
更糟的是,绝大多数任务只会命中其中一两项,剩下的全是无谓的占用。
Skills 的做法:清单常驻、正文按需
我们在 M7 换一个思路。我们把每一项可复用能力写成一个独立的文件,叫做技能文件 SKILL.md。
每个技能文件分两部分:一段文件头(名字、描述、何时用)和一段正文(详细步骤)。
会话开始时,我们只把所有技能的清单加载进上下文,也就是每个技能一行的文件头摘要。
模型判断某个技能和当前任务相关时,才用 Read 工具把那个 SKILL.md 的完整正文读进来,再按照正文执行。
这样一来,清单很小、常驻上下文,正文只在用到时才读取。我们新增一项能力,只需要往技能目录里放入一个 SKILL.md,不需要修改任何一行代码。
这和 M5 是同一种做法
如果你还记得第五章 MEMORY.md,你会发现这个思路和第五章是同一类做法。
M5 的记忆系统就是"MEMORY.md 索引常驻 + 主题文件按需 Read"。M7 基本上是把那套机制再实现一遍。
它们都叫做渐进式披露:入口常驻在上下文里,内容在需要时再读取。
区别只在于来源不同:记忆是模型自己写、跨会话积累的笔记;技能是人预先准备、可复用的操作手册。
命令行里是什么样的
我们用两个场景,把 M7 的功能展示一下。
场景一:技能被命中,先读正文再执行
假设我们在 ~/.mcc/skills/commit-helper/ 下放入了一个生成提交信息的技能。
你让它帮你提交改动。
> 帮我把刚才的改动提交一下
⏺ 我先读一下 commit-helper 技能,按它的规范来提交
⏺ Read(file_path=/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md)
⎿ (SKILL.md 正文:先看 git diff --staged、按 Conventional Commits 写 message……)
⏺ Bash(command="git diff --staged")
⎿ (已暂存的改动)…
⏺ Bash(command="git commit -m \"feat(order): 新增订单取消接口\"")
⎿ [main a1b2c3d] feat(order): 新增订单取消接口注意这里的关键一步:模型没有凭清单里的简短描述就直接编写提交信息,而是先 Read 了那个 SKILL.md,再严格按照正文里的步骤执行。
场景二:没有技能命中,正常处理
你问它一个和任何技能都不相关的问题。
> codecrush 这个项目用的是什么构建工具?
⏺ Read(file_path=/Users/wangzheng/codecrush/build.gradle)
⎿ plugins { id 'java' } …
⏺ 这个项目用的是 Gradle。这一轮它没有去 Read 任何 SKILL.md。没有技能命中时,它就按照平常的方式正常处理,不会勉强套用技能。
/skills:查看当前有哪些技能
我们还给用户增加了一个查看命令 /skills。它和 /tools 是同一类命令,只负责展示。
> /skills
可用技能(2 个):
commit-helper:规范化生成 git 提交信息(当用户要创建 git 提交时)
/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md
release-checklist:发布前检查清单(当用户准备发布、打 tag 时)
/Users/wangzheng/codecrush/.mcc/skills/release-checklist/SKILL.md它把当前会话能够使用的技能都列出来,包括名字、描述、何时使用,以及每个 SKILL.md 的文件路径。
M7 这一版交付什么
我们这一版只做一件事:为 Agent 增加 Skills。
- 我们把可复用能力写成约定格式的
SKILL.md,放在全局或项目级的技能目录里。 - 会话开始时,由一个新的 Stage(
SkillStage)只把技能清单注入上下文。 - 模型命中某个技能时,用既有的 Read 工具把正文读进来,再按照正文执行。
- 我们再增加一个
/skills命令,方便用户随时查看。
本章的学习路线
接下来的几节,我们把这套能力逐节细化成代码。
- 7.2 我们先讲一下总体架构:M7 复用了 M1–M6 的哪些结构、新增了哪个包、一次"带技能的会话"是怎么进行的。
- 7.3 我们来讲一下技能的磁盘布局,以及
SKILL.md的格式。 - 7.4 我们来讲一下
SkillLoader:它怎么扫描目录、解析文件头、按名字去重。 - 7.5 我们来讲一下
SkillStage:它怎么把技能清单注入上下文。 - 7.6 我们来讲一下技能正文的按需加载为什么能直接复用 Read,并在最后讲一下
/skills命令和配置。
读完这一章,你给这个 Agent 新增一项专业能力,只需要往技能目录里放入一个 SKILL.md。
7.2 M7 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.skill.Skill.java
com.minicc.skill.SkillLoader.java
com.minicc.skill.SkillPromptText.java
com.minicc.context.SkillStage.java
com.minicc.cli.command.SkillsCommand.java
com.minicc.MccApplication.java
上一节我们把 M7 要做什么、在命令行里是什么样,都讲清楚了。
这一节我们来看一下它的整体结构:它复用了 M1–M6 的哪些结构、新增了哪个包、一次"带技能的会话"是怎么在各个组件之间流动的。
你先掌握这张结构图。后面几节我们逐个讲每个组件时,你就知道它在整体里处在什么位置。
M7 几乎是纯新增
M7 继续延续"后续里程碑只新增、少修改既有代码"的原则。
和 M5 一样,它是一个"几乎纯新增"的里程碑。
核心新增的是三部分:一个新的 skill 包、一个新的 Stage、一段给模型的提示文本。技能正文的加载,我们直接借用既有的 Read 工具。
这又一次是前面几个里程碑提前留好扩展点的回报。我们把 M7 的几条主线分别接到这些扩展点上。
- 技能清单的"注入点":M1 的上下文组装器
ContextAssembler内部是一条有序、可插入 Stage 的管线,我们新增一个SkillStage,每轮把技能清单注入上下文。 - 技能正文的"加载方式":我们不新增任何工具,直接使用 M1 的 Read。清单里给出每个
SKILL.md的绝对路径,模型用 Read 读取那个路径,就能把正文取回来。 - 技能目录的"层叠约定":沿用"全局 + 项目级"两层,和
mcc.yml、记忆目录是同一套路。
包结构的增量
M7 是建在 M6 之上的,所以我们重点看一下它相对 M6 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ skill/ // 新:整个包(Skills 这一件事)
│ │ ├─ Skill.java // 新:一个已加载技能的元数据(name/description/whenToUse/路径)
│ │ ├─ SkillLoader.java // 新:扫描技能目录、解析 SKILL.md 文件头、去重
│ │ └─ SkillPromptText.java // 新:Skills 行为说明 + 把技能列表渲染成带预算的清单
│ ├─ context/
│ │ └─ SkillStage.java // 新:Stage,每轮注入"行为说明 + 技能清单"
│ ├─ cli/command/
│ │ └─ SkillsCommand.java // 新:/skills 列出当前可用技能
│ ├─ config/
│ │ ├─ MccConfig.java // 改:加 skills 子配置(开关、清单预算)
│ │ └─ ConfigLoader.java // 改:读取 skills 子配置(缺省回落默认)
│ ├─ resources/default-mcc.yml // 改:带注释写上 skills 默认配置
│ └─ MccApplication.java // 改:装配 SkillLoader、SkillStage、/skills 命令skill 包里的几个角色
这个新包里只有三个类,各负责一件事。
Skill:一个已加载技能的元数据。它只持有进清单需要的几个字段,加上SKILL.md的路径。正文不在它这里(见 7.4)。SkillLoader:技能加载器。会话开始时,它扫描两层技能目录,解析每个SKILL.md的文件头,返回一个技能列表(见 7.4)。SkillPromptText:提示文本。它提供给模型的"Skills 行为说明",以及把技能列表渲染成带预算截断的清单的逻辑(见 7.5)。
另外还有一个 Stage:SkillStage,放在 context 包里,和 M5 的 MemoryStage、M6 的 CompactionStage 是同类(见 7.5)。
既有代码的几处修改
除了新包,M7 在既有代码上只有几处小改动,而且位置都是前几个里程碑早已预告的扩展点。
MccApplication:构造SkillLoader、扫描得到技能列表,再把SkillStage插进上下文组装器的管线,并注册/skills命令。MccConfig和ConfigLoader:新增一组可选的skills配置(开关、清单预算),都有默认值。default-mcc.yml:带注释写上skills的默认配置。
可以看到,控制循环、工具接口与既有工具、审批钩子、持久化、记忆、压缩,全都不需要修改。
Skills 做的事情,就是往上下文组装器的管线里增加一个 Stage、读取一批磁盘文件,再借用 Read 取得正文。
上下文组装器的管线里 SkillStage 放在哪
我们看一下这条管线的装配。
// 源码位置:com.minicc.MccApplication.java
ContextAssembler assembler = new ContextAssembler(List.of(
new SystemPromptStage(SystemPrompt.TEXT),
memoryStage, // M5:AGENT.md + 记忆说明 + MEMORY.md 索引
skillStage, // M7:Skills 行为说明 + 技能清单
new PlanModeStage(), // M8:计划态提示(本章先不管)
new CompactionStage(compactionManager) // M6:接管会话历史这一段
));SkillStage 插在 MemoryStage 之后、压缩历史之前。
我们为什么把它放在这个位置?理由和 MemoryStage 完全一样。技能清单是"稳定的靠前内容",每一轮基本不变、位置固定,这样有利于前缀缓存。
我们把它放在历史之前,模型读取历史、做决策的时候,就已经知道当前有哪些技能可用。
一次"带技能的会话"的全过程
我们按顺序说明一次完整的执行过程。
第一步,启动时扫描。 MccApplication 构造 SkillLoader,扫描全局 ~/.mcc/skills/ 与项目级 <项目>/.mcc/skills/,解析每个 SKILL.md 的文件头,得到一个技能列表。这份列表交给 SkillStage。
第二步,每轮注入清单。 ContextAssembler 依次执行各个 Stage。轮到 SkillStage 时,它把"行为说明 + 技能清单"拼成一条系统消息注入。清单里每条形如 - commit-helper: 规范化生成提交信息 - 当用户要创建 git 提交时(/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md)。
第三步,模型决策。 模型看到用户说"帮我把这些改动提交一下",在清单里识别出 commit-helper 与当前任务相关,于是先用 Read 读取那个 SKILL.md 的绝对路径,把完整正文取进上下文。
第四步,按照技能执行。 模型按照正文里的步骤一步步执行。
第五步,正文不常驻。 技能正文作为一次 Read 的结果留在会话历史里,和任何工具结果一样,会被 M6 的压缩链按预算管理。清单则每轮都在,始终很小。
整个过程里,Skills 只涉及一个 Stage 和一个加载器。AgentLoop 主循环、ModelClient、既有工具都不需要处理"技能"这个概念。
对它们来说,这只是上下文里多了一段清单,模型多读取了一个文件。
下一节我们来讲一下技能的磁盘布局,以及 SKILL.md 到底是什么样子。
7.3 技能的磁盘布局与 SKILL.md 格式
本篇涉及到的源码列表:
com.minicc.skill.Skill.java
com.minicc.skill.SkillLoader.java
上一节我们看了 M7 的整体结构。这一节我们从最底层开始讲:技能在磁盘上是怎么存放的,一个 SKILL.md 又是什么样子。
我们把这两件事确定清楚,后面 SkillLoader 怎么扫描、怎么解析就很自然了。
目录布局:全局 + 项目级两层
技能目录沿用的是"全局 + 项目级"两层,和配置、记忆是同一套约定。
~/.mcc/skills/ # 全局技能:所有项目通用
commit-helper/
SKILL.md
skillify/
SKILL.md
/Users/wangzheng/codecrush/.mcc/skills/ # 项目级技能:随仓库走(像 AGENT.md 一样提交进 git)
release-checklist/
SKILL.md
checklist.md # 技能可带引用资料,正文里让模型按需 Read我们把这个布局的几条约定一条条说清楚。
约定一:每个技能是一个目录
每个技能都是一个目录,目录名就是技能名。
目录里必须有一个 SKILL.md。如果没有,加载时我们就跳过这个目录。
我们只支持这种目录格式,不支持单独放置的单个 .md 文件。
这样做的好处是,一个技能对应一个目录。它除了 SKILL.md,还可以放入脚本、引用资料,正文里再让模型在需要时去 Read。
上面项目级例子里的 checklist.md 就是这样一份引用资料。
约定二:两层,同名时项目级覆盖全局
全局目录 ~/.mcc/skills/ 存放所有项目通用的技能。我们配置一次之后,各个项目都能使用。
项目级目录 <项目>/.mcc/skills/ 存放随仓库走的技能,像 AGENT.md 一样可以提交进 git,供团队共享。
两层如果有同名的技能,项目级覆盖全局。更靠近当前项目的那一份优先,这和配置、记忆的层叠约定完全一致。
约定三:全局目录不存在时自动创建
会话开始时,如果全局技能目录还不存在,程序会自动创建一个空目录。
这和记忆目录的做法一样,方便用户直接放入技能文件,不必自己先创建目录。
// 源码位置:com.minicc.skill.SkillLoader.java
public void ensureGlobalDirExists() {
if (globalSkillsDir == null) {
return;
}
try {
Files.createDirectories(globalSkillsDir);
} catch (IOException e) {
// 创建失败只打印一行,不会导致启动失败。
System.err.println("创建技能目录失败(已忽略):" + globalSkillsDir + " —— " + e.getMessage());
}
}SKILL.md 的格式
一个 SKILL.md 由两部分组成:一段 YAML 文件头,再加一段 markdown 正文。
我们来看一个完整的例子。
# 源码位置:~/.mcc/skills/commit-helper/SKILL.md
---
name: commit-helper
description: 规范化生成 git 提交信息
when_to_use: 当用户要创建 git 提交、或询问如何写提交信息时
---
# 生成规范的提交信息
按以下步骤操作:
1. 用 `Bash("git diff --staged")` 查看已暂存的改动,弄清这次提交做了什么。
2. 按 Conventional Commits 规范写 message:`<type>(<scope>): <subject>`,type 取
feat/fix/docs/refactor/test/chore 之一;正文用中文、祈使句、不超过 72 列。
3. 用 `Bash("git commit -m ...")` 提交;若有 pre-commit 钩子失败,读取报错并修复后重试。
注意:绝不要 `git add` 用户没让你加的文件;只提交已暂存的改动。--- 之间的那段是文件头,--- 之后的全部是正文。
文件头的三个字段会进入清单
文件头里有三个字段,它们是唯一会进入上下文清单的内容。
name:技能名。缺省时,我们使用目录名。description:简短描述,告诉模型这个技能是用来做什么的。when_to_use:何时该使用。这是模型判断相关性的关键,写得越具体越好。
只有这三项会进入清单。这些内容只够让模型认出这里有这么一项能力、大概什么时候用得上,不含任何操作细节。
正文随 Read 加载
--- 之后的全部 markdown 是正文。
正文里是真正的操作细节:详细步骤、注意事项、参数说明。
但正文只有模型 Read 这个文件时才进入上下文。会话开始时,我们不会加载正文。
这就是渐进式披露的两层:文件头常驻在清单里,正文在需要时再用 Read 读取。
正文里还可以引用同目录的其它文件,比如前面例子里项目级技能的 checklist.md,模型需要时再去 Read。
如果我们把 M7 和 M5 放在一起看,这个结构会非常清晰。
SKILL.md 的文件头,对应 MEMORY.md 索引里的一行。SKILL.md 的正文,对应记忆的主题文件。
两者都靠"入口常驻、内容在需要时 Read"实现渐进式披露。
布局和格式我们讲清楚了。下一节我们来讲一下 SkillLoader 怎么把这些目录扫描出来、把文件头解析出来。
7.4 SkillLoader:扫描、解析、去重
本篇涉及到的源码列表:
com.minicc.skill.Skill.java
com.minicc.skill.SkillLoader.java
上一节我们确定好了技能的磁盘布局和 SKILL.md 格式。这一节我们来讲一下把它们读进内存的 SkillLoader。
它要做三件事:扫描两层目录、解析每个 SKILL.md 的文件头、按名字去重。
这里有一个我们需要记住的点:它只读取文件头、不读取正文。
先看 Skill:一个技能的元数据
加载的结果是一批 Skill 对象。我们先看一下它是什么样子。
// 源码位置:com.minicc.skill.Skill.java
public record Skill(
String name, // 技能名(缺省取目录名)
String description, // 一句话描述(进清单)
String whenToUse, // 何时该用(进清单;模型据此判断相关性)
Path skillFile, // SKILL.md 的绝对路径(清单里给出,供模型 Read 取回正文)
Path baseDir // 技能目录(供正文引用的同目录资料定位)
) {}注意这里面没有"正文"这个字段。
Skill 只持有进入清单需要的几项,加上 SKILL.md 的路径。正文本身不在内存里,等模型调用 Read 时,才由 Read 工具读进来。
这就是渐进式披露在数据结构层面的体现。skillFile 这个字段,对应的正是 M5 里"要按需 Read 的那份主题文件"。
SkillLoader 的构造
SkillLoader 持有两个目录:全局的和项目级的。
// 源码位置:com.minicc.skill.SkillLoader.java
public class SkillLoader {
private final Path globalSkillsDir; // 全局 ~/.mcc/skills
private final Path projectSkillsDir; // 项目级 <项目>/.mcc/skills
public SkillLoader(Path globalSkillsDir, Path projectSkillsDir) {
this.globalSkillsDir = globalSkillsDir;
this.projectSkillsDir = projectSkillsDir;
}
// …
}loadAll:先全局、后项目级,同名覆盖
对外的入口是 loadAll。它可以概括为:先放入全局技能,再用项目级技能覆盖同名项。
// 源码位置:com.minicc.skill.SkillLoader.java
public List<Skill> loadAll() {
Map<String, Skill> byName = new LinkedHashMap<>();
for (Skill s : scanDir(globalSkillsDir)) { // 全局先放
byName.put(s.name(), s);
}
for (Skill s : scanDir(projectSkillsDir)) { // 项目级覆盖同名
byName.put(s.name(), s);
}
return new ArrayList<>(byName.values());
}这里有两个细节,值得我们说一下。
一是去重的实现。我们用一个 Map,键是技能名。全局的技能先 put,项目级的技能后 put,同名的技能自然就被项目级覆盖了。这就实现了上一节说的"项目级覆盖全局"。
二是我们为什么使用 LinkedHashMap。它能够保留插入顺序,返回的列表每次都是稳定顺序。这样清单每一轮都一致,前缀缓存才用得上。
scanDir:扫描一个目录
scanDir 负责扫描一层目录下的所有 skill-name/SKILL.md。
// 源码位置:com.minicc.skill.SkillLoader.java
private List<Skill> scanDir(Path dir) {
if (dir == null || !Files.isDirectory(dir)) {
return List.of(); // 目录不存在就返回空,不报错
}
List<Skill> skills = new ArrayList<>();
try (Stream<Path> entries = Files.list(dir)) {
// 按目录名排序,保证清单顺序稳定。
entries.filter(Files::isDirectory).sorted().forEach(skillDir -> {
Path file = skillDir.resolve("SKILL.md");
if (Files.isRegularFile(file)) { // 目录里没有 SKILL.md 就跳过
parseSkill(skillDir, file).ifPresent(skills::add);
}
});
} catch (IOException e) {
System.err.println("扫描技能目录失败(已忽略):" + dir + " —— " + e.getMessage());
}
return skills;
}它只检查目录项,逐个查找里面的 SKILL.md。如果找不到,它就跳过这个目录。这正是上一节说的"目录里必须有 SKILL.md"。
目录不存在时,它直接返回空列表,不报错。所以哪怕你一个技能都没有放入,整个流程也能正常执行完。
parseSkill:解析一个 SKILL.md 的文件头
parseSkill 才是真正读取文件、取出字段的地方。
// 源码位置:com.minicc.skill.SkillLoader.java
private Optional<Skill> parseSkill(Path skillDir, Path file) {
try {
String content = Files.readString(file, StandardCharsets.UTF_8);
Map<String, Object> fm = parseFrontmatter(content); // 复用 SnakeYAML
String name = str(fm.get("name"), skillDir.getFileName().toString()); // 缺省用目录名
String description = str(fm.get("description"), "");
String whenToUse = str(fm.get("when_to_use"), "");
if (description.isBlank()) {
description = name; // 空描述兜底为名字,避免清单里出现空描述
}
return Optional.of(new Skill(name, description, whenToUse, file, skillDir));
} catch (Exception e) {
System.err.println("解析技能失败(已跳过):" + file + " —— " + e.getMessage());
return Optional.empty();
}
}这里我们要留意一下。虽然它用 Files.readString 把整个文件读进来了,但它只从里面取出文件头的三个字段。
正文读完后即丢弃,不会放进 Skill。所以从加载器的角度看,正文始终没有进入会话上下文。
几个兜底也在这里:name 缺省时使用目录名,description 为空时用名字兜底,避免清单里出现空描述。
parseFrontmatter:复用 SnakeYAML
解析文件头时,我们直接复用项目里已经在使用的 SnakeYAML(它本来就用来读取 mcc.yml)。
// 源码位置:com.minicc.skill.SkillLoader.java
private static Map<String, Object> parseFrontmatter(String content) {
String s = content.stripLeading();
if (!s.startsWith("---")) {
return Map.of(); // 没有文件头就返回空 Map
}
int end = s.indexOf("\n---", 3); // 找到闭合的 ---
if (end < 0) {
return Map.of();
}
String yaml = s.substring(3, end); // 取两个 --- 之间那段
Object parsed = new Yaml().load(yaml);
return (parsed instanceof Map) ? (Map<String, Object>) parsed : Map.of();
}这段逻辑很直接:找到开头的 --- 和闭合的 ---,把中间那段 YAML 交给 SnakeYAML。
如果没有文件头,或者没有找到闭合的 ---,这个方法就返回一个空 Map。配合 parseSkill 里的兜底,这个技能仍然可以加载,只是字段使用缺省值。
容错:单个技能失败不影响其它技能
整个加载过程有一条贯穿的原则:如果某一个技能解析失败,它不影响其它技能,也不会让程序启动失败。
parseSkill 会捕获所有异常。解析失败的技能只打印一行,然后 return Optional.empty() 跳过。scanDir 里扫描目录出错,也只打印一行。
这个容错风格和配置、记忆的加载完全一致。
加载的部分我们讲完了。我们就得到了一份顺序稳定、已经按名字去重的技能列表。下一节我们来讲一下 SkillStage 怎么把它注入上下文。
7.5 SkillStage:把技能清单注入上下文
本篇涉及到的源码列表:
com.minicc.context.SkillStage.java
com.minicc.skill.SkillPromptText.java
上一节我们用 SkillLoader 拿到了一个技能列表。这一节我们来讲一下怎么把它注入上下文,也就是 SkillStage。
它每一轮往上下文里增加一条系统消息,分两部分:一段行为说明,再加一份技能清单。
SkillStage:一个 Stage
SkillStage 实现 AssemblyStage 接口,和 M5 的 MemoryStage、M6 的 CompactionStage 是同一类组件。
// 源码位置:com.minicc.context.SkillStage.java
public class SkillStage implements AssemblyStage {
private final List<Skill> skills;
private final int listingMaxChars; // 清单字符预算(来自配置 skills.listingMaxChars)
public SkillStage(List<Skill> skills, int listingMaxChars) {
this.skills = skills;
this.listingMaxChars = listingMaxChars;
}
@Override
public void contribute(List<Message> messages, Session session) {
if (skills == null || skills.isEmpty()) {
return; // 没有任何技能:什么都不加,不浪费上下文
}
String text = SkillPromptText.behavioralGuide() // Skills 是什么、怎么用(固定)
+ "\n\n## 可用技能清单\n\n"
+ SkillPromptText.renderListing(skills, listingMaxChars); // 带预算截断的一行一条
messages.add(new SystemMessage(text));
}
}它的 contribute 方法做的事情很简单:把"行为说明 + 技能清单"拼成一条 SystemMessage,再加入消息列表。
这里有一个细节,我们要强调一下:没有任何技能时,它直接 return,不会加入任何内容。这保证了"无技能时零注入",避免无谓占用上下文。
行为说明:告诉模型怎么用技能
拼接的第一部分是行为说明,它是一段固定文本,由 SkillPromptText.behavioralGuide() 提供。
// 源码位置:com.minicc.skill.SkillPromptText.java
public static String behavioralGuide() {
return """
# 技能(Skills)
你有一批可复用的「技能」——每个技能是一份写好的操作手册,告诉你某一类任务该怎么一步步做。
下面的清单只列出每个技能的名字、用途和它的 SKILL.md 文件路径(这是渐进式披露:清单常驻,正文按需)。
如何使用技能:
- 当用户的请求与某个技能匹配时,这是一条**强制要求**:先用 Read 读取那个技能的 SKILL.md(清单里给了绝对路径),
再开始做这项任务——不要只凭清单里的一句话描述就动手。
- 读完 SKILL.md 后,严格按它正文里的步骤执行;正文若引用了同目录的其它文件,按需再 Read。
- 绝不要嘴上提到某个技能却不去 Read 它;也不要在明显匹配时跳过技能、自己另起一套做法。
- 如果没有任何技能匹配当前任务,就按平常的方式正常处理,不必勉强套用技能。""";
}这段话里有几处是有意这样写的,我们分别说明一下。
第一,它把"强制要求"说在前面。匹配到技能时,模型必须先 Read 它的 SKILL.md,不能只凭清单里的简短描述就开始执行。这是为了避免模型不读取正文,就直接开始这项任务。
第二,它明确了加载的方式是"用 Read 读取"。我们没有单独做一个调用工具,而是复用既有的 Read。下一节我们再讲一下这一点。
第三,它给了一条反向约束:没有技能匹配时,模型就按照平常的方式处理,不必勉强套用技能。这是为了避免在没有匹配技能时也强行使用技能。
技能清单:一行一条
拼接的第二部分是技能清单,由 renderListing 把技能列表渲染出来。
// 源码位置:com.minicc.skill.SkillPromptText.java
public static String renderListing(List<Skill> skills, int maxChars) {
StringBuilder sb = new StringBuilder();
for (Skill s : skills) {
String line = formatEntry(s);
// 超预算:停止并给出「已截断」提示(/skills 命令仍能看全)。
if (maxChars > 0 && sb.length() + line.length() + 1 > maxChars) {
sb.append("> (技能较多,清单已按预算截断——未列出的技能可用 /skills 查看)\n");
break;
}
sb.append(line).append('\n');
}
return sb.toString().stripTrailing();
}它逐条拼接,每条占一行。拼接之前,它先计算一下,加上这一条会不会超出预算。如果超出了,它就停止拼接,并补上一句"已截断"的提示。
单条的格式与截断
每一条是什么样子,由 formatEntry 决定。
// 源码位置:com.minicc.skill.SkillPromptText.java
private static String formatEntry(Skill s) {
String desc = s.whenToUse().isBlank()
? s.description()
: s.description() + " - " + s.whenToUse();
if (desc.length() > MAX_ENTRY_CHARS) { // 单条上限 250
desc = desc.substring(0, MAX_ENTRY_CHARS - 1) + "…";
}
return "- " + s.name() + ": " + desc + "(" + s.skillFile() + ")";
}格式是 - 名字: 描述 - 何时用(SKILL.md 绝对路径)。
末尾那个绝对路径很关键,它就是模型接下来要用 Read 读取的目标。有了这个路径,模型才知道该去读取哪个文件。
截断分成两道。单条描述如果超过 250 个字符,我们就截断并加上省略号。整份清单如果超过 listingMaxChars(默认 8000),就停止继续追加。
这两道截断和 M5 MEMORY.md 的截断是同一种做法,目的都是让清单保持短小、占用可控。
渲染出来是什么样子
我们把两部分拼起来之后,上下文里的技能清单大致是这样。
# 技能(Skills)
…(行为说明)…
## 可用技能清单
- commit-helper: 规范化生成 git 提交信息 - 当用户要创建 git 提交时(/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md)
- release-checklist: 发布前检查清单 - 当用户准备发布、打 tag 时(/Users/wangzheng/codecrush/.mcc/skills/release-checklist/SKILL.md)模型根据这份清单判断相关性,用 Read 读取对应路径,再按照正文执行。整条链路到这里就完整了。
为什么插在记忆之后、历史之前
上一节讲架构的时候,我们提过这个位置。这里我们补充一下原因。
技能清单是稳定的靠前内容,每一轮基本不变。我们把它和系统提示词、记忆放在一起,前缀缓存就能命中。
我们把它放在会话历史之前,模型读取历史、做决策的时候,就已经知道当前有哪些技能可用。
清单注入的部分我们讲完了。下一节我们来讲一下最后一部分:正文的按需加载为什么能直接复用 Read,以及 /skills 命令和配置。
7.6 技能正文按需加载 + skills命令 + 配置
本篇涉及到的源码列表:
com.minicc.tool.builtin.ReadTool.java
com.minicc.cli.command.SkillsCommand.java
com.minicc.config.MccConfig.java
com.minicc.config.ConfigLoader.java
mcc.yml
前面几节,我们已经把技能扫描进来了,也把清单注入上下文了。这一节我们补上最后一部分:技能正文到底是怎么加载的。
技能正文的加载不需要新写代码,我们直接复用 M1 已经实现的 Read 工具。
M7 不新增"调用技能"的工具
一个很自然的想法是,我们给技能做一个专门的调用工具。模型报出技能名之后,工具把正文展开并注入对话。
M7 没有这么做。
我们的做法是:清单里每条都带了 SKILL.md 的绝对路径,模型用 Read 读取那个路径,正文就取回来了。
因此不需要新增工具。
为什么复用 Read 就够了
这是有意的设计,有几个具体的好处。
第一,我们不新增任何工具。Read 本来就支持绝对路径、行号、大文件分段,正文再长也能稳妥读进来。清单里给出的就是绝对路径,模型直接用 Read 读取即可。
第二,正文会自动进入已有机制。技能正文作为一次 Read 的结果留在历史里,自动接受 M6 压缩链按 Read 的预算管理。审批、持久化这些机制也都照常工作,不需要任何特殊处理。
这里还有一处和 M6 一致的设计。M6 给 Read 的结果设的是无限预算、永不落盘。因为落盘后模型还会根据路径再次 Read,形成死循环。技能正文也是 Read 读回来的,所以它不会被落盘后又被重复读取。
第三,这和 M5 的记忆是同一种做法。模型"看着 MEMORY.md 索引、用 Read 读取主题文件",和"看着技能清单、用 Read 读取 SKILL.md",是同一个动作、同一个工具、同一种渐进式披露。两边统一,减少了代码理解的负担。
整条链回顾一遍
我们把正文加载放回整条链路里看一下。
> 帮我把刚才的改动提交一下
⏺ 我先读一下 commit-helper 技能
⏺ Read(file_path=/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md)
⎿ (正文:先看 git diff --staged、按 Conventional Commits 写 message……)
⏺ Bash(command="git diff --staged")
⎿ …
⏺ Bash(command="git commit -m \"feat(order): 新增订单取消接口\"")
⎿ [main a1b2c3d] feat(order): 新增订单取消接口清单让模型知道有这样一项技能,以及文件在哪里。Read 把正文取进上下文。剩下的步骤使用的全是既有工具。
对 AgentLoop 和这些工具来说,这一轮只是模型多读取了一个文件,它们完全不知道"技能"这个概念。
/skills 命令:查看当前有哪些技能
我们再增加一个查看命令 /skills。它和 /tools 完全同构,只负责展示,不修改任何状态。
// 源码位置:com.minicc.cli.command.SkillsCommand.java
@Override
public boolean run(String args) {
if (!enabled) {
renderer.info("Skills 已关闭(skills.enabled: false)。");
return false;
}
if (skills == null || skills.isEmpty()) {
renderer.info("当前没有可用技能,可在 ~/.mcc/skills/ 或 <项目>/.mcc/skills/ 下添加 skill-name/SKILL.md。");
return false;
}
renderer.info("可用技能(" + skills.size() + " 个):");
for (Skill s : skills) {
renderer.info(" " + s.name() + ":" + s.description()
+ (s.whenToUse().isBlank() ? "" : "(" + s.whenToUse() + ")"));
renderer.info(" " + s.skillFile());
}
return false;
}这里有一个值得我们注意的地方:即使上下文里的清单因为预算被截断了,/skills 仍然会把全部技能列出来。清单的截断只影响发给模型的那一份,不影响你查看。
配置:一组可选项
M7 新增一组配置,都有合理的默认值,不配置也能运行。
# 源码位置:mcc.yml
skills:
enabled: true # 是否启用 Skills(默认开;关掉则不扫描目录、SkillStage 不注入)
listingMaxChars: 8000 # 技能清单在上下文里的字符上限(超出按预算截断;/skills 仍能看全)skills.enabled:总开关。我们把它关掉之后,程序连目录都不扫描,SkillStage也不注入,/skills会提示已经关闭。它方便我们对比"有技能"和"无技能"时上下文的差异。skills.listingMaxChars:清单字符预算,缺省 8000。技能很多时,清单会按这个上限截断,但/skills仍然能看全。
还有一点我们要说明:技能目录没有做成配置项。它固定为全局 ~/.mcc/skills/ 和项目级 <项目>/.mcc/skills/ 两层,和记忆、配置的层叠约定一致,因此我们不再单独增加一个配置项。
配置是怎么读取进来的
我们在 MccConfig 里增加了一个 SkillSettings 子配置。
// 源码位置:com.minicc.config.MccConfig.java
public record SkillSettings(
boolean enabled,
int listingMaxChars) {
}ConfigLoader 负责把 YAML 里的 skills 段读取成 SkillSettings,缺省字段回落到默认值。
// 源码位置:com.minicc.config.ConfigLoader.java
private static MccConfig.SkillSettings asSkills(Object node, MccConfig.SkillSettings base) {
if (!(node instanceof Map)) {
return base; // 没写 skills 段就用默认
}
Map<String, Object> m = (Map<String, Object>) node;
boolean enabled = asBool(m.get("enabled"), base.enabled());
int listingMaxChars = asInt(m.get("listingMaxChars"), base.listingMaxChars());
return new MccConfig.SkillSettings(enabled, listingMaxChars);
}这种缺省回落的处理方式,和 M6 读取 compact 配置是一样的:如果读不到某个字段,就回落到默认值,不会因为少写一个字段就报错。
本章小结
到这里,M7 就完成了。我们看一下这一章一共修改了哪些地方。
我们新增了一个 skill 包(三个类)、一个 Stage(SkillStage)、一个 /skills 命令。既有代码里,只有 MccApplication 的装配和几处配置有修改。
控制循环、工具接口、既有工具、审批、持久化、记忆、压缩,全都不需要修改。
这正是 M1 把上下文组装器做成扩展点、又让 Read 足够通用所留下的回报。它和 M5 的记忆加载,是同一类做法的两次应用。
现在,你给这个 Agent 新增一项专业能力,只需要往技能目录里放入一个 SKILL.md,不需要修改任何一行代码。
下一章我们进入 M8,为 Agent 增加 Plan Mode,让它先给出计划,确认之后再修改代码。
