Skill Schema V2

"把 Agent Skill 从提示词文件，升级成可路由、可治理、可复用的能力契约。"

Skill Schema V2 是一套 Agent Skill 设计、审计和重构规范，用来判断一个 Skill 是否真正适合长期复用：能不能被正确路由，边界是否清楚，输出是否可验证，运行时是否足够轻，安全与交接是否有明确规则。

快速开始 · 编码说明 · 它解决什么 · 核心模型 · 能力范围 · 论文来源 · 目录结构 · English

---

快速开始

把 skill-schema-v2.skill/ 安装或复制到你的 Agent / Codex skills 目录中。

skill-schema-v2.skill/
├── SKILL.md
├── docs/
│   ├── audit-rubric.md
│   ├── repair-playbook.md
│   └── v2-design-spec.md
└── examples/
    └── v2-audit-report.md

在 Codex 中，它应该被放到类似下面的位置：

~/.codex/skills/skill-schema-v2/

加载条件：

description: "Load when creating, auditing, refactoring, or repairing an Agent Skill for reuse, governance, and runtime efficiency."

---

编码说明

仓库文档和 skill-schema-v2.skill/ 包内文件均使用 UTF-8。Windows PowerShell 在某些终端或管道配置下可能把中文显示成 鎶、鈥、涓 一类乱码；这通常是显示解码问题，不代表文件内容损坏。

验证文件内容时优先使用 UTF-8 读取工具，例如：

rg -n "把|快速开始|you are" .

或使用 Node / Python 按 UTF-8 读取文件。不要在未确认原始字节前对文档做批量转码。

---

它解决什么

很多 Skill 一开始只是一次对话里的经验沉淀，后来被复制到仓库、团队、不同 Harness 中复用，问题就会暴露出来：

常见问题	真实后果
description 写成介绍，不是触发器	Agent 不知道什么时候该加载
SKILL.md 越写越大	上下文浪费，模型抓不到重点
没有输入/输出契约	结果无法验收，只能靠感觉判断
权限和人工确认点不清楚	外发、删除、部署、承诺类操作容易越界
docs/examples/scripts 没有索引	Skill 离开原项目后不可复用
persona 和 scope 混在一起	Skill 变成隐性系统提示，污染其他任务

Skill Schema V2 的目标不是把 Skill 写得更复杂，而是把复杂度放到正确位置：入口要短，契约要清楚，运行时资源要按需加载。

---

核心模型

V2 把一个成熟 Skill 拆成三个表面：

Routing Surface
  name + description + frontmatter
  决定 Agent 什么时候加载它。

Contract Surface
  goal + inputs + permissions + evidence + output + verification + handoff
  决定什么叫做完成，什么叫做越界。

Runtime Boundary Surface
  docs + examples + scripts + operators + fallback paths
  决定加载哪些细节，执行哪些工具，失败后怎么退回。

一句话：

Skill = 可路由的任务契约 + 最小运行时边界

这三个表面必须自洽。description 路由的任务，必须被正文契约治理；正文承诺的能力，必须被 docs/、examples/、scripts/ 或明确的 fallback 支撑。

---

能力范围

Skill Schema V2 可以用于：

• 创建新的 Agent Skill
• 审计已有 SKILL.md
• 拆分膨胀的单文件 Skill
• 重写 description 路由触发器
• 补齐目标、输入、权限、证据、输出、验证、交接规则
• 清理模型已知内容和流程表演
• 建立 docs/、examples/、scripts/ 的按需加载结构
• 检查 hardcoded secrets、safety bypass、persona override、scope conflict
• 把 Skill 改造成更适合跨 Harness 复用的能力包

审计评分维度：

维度	分值	关注点
Routing	15	是否能被正确发现和加载
Contract	20	是否有目标、输入、输出、验证和边界
Runtime Boundary	15	是否按需加载资源，避免无关上下文注入
Reusability	15	是否能离开原项目继续复用
Safety	15	是否有权限、人类确认点和安全边界
Signal Density	10	是否删除模型已知内容和空流程
Versioning	5	是否有 SemVer 和更新时间
Self-Consistency	5	入口、正文、资源、脚本是否互相矛盾

---

论文来源

V2 不再只基于 Perplexity 与 Karpathy 的早期理念，而是融合了 2026 年 5 月后关于 Agent Skill 的多篇研究。