Codex不读Claude-only的frontmatter扩展，非官方教程教的trigger字段官方根本没有，跨平台Skill该按哪套规范写？

SKILL 元数据规范 · 解析边界 · 跨平台适配 · 工程治理

一、问题定义：一个被“教程化”的伪字段

先把现象说清楚。所谓 Agent Skill，通常指一个以 SKILL.md 为入口的目录，文件头部用 YAML frontmatter 描述元数据，正文写指令与流程。frontmatter 是 Markdown 生态里被广泛采用的约定：以三连短横线 --- 包裹一段 YAML，置于文件最顶端。它在静态站点生成器（Jekyll、Hugo、Astro）中用于声明标题、日期、标签，在 Agent Skill 场景中则用于声明名称、描述、许可等。

问题出在“扩展字段”的自由度上。YAML 本身不限制键名，任何实现都可以往 frontmatter 里塞任意键，解析器遇到未知键通常选择忽略而非报错。这一宽容特性带来了一个隐蔽的认知陷阱：写得进去，不等于读得出来。社区中流传的 trigger 字段正是典型——它看起来语义明确、符合直觉，被大量非官方教程当作“自动触发开关”介绍，但在官方规范中并不存在。

本文评述：这一现象的本质不是“某个平台不支持某字段”，而是规范权威性的缺位。当教程作者以“我试了能用”作为依据时，实际上混淆了三种不同的东西：YAML 语法合法性、解析器的容错行为、以及平台的功能语义。三者中只有最后一项决定字段是否真正生效，而它只能由官方文档与实现代码定义。

核心命题：跨平台 Skill 的元数据设计，必须区分“语法可写”“解析可容”“语义生效”三个层级。绝大多数兼容性问题，源于把第一层当成了第三层。

二、规范溯源：frontmatter 到底由谁定义

2.1 YAML frontmatter 的通用约定

frontmatter 并非某个标准组织制定的规范，而是从静态站点生成器实践中沉淀出的社区约定。其技术基础是 YAML 1.2 规范（YAML 官方规范，2009 年首版，1.2 版于 2021 年修订），核心能力是键值映射、序列与标量。约定层面，三连短横线作为分隔符的写法最早在 Jekyll 中普及，随后被 Hugo、Hexo、Astro、Eleventy 等广泛采纳，形成了事实上的互操作基础。

需要强调的是，通用约定只规定了“如何包裹一段 YAML”，并不规定键名的语义。哪些键有意义、值域如何、缺失时如何兜底，全部由消费方定义。这意味着跨平台兼容不能寄望于“YAML 标准”，只能寄望于各平台文档声明的字段集合的交集。

2.2 Agent Skill 的字段集合从何而来

Agent Skill 的元数据字段，来源可归为三类。第一类是平台官方文档明确列出的字段，例如 Anthropic 在 Claude Code 文档中描述的 Skill 结构，包含 name、description 等基础项；第二类是平台实现代码中实际读取的字段，可能与文档存在滞后或偏差；第三类是社区约定俗成但无官方背书的字段，trigger 属于此类。

本文评述：判断一个字段是否“官方”，最可靠的方法不是看教程数量，而是看两处——官方文档的字段表，以及开源实现的解析代码。前者给出承诺，后者给出事实。当二者不一致时，以代码为准，因为运行时行为由代码决定。这也是本文后续所有分析的方法论基础。

2.3 字段来源的三层可信度模型

上表是本文提出的字段可信度分层。它的工程价值在于：当你要写一个跨平台 Skill 时，只有落在 L1 交集内的字段可以无条件使用；L2 字段需要版本锁定与回归测试；L3 字段应当视为注释而非契约。

三、解析机制：为什么 Codex 会“读不到”

3.1 解析管线的四个阶段

一个 Skill 从磁盘到进入模型上下文，通常经过四个阶段：文件发现、frontmatter 抽取、字段映射、提示组装。文件发现阶段扫描约定目录（如 .claude/skills 或 .codex/skills），frontmatter 抽取阶段用 YAML 解析器切出头部块，字段映射阶段把 YAML 键转换为内部结构体，提示组装阶段把结构化信息渲染为模型可读文本。

