跳至主要內容

PaiCLI Skill 系统：让 Agent 学会正确的做事方法

沉默王二约 5829 字大约 19 分钟

PaiCLI Skill 系统：让 Agent 学会正确的做事方法

大家好，我是二哥呀。

上一期我们搞定了 CDP 会话复用，Agent 终于能直连日常 Chrome 了，GitHub 私有仓库、内网系统、飞书文档这些需要登录的内容统统能让Agent看到了。

但又有了新的问题。

比如说，让 PaiCLI 抓一篇未知的 URL。

合理的决策是：先用 web_fetch 试试能不能直接抓到文章内容，抓不到就切 Chrome DevTools MCP 上浏览器，浏览器也抓不到，最后再用 Jina Reader 试一次。

这一期，我们给 PaiCLI 加上 Skill 系统。

决定 Agent 在什么场景下用什么工具、遇到阻拦怎么绕。加完之后，PaiCLI 就从一个“有一堆工具的 Agent”变成了一个“有经验的 Agent”。

01、Skill 和 MCP 的区别

MCP 提供的是能力，能搜索、能抓网页、能操作浏览器。

Skill 提供的是决策，什么时候搜索、什么时候抓网页、什么时候启动浏览器。

Claude Code 在 2025 年底首先引入了 Skill 的概念。

一个 Skill 就是一个文件夹，里面放一个 SKILL.md（决策手册）加上可选的 references 参考文件。

截止到目前，SKILL.md 已经不是 Claude Code 一家的事了。Anthropic、OpenAI、Google 三家在 Linux Foundation 下面共同成立了 Agentic AI Foundation，把 SKILL.md 定成了跨工具的开放标准。

也就是说，你给 Claude Code 写的 Skill，拿到 Codex 上也能直接用。

02、Skill的三层加载架构

PaiCLI 的 Skill 系统设计了三层加载机制：

第一层：内置 Skill，打包在 PaiCLI 的 jar 包里，随版本发布。目前内置了一个 web-access Skill，教 Agent 怎么做联网操作。

第二层：用户级 Skill，放在 ~/.paicli/skills/<name>/SKILL.md。放自己写的全局 Skill，所有项目都能用。

第三层：项目级 Skill，放在 <项目目录>/.paicli/skills/<name>/SKILL.md。针对特定项目的 Skill，优先级最高。

SkillRegistry 是管理这三层扫描和合并的核心类。扫描的时候按 builtin → user → project 的顺序处理，每扫到一个同名 Skill 就直接覆盖前一层的。

PaiCLI 启动时会输出一段 Skill 加载汇总：

📚 Skills 加载（1 个）...
   ✓ web-access      builtin   description 88 字符
   1/1 启用，索引段共 0.6KB

这段日志一眼就能看到有多少 Skill 被加载了、来源是什么、索引段占了多大空间。

来验证一下。

启动 PaiCLI，输入 /skill list：

只有一个内置的 web-access。现在我在用户目录创建一个同名 Skill 试试覆盖效果：

mkdir -p ~/.paicli/skills/web-access
cat > ~/.paicli/skills/web-access/SKILL.md << 'EOF'
---
name: web-access
description: 用户自定义的联网操作指引（覆盖内置版）
version: "9.9.9"
---

这是用户版的 web-access，优先级高于内置版。
EOF

然后在 PaiCLI 里执行 /skill reload：

来源从 builtin 变成了 user，覆盖生效了。

验证完记得把用户级的删掉，恢复内置版本：

rm -rf ~/.paicli/skills/web-access

再 /skill reload 就回到内置的了。

03、SKILL.md 的结构

每个 Skill 的核心就是一个 SKILL.md 文件，分两部分：YAML frontmatter（元数据）和 frontmatter 之后的 Markdown 决策手册。后文把前者里的 name + description 叫“索引”，把后者叫“SKILL.md 正文”，代码里对应 Skill.body()。

---
name: web-access
description: |
  所有联网操作必须通过此 skill 处理，
  包括搜索、网页抓取、登录后操作
version: "1.0.0"
author: PaiCLI
tags: [web, browser, search]
---

# web-access Skill

## 浏览哲学

明确目标 → 选择起点 → 过程校验 → 完成判断...

frontmatter 只有两个必填字段：name 和 description。

