为什么散文技能总靠不住?SKILL.md 与 SkillSpec 结构化契约的完整对比
为什么散文技能总靠不住?SKILL.md 与 SkillSpec 结构化契约的完整对比
如果你用 SKILL.md 给 AI Agent 写过技能,大概率遇到过这种场景:规则写得很认真,Agent 却"阳奉阴违"——跳过靠后的安全规则、擅自换工具、最后还报一句"已完成"。SkillSpec 就是为了解决这个问题而生的开源工具:它把 SKILL.md 里靠不住的散文行为,变成一个可校验、可测试、可证明的结构化契约 skill.spec.yml,并附带 Doctor 风险报告和运行对齐证明。
这篇文章面向新手,完整对比"纯散文技能"和"SkillSpec 结构化契约"两种写法:为什么散文会失守、SkillSpec 怎么补救、以及你的技能该不该迁移。
一、先搞清楚:SKILL.md 为什么"写得好 ≠ 执行得好"
Agent 技能(Agent Skill)的基本形态很简单:一个目录 + 一个 SKILL.md 文件。启动时 Agent 只加载每个技能的名称和描述(用于发现),任务匹配时才加载完整正文。这个设计本身是聪明的,但它有一个致命前提——
技能一旦激活,正文就只是一段提示词(prompt),模型可以忽略它、部分遵守它,或者乱序执行它。
SkillSpec 团队在研究文档 docs/overview/00-skills-reliability-gap.md 中系统归纳了散文技能的失败模式,其中最常见的三个是:
1. 靠后的规则会被静默跳过 🎯
研究表明,模型对长上下文中开头和结尾的指令最敏感,中间部分极易丢失(即 "Lost in the Middle" 效应)。更扎心的是实测数据:前沿模型在同时面对 500 条指令时,遵循率只有约 68%。
一个部署技能列出 5 个步骤,模型可能悄悄丢掉第 3 步"打版本标签"——当时不报错,直到某天发现发布包没有 tag 才追根溯源,而运行记录里根本查不到这一步没执行过。
2. 每次失败都会让散文更长,形成恶性循环 🔄
每次发现 Agent 犯错,维护者的本能反应是再加一段话强调。结果正文越写越长,下一次跳过规则的概率反而更高。就像给不听话的模型写越来越长的家规,但家规本身没有任何约束力。
3. 你只能看到最终答案,看不到过程 🕵️
技能运行结束后没有持久记录:选了哪条路线、执行了哪些步骤、跳过了什么,全靠"感觉没问题"。没有记录,就没有可审计性。
二、SkillSpec 的解法:散文归散文,契约归契约
SkillSpec 的核心主张一句话概括(出自 docs/overview/01-why-skillspec.md):
Keep the prose. Structure the decisions.(保留散文,把决策结构化。)
它不是要用 YAML 替换你的 SKILL.md,而是在 SKILL.md 旁边放一个小文件 skill.spec.yml,把"必须被检查的行为"从段落里搬进类型化字段:
| 散文里的写法 | 契约里的写法 |
|---|---|
| "浏览任务用浏览器自动化"(建议性语句) | routes + rules 明确选择 browser 路线 |
| "永远不要拿搜索当答案"(容易被忽略) | forbid: native_search_as_answer(可测试的硬约束) |
依赖关系靠示例暗示(gh: command not found 现场翻车) |
dependencies 显式声明,skillspec deps check 执行前检查 |
| 用户提问靠开放式追问 | elicitations 限定选项,问法有边界 |
| 测试基本不存在 | tests 场景测试,CI 里能跑、能失败 |
| 无决策轨迹 | trace 记录匹配的规则和选中的路线 |
完整字段清单可以参考 spec/README.md,配套的 JSON Schema 在 spec/skill.spec.schema.json。
三、真实案例对比:同一个浏览器技能,两种写法
项目内置了一个绝佳的对照示例 examples/before-after/。改造前的纯散文技能 examples/before-after/SKILL.before.md 只有几行:
# Browser Research
If the user asks to browse, open, click, snapshot, inspect, or extract from a page, use browser automation.
Never replace a browser task with a native web search summary.
写得没毛病,对吧?但维护者无法运行任何命令来证明"never"规则仍然存在;审查者无法看出一个字段拼写错误是否让规则失效;CI 无法为典型输入证明预期行为。
改造后,行为契约搬进 examples/before-after/skill.spec.yml,SKILL.md 变成一个指向契约的"薄加载器"。关键变化是:路线决策和禁止替代项变成了可测试的。
SkillSpec 的演示文档 docs/examples/why-skillspec-demo/README.md 给出了一个"点石成金"的瞬间:把规则里的字段 prefer 拼错成 preferr,运行 skillspec validate 会直接报错。而在散文版本里,同样的拼写错误会静默地让规则失效——没有任何人会注意到。
一句话总结这个对比:
Prose-only skill says the rule. SkillSpec-backed skill proves the rule.(散文技能只是"说出"规则,SkillSpec 技能能"证明"规则。)
两种写法的完整对照表 📊
项目文档 docs/overview/02-prose-vs-skillspec.md 的对比浓缩如下:
| 关注点 | 纯散文技能 | SkillSpec 契约技能 |
|---|---|---|
| 语气与领域背景 | 自然易读 | 仍保留在散文资源中 |
| 路由决策 | 藏在段落里 | 显式 routes 和 rules |
| 禁止的替代行为 | 容易被忽略 | 显式 forbid 条目 |
| 用户提问 | 开放式 | 带选项的 elicitations |
| 依赖 | 靠示例暗示 | 显式声明、可检查 |
| 测试 | 通常没有 | spec 内场景测试 |
| 决策轨迹 | 缺失或各平台私有 | 声明式 trace 要求 |
| 移植性 | 依赖模型对提示词的理解 | 编译器生成各平台加载器 |
| 代码审查 | 人工通读全文 | 审查 schema、测试与 diff |
四、第一步不用改技能:先跑 Doctor 风险报告 🩺
不确定自己的技能靠不靠谱?SkillSpec 提供一条命令的体检报告,不需要任何前置改造:
skillspec doctor ./my-skill
输出示例(来自 README.md):
SkillSpec Doctor
================
Target: ./my-skill Shape: simple_skill
Agent follow-through risk: HIGH (74/100)
Findings
- description is short and generic -> automatic discovery may be unreliable
- active skill load is 8,482 tokens -> above the balanced target
- 14 must/never obligations appear after 60% of the body -> easy to miss
- tools and commands are used, but dependencies are never declared
- no tests and no progress/trace surface -> "done" can't be checked
Likely consequence
An agent may follow the broad task but skip a late safety gate, use an
undeclared tool, or claim completion without evidence.
74/100 的 HIGH 风险,逐条列出"哪些义务藏在正文 60% 之后"、"哪些依赖没声明",并给出可能的后果。报告里每一条风险条件都引用了已发表的 Agent 失败研究或项目自身的评估方法论(详见 docs/design/operations/22-doctor-agent-drift-risk.md),不是凭感觉打分。
五、三步迁移:评估 → 移植 → 证明
决定迁移后,SkillSpec 的工作流也很轻(完整命令参考见 docs/design/operations/16-command-log.md):
- Assess(评估):
skillspec doctor ./my-skill,拿到风险基线; - Port(移植):一条命令把散文技能导入契约,生成
skill.spec.yml,同时编译出薄加载器,让运行时 prompt 保持精简:
skillspec port-one-shot path/to/SKILL.md --out ./draft --target codex-skill --prove
导入器刻意保守:保留原始素材、提取明显结构、把不确定的部分标记为 review_required 待人工确认,而不是瞎猜。
- Prove(证明):每次运行都可以产出一份对齐摘要——选中的路线、完成的步骤、缺失的证据、禁止动作状态、token 用量。不是"done"两个字,而是一份可审计的记录。对齐判定是诚实的三值:
aligned(对齐)/partial(部分)/unproven(证据不足,不推断成功)。方法论细节见 docs/overview/08-contract-trace-methodology.md。
上手前建议先装 CLI:
cargo install skillspec
skillspec --version
六、什么时候还不需要 SkillSpec?✅
诚实地说,散文技能在以下场景完全够用(依据 docs/overview/02-prose-vs-skillspec.md):
- 技能是个人自用、低风险的;
- 内容主要是语气说明或领域解释;
- 没有关键依赖、路线选择或安全决策;
- 不需要跨 Agent 平台移植。
而满足以下任意一条时,SkillSpec 就值得投入:
- 技能要公开分享或跨团队复用;
- 技能需要在多个平台(Codex、Claude、Agents)加载出一致行为;
- 技能会在多个工具/路线间做选择,错误的替代会很贵;
- 依赖或凭据需要被审查;
- 用户需要一条"Agent 为什么走了这条路"的审计轨迹。
七、常见疑问(FAQ)❓
SkillSpec 是一个新的 Agent 运行时吗? 不是。它就是一个 CLI + 一个与 SKILL.md 并排的小文件。不换运行时、不上编排平台。
它是安全沙箱吗?
不是。SkillSpec 让运行可审计——你能看到 Agent 声明做了什么、对照契约核查。工具边界的强制拦截仍然是宿主(harness)的职责。项目还单独提供了 skillspec boundary 命令来分析技能"能触达什么"(网络主机、文件路径、二进制),并编译成最小权限策略,详见 docs/boundary-guide.md。
改造后散文还有用吗?
有用,而且被刻意保留。resources 字段会把原始散文作为出处保存下来,散文继续承担语气、判断和示例,结构化契约只承担"必须被证明的部分"。
八、总结:希望 vs 契约 🧭
回到开头的场景。散文技能本质上是在希望模型读对了、记牢了、执行了;而 SkillSpec 把希望变成了检查:
| 纯散文 SKILL.md | SkillSpec 结构化契约 | |
|---|---|---|
| 规则的效力 | 模型的自觉 | 校验器 + 测试 + 轨迹 |
| 拼写/字段错误 | 静默失效 | validate 直接报错 |
| "完成"的含义 | 一句 "done" | 对齐摘要 + 证据缺口 |
| 审查方式 | 通读全文 | 看 schema、测试、diff |
如果你想动手试试,最快的路径是:cargo install skillspec → 对你的技能跑 skillspec doctor → 阅读风险报告 → 用 port-one-shot 生成契约 → 跑 skillspec test 看场景测试通过。更复杂的技能可以直接让 Agent 帮你执行:/skillspec import ./my-skill, compile it, test it, install it, and print the alignment summary。
深入阅读推荐:docs/overview/ 下的完整系列(可靠性缺口、为什么需要契约、散文对比)、spec/ 下的完整语法参考、以及 examples/ 下的更多真实技能对照示例。