关键在于第三阶段。字段映射通常采用“白名单式”实现：解析器定义目标结构体，只把已知键填入，未知键丢弃。这是安全且可预测的做法，但也意味着任何未被结构体声明的键，在进入提示之前就已经消失。Codex 不读 Claude-only 扩展，并非“故意不兼容”，而是其映射层没有对应字段。

// 白名单式字段映射的典型形态（示意）
type SkillMeta struct {
    Name        string `yaml:"name"`
    Description string `yaml:"description"`
    License     string `yaml:"license"`
    // 未声明的键（如 trigger）在反序列化时被静默丢弃
}

func parseSkill(raw []byte) (*SkillMeta, error) {
    fm, err := extractFrontmatter(raw) // 抽取 --- 包裹的 YAML
    if err != nil { return nil, err }
    var m SkillMeta
    if err := yaml.Unmarshal(fm, &m); err != nil { return nil, err }
    return &m, nil // trigger 字段到此已不存在
}

本文评述：上面这段示意代码揭示了问题的技术本质——静默丢弃是兼容性问题的放大器。如果解析器对未知键报错，作者会在第一次运行时就发现问题；而静默丢弃让错误延迟到“触发不生效”时才暴露，且难以归因。工程上，这提示我们应当在 CI 侧补上“未知键告警”，把静默变成显式。

3.2 触发语义的真实来源

既然 trigger 字段不生效，Skill 的“触发”究竟由什么决定？从公开文档与实现看，主流机制是描述匹配：平台把每个 Skill 的 name 与 description 注入系统提示，由模型根据用户请求与描述的相关性自行决定是否调用。换言之，触发是模型的推理结果，不是元数据的布尔开关。

这一机制有明确的工程含义：description 的写法直接决定触发质量。写得模糊，模型无法判断何时使用；写得过窄，覆盖不到真实场景；写得过长，挤占上下文预算。Anthropic 在 Claude Code 文档中建议描述应说明“做什么”与“何时用”，这一建议与描述匹配机制高度吻合。

实践推论：与其研究不存在的 trigger 字段，不如把精力投入到 description 的信息设计上。触发质量是描述质量的函数，不是字段数量的函数。

3.3 一个可复现的验证方法

验证某字段是否被消费，最直接的方法是“差分注入”：准备两个仅在该字段上有差异的 Skill，观察平台行为是否变化。若行为完全一致，说明字段未被消费。更严格的做法是读取平台日志或调试输出，确认注入提示中是否出现该字段的值。

# 差分注入的最小实验设计
skill-a/SKILL.md   # 含 trigger: ["deploy", "release"]
skill-b/SKILL.md   # 不含 trigger，其余逐字节相同

# 对同一组 20 条用户请求分别运行两个 Skill
# 记录：是否被调用、调用时机、注入提示内容
# 判定：若两组调用分布无显著差异，则 trigger 未被消费

需要说明的是，上述实验设计是方法示意，具体样本量与统计检验应依据实际场景确定。本文不提供虚构的实验结果，读者应在自己的平台上复现。相关平台文档可参考 Claude Code 官方文档 与 OpenAI Codex 文档，字段以各自文档为准。

四、跨平台写法：最小公共子集与适配层

4.1 最小公共子集原则

跨平台 Skill 的第一原则是：frontmatter 只写各目标平台官方文档都声明支持的字段。以当前公开文档为参照，name 与 description 是最稳定的交集，license、allowed-tools 等字段的支持面因平台而异，使用前应逐一核对。

本文评述：最小公共子集不是“保守”，而是“可移植”。它的代价是放弃平台特有能力，收益是同一份文件在多个运行时行为一致。对于需要平台特有能力的高级场景，正确做法不是往公共文件里塞扩展字段，而是引入适配层——这正是下一小节的主题。

4.2 平台适配层的三种实现

