信号

宝玉今天讨论 baoyu-skills 里的一个设计取舍：过去用 EXTEND.md 保存用户自定义设置，优点是 Agent 直接读起来方便；问题是 Markdown 对程序不友好，格式不稳定。后续如果要被 CLI、registry、审计器、安装器解析，就会变成隐性技术债。

这件事看起来是在讨论 Markdown、YAML、JSON 的格式选择，本质其实是一个更大的变化：

Skill 正在从“给模型看的提示词文件”，变成 Agent Runtime 里的能力资产。

Skill 从一张提示词文件，逐步变成 Agent Runtime 可以发现、安装和治理的能力资产。
Skill 不再只是写给模型读的说明，而开始成为系统可以管理的能力单元。

判断

最权威的官方说法不是“在 Skill 里写 JSON”。

Anthropic 和 OpenAI Codex 当前的基础定义都很清楚：一个 Skill 通常是一个目录，里面必须有 SKILL.md。SKILL.md 开头用 YAML frontmatter 写 name、description 等基础 metadata，正文用 Markdown 写 Agent 需要遵循的操作说明。

所以准确理解应该是：

Markdown 是 Agent 的上下文界面；YAML frontmatter 是系统发现 Skill 的基础 metadata；更复杂的 JSON/YAML Contract 是平台治理层的扩展，而不是当前官方 Skill 的必需形态。

也就是说，今天的标准解决的是：

  • Agent 如何发现 Skill；
  • Agent 什么时候加载 Skill；
  • Agent 如何读取 Skill 的说明；
  • Skill 如何被打包成可复用能力。

但如果 Skill 要进入组织、团队、市场和生产环境，仅有 SKILL.md 还不够。

因为平台还需要知道：

  • 这个 Skill 是谁发布的；
  • 适合什么场景；
  • 需要哪些工具和权限；
  • 是否会访问文件、网络、代码、邮箱、日历；
  • 依赖哪些脚本和环境；
  • 版本升级是否兼容；
  • 有没有最小 eval；
  • 历史运行是否可靠；
  • 失败模式是什么；
  • 安全风险等级是多少。

这就是 Skill Trust Layer。

Skill Trust Layer 需要记录发布者、场景、工具权限、依赖、版本、eval、失败模式和安全风险。
当 Skill 要进入组织和市场，说明书之外必须有可信层。

方法

可以把 Skill 拆成三层理解。

第一层：SKILL.md

给人和 Agent 看的说明书。它解释这个 Skill 做什么、什么时候用、怎么做、有哪些步骤和注意事项。

第二层：Metadata / Manifest

给系统看的结构化信息。早期可以放在 SKILL.md 的 YAML frontmatter 里；后期如果要做 marketplace、registry、权限、审计、安装器，就可以演进成独立的 skill.yaml 或 skill.json。

第三层：Eval / Run Ledger

给组织和市场看的可信记录。它证明这个 Skill 是否真的可靠，是否在真实任务里跑通过，失败率是多少，风险在哪里。

Skill 可以拆成 SKILL.md、Metadata Manifest、Eval Run Ledger 三层。
Markdown 负责让 Agent 理解，Manifest 负责让系统管理，Ledger 负责让组织信任。

行动

不要把 Skill 市场做成“提示词收藏夹”。

真正有价值的不是收集更多 Markdown，而是让每个 Skill 都能被发现、被安装、被审计、被评估、被版本管理。

短期可以继续允许创作者只写 SKILL.md，降低发布门槛：

my-skill/
└── SKILL.md

中期应该让平台自动从 SKILL.md 里抽取或生成 Manifest：

name:
description:
version:
owner:
tools:
permissions:
dependencies:
compatibility:
risk_level:

长期进入组织空间或 marketplace 前，必须补齐：

inputs:
outputs:
evals:
failure_modes:
usage_logs:
security_review:

这样用户安装的就不是一段提示词，而是一个可治理、可审计、可复现的 Agent 能力资产。

Skill 从 SKILL.md 演进到 Manifest，再演进到包含 eval、usage logs 和 security review 的 Skill Contract。
Skill 市场的终局，不是更多提示词，而是可治理的能力合约。

一句话总结

官方 Skill 的基础形态是 SKILL.md + YAML frontmatter，不是 JSON；但 Fat Skills 的未来，一定不是更多 Markdown，而是可治理的 Skill Contract。