version、author、tags 都是选填。未知字段直接忽略。

body 部分就是给 LLM 看的决策手册。写什么都行，但核心是告诉 LLM 遇到什么场景做什么决策。

这里有个关键设计：body 不是启动时就塞进 system prompt 的。LLM 在 system prompt 里只能看到每个 Skill 的 name 和 description（一句话摘要），需要时才通过 load_skill 工具加载完整 body。

为什么这么设计？

因为 system prompt 是有 token 预算的。如果启动时把所有 Skill 的完整内容都塞进去，装 10 个 Skill 就可能吃掉好几万 token。按需加载，轻量索引，这是 Claude Code 的 Skill 系统采用的设计理念，叫做 Progressive Disclosure（渐进式披露）。

04、手写 YAML 解析器

SkillFrontmatterParser 覆盖了 95% 的真实使用场景。

来看几个 case。正常的单行值：

name: web-access
version: "1.0.0"

多行 description（| 管道符）：

description: |
  所有联网操作必须通过此 skill 处理，
  包括搜索、网页抓取、登录后操作

内联数组：

tags: [web, browser, search]

如果写了我们不支持的语法，比如嵌套对象 {nested: object}，解析器会跳过这个字段并在 stderr 输出一条警告，不会阻塞其他 Skill 的加载。

⚠️ Skill 'broken' frontmatter 解析警告：第 5 行包含不支持的语法，已跳过

05、让 LLM 自己决定加载什么

这是整个 Skill 系统最核心的机制。

传统做法是用关键词匹配。用户说“帮我看网页”，就自动加载 web-access Skill。但关键词匹配永远不够精确，“看网页”“浏览器”“抓取”“搜索”都可能触发，也可能漏掉。

PaiCLI 的做法是：把 load_skill 注册为一个内置工具，让 LLM 自己判断要不要调用。

LLM 的 system prompt 里会有一段 Skill 索引：

## 可用 Skills（按需调用 load_skill 加载完整指引）

- **web-access**: 所有联网操作必须通过此 skill 处理，包括搜索、网页抓取、登录后操作...

判断准则：当任务描述匹配某个 skill 的触发场景时，调用 load_skill(name) 加载完整指引；
加载后完整指引会紧跟在 load_skill 工具结果之后，以 "## 已加载 Skill" 段落出现，先读指引再继续当前任务。
正文还在上下文里时直接按它做；上下文压缩后正文会被移出，还需要时重新 load_skill。

LLM 看到问题涉及联网操作，就自己调 load_skill("web-access")。

来验证一下。直接对 PaiCLI 说：

> 帮我看下 https://mp.weixin.qq.com/s/RB7kF_BbsJZ5_Hmu9PxWdg 这篇文章讲了什么

观察 Agent 的行为：

模型先用 web_fetch 试了一次（微信文章是 SPA，抓不到文章内容），接着切 Chrome DevTools MCP 用浏览器打开页面拿到了完整内容。

不过仔细看思考过程，模型这一次其实没有调用 load_skill，它说的是“According to my instructions”，依据的是 system prompt 里的联网路由规则。“先 web_fetch、失败再切浏览器”这条规则 system prompt 里本来就有。Skill 真正派上用场的，是 system prompt 没有覆盖、只写在 SKILL.md 里的经验，比如各站点的登录态处理、什么时候改用 Jina。

这就是 Skill 的价值——让 Agent 学会正确的做事方法。

06、SKILL.md 正文什么时候生效

当 LLM 调用 load_skill("web-access") 时，PaiCLI 做了两件事：

  1. 工具返回一条简短确认：“已加载 skill 'web-access' 的完整指引（N 字符），正文紧跟在本工具结果之后”
  2. Agent 拿到这批工具结果后，在下一次请求模型之前，再追加一条 user 消息，里面装着 SKILL.md 正文。后文把这条消息叫“注入消息”，它长这样：
[PAICLI_SKILL_INJECTION]
以下是刚才 load_skill 加载的 Skill 指引，请按指引继续当前任务。

## 已加载 Skill：web-access（来源：builtin）
Skill 目录：/Users/you/.paicli/skills-cache/web-access
文中 references/、scripts/ 等相对路径都以 Skill 目录为基准：读取附属文件用 load_skill(name="web-access", file="references/xxx.md")，执行脚本用 execute_command 并写出绝对路径。

