Agent Skills 不是文档，是给 Agent 的 onboarding——三级披露和防过期，才是技能包的命门

现状之痛：Agent Skills 这个词这两周在圈子里密集出现：Anthropic 把技能做成了开放标准，Addy Osmani 开源了 agent-skills，中文社区里技能包教程也越来越多。可我自己踩过一圈后发现，大多数人建技能包的姿势是错的——把几十页经验塞进一个 SKILL.md，Agent 要么找不到它，要么找到了也带不动上下文；技能包建完就躺在目录里吃灰，三个月后模型一升级、工具一换接口，全部作废重来。

读完你将：拿到建技能包的三个工程判断：为什么技能不是文档而是 onboarding；Anthropic 三级披露（metadata → SKILL.md → 捆绑文件）到底怎么省上下文；以及技能真正的命门——防过期维护闭环怎么转。全部来自我跑了 276 天的内容生产系统：错误账本 60+ 条、每晚复盘回灌、17 项写作门禁。

前一篇聊 Coding Agent 供应链安全时我说过一句话：agent 的产出是提案，不是成品。今天往前再推一步——给 agent 的准备物也一样：技能包不是给人看的文档，是给 agent 走的 onboarding 流程。

一、Agent Skills 到底是什么：先分清三个东西

Anthropic Engineering 博客《Equipping agents for the real world with Agent Skills》把技能讲得很清楚：一个技能 = 一个 SKILL.md + 可选的一堆捆绑文件，放在约定的目录里，agent 能自己发现、自己决定什么时候用。

很多教程把技能当成「高级 prompt」来写：把系统提示词加长、加详细、加例子，然后包一层壳叫技能。这是第一个坑。技能和 prompt 有三个本质区别：

prompt 是被动塞进上下文的，技能是 agent 主动按需翻开的；
prompt 没有边界，技能有 description（触发条件）来声明自己管什么、不管什么；
prompt 改一次全线重跑，技能改一次只影响被它命中的任务。

给 Agent 建技能，不是写文档，是写 onboarding。 文档假设人会主动读，onboarding 假设人按顺序走完每一步；agent 不会主动读任何东西，它只会被 description 命中后翻开 SKILL.md。

二、三级披露：上下文只装索引，不装全书

技能规范里最容易被忽略、也最值钱的设计，是 progressive disclosure（渐进式披露），分三级：

第一级 metadata：一行 description，每轮都在上下文里，只回答「什么时候该用这个技能」；
第二级 SKILL.md：命中才载入，写步骤、边界、验收标准，要求短到能一次读完；
第三级捆绑文件：references、scripts 留在磁盘，用到才按路径调用，长材料不占上下文。

上下文只装索引，不装全书。 这一条解决的不是「塞不下」，而是「找不着」——上下文再大，也扛不住你把一百个技能包全文塞进去；而 agent 真正需要决策的那一刻，往往只需要翻开那两三页。

我对这套设计的体会来自自己的技能目录：SKILL.md 只写触发条件、主流程、验证命令，references 放长规范，scripts 放工具。写作、配图、复盘这些技能全是这个结构，用了一年多没出现上下文撑爆的问题。避坑提示：SKILL.md 写超过一屏，基本可以判定你又在写长 prompt 了。

配图技能是 9 月 8 日刚加过门禁的，正好当例子——本稿 3 张配图生成后，全部跑过布局验证才敢用：

# 配图生成后的物理验证（2026-09-08 固化，本稿实测输出）
python3 /root/hermes-harness/verify/verify_image_layout.py \
  figs-as-20260908/as1-three-level.png \
  figs-as-20260908/as2-onboarding.png \
  figs-as-20260908/as3-rot-loop.png
# ✅ as1-three-level.png: 布局通过 (1080x1350)
# ✅ as2-onboarding.png: 布局通过 (1080x1350)
# ✅ as3-rot-loop.png: 布局通过 (1080x1350)

这背后是同一套逻辑：把「应该检查」编译成「必须过闸」，而不是靠每次生成时肉眼盯。门禁代码长这样（真实代码节选）：

# verify_image_layout.py 结论条检测（真实代码节选，2026-09-08）
def _row_strip_ratio(px, w, y):
    tot = cnt = 0
    for x in range(0, w, 2):
        tot += 1
        if _is_strip(px[x, y]):
            cnt += 1
    return cnt / tot if tot else 0

三、为什么说技能是 onboarding：把带新人的经验搬给 agent

我们做过一个判断：给 agent 建技能，和给新人写 onboarding 是同一件事。我们团队带新人用的三件套——入职登记、岗位手册、师傅兜底——搬到 agent 身上一一对应：

