为什么散文技能总靠不住?SKILL.md 与 SkillSpec 结构化契约的完整对比

原创2026-11-01 21:41:171,919 阅读

为什么散文技能总靠不住?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 在 Agent 技能栈中的层级位置,SKILL.md 负责加载,MCP 提供工具,SkillSpec 定义决策契约

二、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):

  1. Assess(评估):skillspec doctor ./my-skill,拿到风险基线;
  2. Port(移植):一条命令把散文技能导入契约,生成 skill.spec.yml,同时编译出薄加载器,让运行时 prompt 保持精简:
skillspec port-one-shot path/to/SKILL.md --out ./draft --target codex-skill --prove

导入器刻意保守:保留原始素材、提取明显结构、把不确定的部分标记为 review_required 待人工确认,而不是瞎猜。

  1. 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/ 下的更多真实技能对照示例。

登录后查看全文
skillspec