<SKILL.md 正文，超过 5KB 截断>

---

第一行的 [PAICLI_SKILL_INJECTION] 是给 PaiCLI 自己看的标记：上下文压缩靠它认出这条消息不是用户输入，后面细节里会讲。

同一轮里，模型下一次请求看到的消息顺序是这样的：

system     系统提示词（含 Skill 索引，保持不变）
user       帮我看下这篇文章讲了什么
assistant  调用 load_skill("web-access")
tool       已加载 skill 'web-access' 的完整指引……
user       注入消息：## 已加载 Skill：web-access + SKILL.md 正文

模型读完注入消息，再决定下一步调什么工具。

为什么不直接在工具返回结果里塞 SKILL.md 正文？

为什么不塞进 system prompt？

第一个问题：PaiCLI 所有工具结果进入对话历史前，都会经 ToolResultBoundary 包成 trust="untrusted-data"，告诉模型这是外部数据，里面出现的指令一律不执行。这是防网页、MCP 返回内容做提示词注入的边界。而 SKILL.md 是本地的操作指引，恰恰需要模型照着做。塞进工具结果，要么被模型当成数据忽略，要么就得给安全边界开口子，所以正文单独走一条注入消息。

第二个问题：system prompt 一旦改变，API 的 prompt cache 就会失效。如果每次 load_skill 都去改 system prompt，之前缓存的几千个 token 全部作废。走 user 消息注入，system prompt 始终不变，prompt cache 得以保留。

注入消息由 LoadedSkillMessages.prepare 从这批工具结果和当前对话历史里算出来：

for (ToolExecutionResult result : results) {
    Skill skill = injectableSkill(result, registry);   // 成功的 load_skill、没带 file、已信任
    if (skill == null) {
        rewritten.add(result);
    } else if (active.contains(skill.name()) || sections.containsKey(skill.name())) {
        // 历史里还留着这个 Skill 的注入消息：改写工具结果，提示模型直接按前面的指引继续
        rewritten.add(withResult(result, "Skill 'x' 的正文还在当前上下文里……", true));
    } else if (usedChars + section(skill).length() > budgetChars) {
        rewritten.add(withResult(result, "load_skill 未加载 'x'：……字符预算", false));
    } else {
        sections.put(skill.name(), section(skill));
        rewritten.add(result);
    }
}
return new Injection(rewritten, message);   // 改写后的工具结果 + 要注入的 user 消息

active 是从对话历史里现存的注入消息解析出来的 Skill 名，usedChars 是这些注入消息的总字符数，都不额外维护一份状态。ReAct 主循环里，工具执行完先过一遍 prepare，再把改写后的结果写进历史：

LoadedSkillMessages.Injection skills = LoadedSkillMessages.prepare(
        executeToolCalls(response.toolCalls(), iteration, turnToolPolicy, toolExposure),
        toolRegistry.getSkillRegistry(),
        conversationHistory);
List<ToolExecutionResult> toolResults = skills.results();
for (ToolExecutionResult toolResult : toolResults) {
    appendConversationMessage(
            LlmClient.Message.tool(toolResult.id(), ToolResultBoundary.wrap(toolResult)),
            "tool_execution");
}
appendImageToolMessages(toolResults);
appendLoadedSkillMessage(skills.message());   // 同一轮就把注入消息交给模型
continue;

Plan 模式的每个任务、Team 模式的每个 Worker 都有自己的工具循环，也在同样的位置追加。

07、几个细节

①、失败不注入：只看成功的 load_skill 结果，并且按参数重新从 SkillRegistry 查一遍。Skill 不存在、已禁用，或者这次调用被策略拒绝，都不会生成注入消息。

②、上下文里只留一份：去重按对话历史判断。某个 Skill 的注入消息还在历史里时，模型再调 load_skill，工具结果会被改写成“正文还在当前上下文里”，不会再追加一条。注入消息被压缩删掉之后，再加载就是正常注入。

③、5KB 截断：SKILL.md 正文超过 5KB 会在行边界截断，末尾提示 load_skill(name="x", file="SKILL.md", offset=N)，模型照着调用就能从截断处接着读。这里不能提示 /skill show，那是给用户敲的命令，模型调不了。