入职登记 → description：先让路由知道他是谁、放哪个岗，什么任务该叫他；
岗位手册 → SKILL.md：SOP 分章、出事查得到，但平时不占桌面；
师傅 + 环境 → scripts + 门禁：真动手才出现，跑偏了有闸当场拦；
转正验收 → 回归检查：独立扛事算过，技能改动过不了门禁就不让上线。

文档等人来读，onboarding 带人走完——agent 只认后者。我们给新人写 onboarding-checklist.md 的时候想明白的：光写文档没有用，要写「先做什么、再做什么、做完怎么验证」。给 agent 的技能如果只写知识不写动作顺序和验证标准，agent 翻开了也不知道该信哪一步。

四、真正的命门：技能会腐化，防过期靠维护闭环

大厂把技能开源出来，示范的是「怎么写」；真正没人教的是「怎么养」。技能腐化（skill rot）是比写不出来更普遍的问题：模型版本升级，某个步骤的写法过时了；工具接口变了，脚本一跑就报错；踩过的坑没有回流，同样的错 agent 下周再踩一遍。

我的答案是四步维护闭环，每晚转一圈：

# 每晚 21:00 的自动进化任务（真实 cron：daily-self-evolution）
# 1. 扫当天错误 → error-ledger 入账（症状 / 根因 / 解法 / 状态）
# 2. correction_logger 提取知识 → 沉淀进技能 / SOP / 门禁
# 3. 状态置 embedded：记住不算数，写进机制才算数

第一步是「使用即 patch」：技能每次被用到，发现哪句不准、哪个步骤多余，当场补一句，不让它积成债。第二步每晚复盘，扫当天错误账本，抽共因。第三步把纠正沉淀成 SKILL.md 的新章节——我们的 error-ledger 已经 60+ 条，只增不删，每晚回灌。第四步门禁回归：技能改动跑 17 项检查，坏了当场拦下，不让腐化悄悄上线。

技能会过期，会维护的技能才保值。 一个技能包的价值不取决于第一版写得多全，取决于它被维护了多少轮。

边界也得说清楚：技能适合高频复用、验收可代码化的任务——写作规范、配图流程、复盘方法都算。一次性任务、还在探索期的任务，直接 prompt 反而省事，别为了建技能而建技能，那会变成新的知识负债。

结尾

技能包的开源潮还会继续，标准会收敛，工具会换代。真正拉开差距的，从来不是谁手里技能包多，而是谁能让技能包一直不过期。

给 agent 建技能这件事，本质上是在回答一个问题：我们希望 agent 像人一样被带教，还是像机器一样被灌参数？我的答案是前者——写 onboarding 的人，才真正理解 agent 需要什么。

此刻的你

一句话读懂：Agent Skills 不是把文档塞给 agent，而是给 agent 写 onboarding——三级披露管「怎么省上下文」，维护闭环管「怎么不过期」；技能会腐化，会维护的技能才保值。

三个认知

技能是 onboarding，不是文档：agent 不会主动读东西，只会被 description 命中后翻开 SKILL.md；写技能要写动作顺序和验收标准，不是写知识全集。
三级披露是上下文管理，不是格式规定：metadata 每轮在、SKILL.md 命中才载入、捆绑文件用到才调——上下文只装索引，不装全书。
防过期比写初版更重要：技能腐化是常态，使用即 patch、每晚复盘、错误回灌、门禁回归四步闭环，让技能包越用越准。

你应该带走的真正价值

价值一（Agent 工程化场景）：拿到一套可直接照抄的技能目录结构——SKILL.md 短入口 + references 长规范 + scripts 工具，按需载入天然省上下文，任何高频复用型技能都能这么搭。
价值二（团队/组织场景）：把给新人 onboarding 的三件套（登记/手册/兜底）平移成技能的 description/SKILL.md/scripts 三层，带教经验一次沉淀两处受益。
价值三（长期维护场景）：防过期四步闭环（使用即 patch → 每晚复盘 → 错误固化 → 门禁回归）不需要新工具，一本错误账本加一个定时任务就能转起来，回报是技能包不会越用越废。

三步行动

步骤	动作	验证
1	挑一个高频复用任务，按 metadata + SKILL.md + 捆绑文件三级建第一个技能	description 能被路由命中，SKILL.md 一屏内读完
2	技能每次被用到就顺手 patch 一次，把新踩的坑写进去	一个月后 SKILL.md 里新增至少 3 条「已知坑」
3	把技能目录接进每晚复盘 + 门禁回归	技能改动跑检查，坏版本从未上线过

金句：文档会过期，onboarding 会迭代，技能包只有被维护着，才算真的被拥有。

魏无记