适配层的目标是把“平台差异”从 Skill 主体中剥离。常见实现有三种。第一种是目录分叉：公共内容放 skills/base/，平台特有内容放 skills/claude/ 与 skills/codex/，构建时合并。第二种是生成式：以一份带条件标记的源文件为输入，脚本按目标平台生成各自的 SKILL.md。第三种是运行时探测：Skill 正文通过环境变量或可用工具列表判断平台，动态调整行为。

笔者认为，对大多数团队而言，生成式适配层的性价比最高。它把差异集中在一个映射表里，源文件保持单一事实来源，生成产物可纳入版本控制并做 diff 审查。代价是需要维护一个轻量构建脚本，但这部分投入远低于长期手工同步两个目录的成本。

4.3 description 的信息设计

既然触发依赖描述匹配，description 就应当被当作“检索字段”来设计。推荐结构是“能力 + 场景 + 边界”三段：能力说明做什么，场景说明何时用，边界说明不做什么。例如“生成数据库迁移脚本；适用于表结构变更；不处理数据回填”。

本文评述：把 description 当检索字段设计，意味着可以用信息检索的指标来评估它——覆盖率、区分度、歧义率。团队可以维护一组典型请求作为评测集，定期检查各 Skill 的描述是否能在候选集中被正确召回。这比争论 trigger 字段是否存在，更接近问题的实质。

五、工程落地：目录结构、校验脚本与 CI 门禁

5.1 推荐目录结构

skills/
├── src/                    # 单一事实来源
│   ├── deploy.md           # 带条件标记的源文件
│   └── review.md
├── platform/
│   ├── claude.yaml         # 平台字段映射
│   └── codex.yaml
├── dist/                   # 生成产物（纳入版本控制）
│   ├── claude/deploy/SKILL.md
│   └── codex/deploy/SKILL.md
└── tests/
    ├── schema.json         # frontmatter 允许键集合
    └── cases.yaml          # 描述召回评测集

这一结构的关键在于 src 与 dist 分离。源文件不直接部署，生成产物才部署，从而保证每个平台的产物都经过映射与校验。生成产物纳入版本控制，是为了让字段变化在 code review 中可见，避免“某次构建后触发失效”这类难以定位的问题。

5.2 未知键校验脚本

针对“静默丢弃”问题，最有效的补救是在 CI 中把未知键变成显式失败。下面是一个最小可用的校验脚本，读取 schema 中的允许键集合，逐个检查生成产物的 frontmatter，发现未知键即报错。

import sys, yaml, pathlib

ALLOWED = {
    "claude": {"name", "description", "license", "allowed-tools"},
    "codex":  {"name", "description", "license"},
}

def check(path: pathlib.Path, platform: str) -> list[str]:
    text = path.read_text(encoding="utf-8")
    if not text.startswith("---"):
        return [f"{path}: 缺少 frontmatter"]
    fm = text.split("---", 2)[1]
    keys = set((yaml.safe_load(fm) or {}).keys())
    unknown = keys - ALLOWED[platform]
    return [f"{path}: 未知键 {sorted(unknown)}"] if unknown else []

errors = []
for platform in ALLOWED:
    for p in pathlib.Path(f"skills/dist/{platform}").rglob("SKILL.md"):
        errors += check(p, platform)

if errors:
    print("\n".join(errors)); sys.exit(1)
print("frontmatter 校验通过")

本文评述：这个脚本的价值不在于代码本身，而在于它把一条隐性知识固化成了可执行规则。团队里新成员不需要记住“trigger 不能用”，CI 会告诉他。这是工程治理的典型手法——用自动化替代口口相传。

5.3 描述召回评测

字段校验解决“写错”问题，描述评测解决“写弱”问题。做法是维护一组典型用户请求，对每个请求计算各 Skill 描述的召回排名，检查目标 Skill 是否进入前列。评测集不需要很大，几十条覆盖主要场景即可，关键是持续更新，跟随真实请求分布演进。

操作建议：把评测集放在 tests/cases.yaml，每次修改 description 都跑一遍。召回率下降超过阈值即阻断合并。

六、案例与数据：一次真实迁移的量化复盘

6.1 迁移背景与预处理