④、上下文预算：历史里注入消息合计默认不超过 16KB（PAICLI_SKILL_BODY_BUDGET 可调）。超出时新的 load_skill 不注入，返回提示让模型先按已加载的指引把当前任务做完；/compact 或 /clear 删掉注入消息后，预算自然释放。不按数量设上限，也不在超预算时自动淘汰旧的注入消息：淘汰发生在模型不知情的时候，它还以为指引在，比没加载更糟。压缩删除不一样，摘要里会写明哪些 Skill 被移出。

⑤、没有共享状态：注入消息只从当前这批工具结果和调用方自己的对话历史里算出来，谁加载谁拿到。Plan 模式的并行任务、Team 模式的各个 Worker 各看各的历史，互不串。Team 模式的 Planner 和 Reviewer 请求不暴露工具，调不了 load_skill。

⑥、压缩时丢了再读：注入消息留在对话历史里，后续请求模型都能看到。上下文压缩按 user 消息切分轮次，带 [PAICLI_SKILL_INJECTION] 标记的注入消息不算轮次，否则一次 load_skill 就多出一个假轮次，挤掉真实的用户上下文。被切到摘要范围里的注入消息也不交给摘要模型（摘要会把操作指引压成一两句，甚至记成用户要求），而是直接删除，摘要末尾列出对应的 Skill 名，模型还需要时重新 load_skill。改了 SKILL.md 之后，先 /skill reload，再 /compact 或 /clear，才能让模型读到新版本。

⑦、项目级 Skill 要先信任：.paicli/skills/ 随仓库分发，克隆一个陌生仓库，里面的 SKILL.md 不该直接以可信指引的身份进上下文。未信任的项目级 Skill 被加载时，不生成注入消息，SKILL.md 正文放在工具结果里，跟网页内容一样包成 untrusted-data，模型只能拿来参考。用户先 /skill show 看过正文，再 /skill trust <name> 信任，之后加载才生成注入消息。信任绑定 SKILL.md 路径和 SKILL.md 正文的指纹，仓库更新改了正文就要重新信任。内置和用户级 Skill 是你自己装的，不需要这一步。

先让 Agent 加载 web-access：

> 帮我看 https://mp.weixin.qq.com/s/RB7kF_BbsJZ5_Hmu9PxWdg
[Agent 调用 load_skill("web-access")，完成操作]

> 再看一篇 https://www.xiaohongshu.com/explore/67371552000000001901b2aa?xsec_token=ABNTdVgv-ySnmZCIY8jBfaLyQ4YqdGukYbpdtR_-S6j-0=&xsec_source=pc_user
[观察：Agent 不会重复调用 load_skill，因为 system prompt 提示了“同一会话内一次足够”]

第二轮不需要再调 load_skill，上一轮的注入消息还在对话历史里，模型直接参照就行。

08、web-access Skill 深度解析

PaiCLI 内置的第一个 Skill 就是 web-access，是使用频率最高的决策手册。

上一期我们已经讲过 CDP 的原理，这一期重点看 web-access 作为 Skill 给 Agent 带来了什么决策能力。

web-access 的 SKILL.md 大致分这几个板块：

①、浏览哲学，四步法则：明确目标（要拿什么信息）→ 选择起点（用最轻量的方式尝试）→ 过程校验（拿到的内容是否符合预期）→ 完成判断（信息是否充分）。

②、工具选择表，不同场景对应不同工具。搜索用 web_search，已知 URL 用 web_fetch，SPA 动态渲染站点用 Chrome DevTools MCP 的 navigate_page + take_snapshot，web_fetch 和浏览器都搞不定的最后交给 Jina Reader（curl https://r.jina.ai/<url>）。

③、浏览器优先级，这是决策手册最精华的部分。渐进式升级策略：先 web_fetch 试一把（成本最低，token 最少）→ 失败了切 Chrome DevTools isolated 模式（独立实例）→ 需要登录态的切 shared 模式（复用你的 Chrome）。

④、站点经验目录。references/site-patterns/ 下面预置了 6 个站点的操作经验：

站点要点
mp.weixin.qq.comSPA 渲染，web_fetch 拿不到文章内容，必须走浏览器
zhuanlan.zhihu.com懒加载，需要滚动触发内容渲染
x.com频率限制严格，登录态影响内容可见性
xiaohongshu.com反爬较强，只能用 CDP 模式
github.comAPI 优先，登录态看私仓
juejin.cnSSR 渲染友好，web_fetch 通常能直接抓到

核心就三段：这个站是什么技术架构（SPA 还是 SSR、反爬强不强、需不需要登录），什么方式能成功拿到内容（已验证的 URL 模式、CSS 选择器、JS 提取片段），以及常见的失败模式和应对办法。

内置的 SKILL.md 和 references 在 PaiCLI 启动时由 SkillBuiltinExtractor 从 jar 包解压到 ~/.paicli/skills-cache/web-access/。

解压不是每次启动都跑的，extractor 会检查 skills-cache/<name>/.version 文件和 jar 内置版本号是否一致，一致就跳过，节省启动时的 IO 开销。版本不一致或 .version 文件不存在时才重写整个 cache 目录。

LLM 通过 load_skill 的 file 参数读取这些文件。read_file 受路径围栏限制只能读项目内文件，读不到 ~/.paicli 下的 Skill 目录；file 参数只放行当前 Skill 自己的目录，../ 逃出去会被拒绝，传目录则列出其中的文件。

比如它准备抓微信公众号文章时，会先 load_skill(name="web-access", file="references/site-patterns") 看有哪些站点，再 load_skill(name="web-access", file="references/site-patterns/mp.weixin.qq.com.md")，看到“SPA 渲染、web_fetch 无效、必须 CDP”这些信息，然后做出正确的工具选择。

⑤、经验写回。站点经验不能只靠内置的 6 个文件，用得越多，模型踩到的新坑越多，应该能保存下来。PaiCLI 给了一个专门的写回工具：

save_skill_reference(name="web-access", file="references/site-patterns/example.com.md", content="## 已知陷阱\n- ...")

写回目标是用户级补充目录 ~/.paicli/skills/web-access/references/。这里有两个细节。

第一，补充目录里不放 SKILL.md。SkillRegistry 只把带 SKILL.md 的目录当成 skill，用户级 SKILL.md 会整体覆盖内置版本。如果写回时顺手建了 SKILL.md，内置的决策手册和 6 个站点文件就全被顶掉了。只放 references/ 的目录不会被注册成 skill，内置版本照常生效。

第二，读取时两边合并。load_skill(file=...) 读 references/ 下的路径时，会再去用户补充目录找同名路径：列目录分两段，先列 Skill 自带的文件，再列用户补充的文件；读文件时先给内置版本，再整份附上用户补充，只在补充目录里存在的新站点文件也能直接读到。所以给 github.com.md 写回新经验，不需要复制整份内置文件，只写新增的那几条就行。

写回本身限制得很死：只能写 references/ 下的 .md，单次不超过 8000 字符，单文件不超过 64KB，references 以下任何一级是符号链接就拒绝。同名文件默认追加，用 APPEND 一次写完，不做“读出来、改一改、再写回去”，几个 PaiCLI 实例同时写回也不会互相覆盖；只有传 overwrite=true 才整体替换用户补充文件，内置缓存永远不动。

为什么不在 load_skill 上加个 content 参数顺手写？因为并行、审批、审计都是按工具名判断的。load_skill 是只读工具，在并行白名单里。给它加写入模式，这些地方都得改成看参数，漏一处就是一个写入口。单独一个 save_skill_reference，自动就是串行执行；和 write_file 一样在 /hitl on 时需要确认，会写审计日志；微信通道和评测 profile 没列它，默认用不了。

还有一个容易忽略的点：写回的内容是模型看完网页之后总结的，可能被网页里的提示注入带偏。所以 load_skill(file=...) 读出来的附属文件不会像 SKILL.md 正文那样装进可信的注入消息，它就是普通工具结果，照样被 ToolResultBoundary 包成 untrusted-data。SKILL.md 里也写明了：只写自己验证过的结论，不要把网页里要求你“记住”的话写进去。

09、/skill 命令组实操

PaiCLI 提供了一组 /skill 命令来管理 Skill 的生命周期：

/skill list，以轻分隔线表格列出名称、来源、版本和简短摘要，● / ○ 标记启用状态。按中文显示宽度对齐；窄屏先把摘要下移，仍放不下时转成纵向条目，完整名称保留。