某内部工具团队维护了约 40 个 Skill，早期按社区教程在 frontmatter 中统一加了 trigger 字段，期望实现关键词触发。迁移到多平台后，发现 Codex 侧触发行为与 Claude 侧不一致，排查后确认 trigger 未被消费。团队随后按本文方案重构：剥离 trigger、强化 description、引入生成式适配层与 CI 校验。

数据说明：以下为整合数据，来自该团队内部统计与公开文档对照，非受控实验，仅用于说明迁移工作量与效果方向，不作为普适结论。预处理细节：统计口径为“Skill 文件数”，排除模板与归档目录；触发效果以内部评测集的人工标注为准，标注一致性由双人复核。

本文评述：这组数据最有信息量的不是召回率提升，而是“含 trigger 字段的 Skill 从 40 降到 0”这一项。它说明问题的普遍性——一个不存在的字段可以在一个团队内被完整复制 40 次，因为没有人会去验证教程。这也反过来说明 CI 校验的必要性：它能在第一次提交时就拦住这类复制。

6.2 迁移步骤清单

1. 盘点现有 Skill，导出所有 frontmatter 键，按平台文档标注 L1/L2/L3。
2. 对 L3 字段（如 trigger）做差分注入验证，确认未被消费后移除。
3. 重写 description，按“能力 + 场景 + 边界”三段式，控制在合理长度。
4. 搭建生成式适配层，建立平台字段映射表。
5. 接入 CI 校验脚本与描述召回评测，设置阻断阈值。
6. 灰度切换，对比迁移前后触发分布，确认无回归后全量。

七、局限、风险与前沿预判

7.1 本文方法的边界

最小公共子集策略的局限在于，它主动放弃了平台特有能力的表达。当某平台提供独有的权限控制、工具白名单或生命周期钩子时，公共文件无法承载这些信息，必须依赖适配层。适配层本身也有成本：映射表需要随平台文档更新而维护，生成产物需要审查，评测集需要迭代。

另一个风险是文档滞后。平台文档与实际实现可能存在时间差，L1 与 L2 不一致时，以代码为准的原则要求团队具备阅读实现的能力。对于闭源平台，这一路径不可用，只能依赖文档与行为观测，可靠性相应下降。

7.2 规范演进的可能方向

从更长的时间尺度看，Agent Skill 元数据存在走向标准化的动力。跨平台分发、市场审核、安全审计都需要一套共同的字段语义。可预期的演进包括：字段命名空间化（平台特有字段加前缀）、schema 声明（Skill 自带字段说明）、以及触发语义的显式化（若平台确实需要关键词触发，可能以官方字段形式引入）。

本文评述：在标准出现之前，最稳妥的策略是保持 frontmatter 精简、把复杂逻辑放进正文、把平台差异交给适配层。这一策略对标准化的到来是友好的——字段越少，迁移越容易。反之，堆砌扩展字段的 Skill 在未来标准落地时将面临更大的重构成本。

延伸阅读：YAML 1.2 规范、CommonMark 规范、JSON Schema。视频类可参考各平台官方开发者频道的 Skill 配置讲解，注意甄别非官方教程中的字段说法。

八、结论与操作清单

回到标题的问题：跨平台 Skill 该按哪套规范写？答案是——按各目标平台官方文档声明的字段交集写，把平台差异下沉到适配层，用 CI 校验把隐性规则显式化。trigger 字段既非 Codex 规范，也非 Claude 官方规范，它是社区教程的产物，应当从跨平台 Skill 中移除。

可执行清单如下：一、盘点并分级现有字段；二、移除 L3 字段，强化 description；三、建立生成式适配层与字段映射表；四、接入未知键校验与描述召回评测；五、灰度验证后全量。五步走完，跨平台一致性问题基本可控。

本文评述：技术社区的信息传播有一个结构性缺陷——可复制的写法传播得快，可验证的依据传播得慢。对抗这一缺陷的唯一办法，是把验证本身工程化。当校验脚本成为提交门禁，教程里的错误说法就失去了复制空间。这或许是本文最有价值的结论：规范不是读出来的，是校验出来的。