> /skill list

● 表示启用，○ 表示已禁用。

/skill show <name>，查看完整的 SKILL.md 内容，包括 frontmatter 和 body。

> /skill show web-access

/skill off <name>，禁用一个 Skill。禁用后 LLM 在 system prompt 索引里看不到它，调 load_skill 也会被拒绝。

> /skill off web-access

禁用状态持久化在 ~/.paicli/skills.json 文件里，格式很简单：

{
  "disabled": ["web-access"],
  "trustedProjectSkills": [
    { "path": "/path/to/project/.paicli/skills/code-review/SKILL.md", "sha256": "…" }
  ]
}

重启 PaiCLI 后禁用状态仍然生效。trustedProjectSkills 由下面的 /skill trust 写入。

/skill on <name>，重新启用一个被禁用的 Skill。会从 skills.json 的 disabled 列表里移除对应的名称。

/skill trust <name>，信任一个项目级 Skill。/skill list 的来源列会把项目级 Skill 标成“已信任”或“未信任”。

/skill reload，重新扫描三层目录，热加载新增或修改的 Skill。

reload 只影响下一轮对话，不会打断当前正在进行的 LLM 调用。

10、写一个自己的 Skill

理解了原理，我们来动手写一个项目级 Skill。

假设你的项目有一套固定的代码审查流程，每次 review 都要检查安全漏洞、性能隐患、代码风格三个维度。你可以把这套经验写成一个 Skill：

mkdir -p .paicli/skills/code-review
cat > .paicli/skills/code-review/SKILL.md << 'EOF'
---
name: code-review
description: |
  代码审查决策手册，当用户要求 review 代码时加载，
  按安全、性能、风格三个维度逐项检查
version: "1.0.0"
author: 你的名字
tags: [review, security, performance]
---

# Code Review Skill

## 审查流程

收到代码审查请求时，按以下顺序执行：

### 1. 安全维度

- 检查 SQL 注入风险（是否使用参数化查询）
- 检查 XSS 风险（是否对用户输入做转义）
- 检查硬编码的 API Key 或密码
- 检查文件路径拼接是否存在路径遍历风险

### 2. 性能维度

- N+1 查询问题
- 大循环内的数据库调用
- 未关闭的资源（连接、流）
- 不必要的同步锁

### 3. 风格维度

- 方法长度是否超过 50 行
- 嵌套深度是否超过 4 层
- 命名是否清晰表达意图
EOF

保存后 /skill reload，PaiCLI 就能识别了。这是项目级 Skill，/skill show code-review 确认内容后再 /skill trust code-review：

下次你说“帮我 review 一下这段代码”，LLM 在 system prompt 索引里看到 code-review 的 description 和你的请求匹配，就会调用 load_skill("code-review")，然后按安全、性能、风格三个维度逐项检查。

11、PaiCLI如何写到简历上？

项目名称：PaiCLI - Skill-Driven Agent CLI

项目简介：基于 Java 实现的 AI Agent 命令行工具，支持 Skill 系统实现决策知识驱动的智能体能力，兼容 SKILL.md 开放标准。

技术栈：Java 21、Claude API、Chrome DevTools Protocol、MCP 协议、YAML 解析

核心职责：

  • 设计并实现三层 Skill 加载架构（builtin/user/project），支持同名覆盖和热重载，实现决策知识的分层复用
  • 实现 load_skill 内置工具，LLM 通过语义理解自行加载
  • 设计 SKILL.md 正文的注入机制，load_skill 成功后同一轮追加一条独立的注入消息，不改 system prompt 以保留 prompt cache 命中，也不混入 untrusted 工具结果；并行任务之间无共享状态
  • 让上下文压缩识别注入消息：不计入用户轮次、不交给摘要模型，压缩时删除并在摘要里提示模型按需重新加载；上下文内去重和 16KB 注入预算由代码保证，不依赖提示词
  • 为随仓库分发的项目级 Skill 加信任边界，未信任时 SKILL.md 正文按不可信数据处理，信任绑定正文指纹
  • 设计 Skill 参考资料的读取与写回通道：内置缓存与用户级补充目录合并读取，经验写回限定在用户级 references 的 Markdown 文件，不放宽项目路径围栏，写回内容按不可信数据处理