metadata 字段metadata字段是SKILL.md中的**"万能收纳箱"**：当其他5个标准字段（name、description、license、compatibility、allowed-tools）装不下你的信息时，所有额外内容统统往这里塞。
metadata是什么metadata是一个可选的键值对映射（map），用于存储任意自定义的元数据。它的本质是给Skill的开发者、维护者、分发平台提供一个自由扩展的信息空间。例如：
metadata:
author: example-org
version: "1.0"
category: data-processing
tags: "csv, analysis, charts"
| 维度 | 说明 |
|---|---|
| 是否必填 | 可选 |
| 数据类型 | 键值对映射（map），键和值都必须是字符串 |
| 长度限制 | 无明确限制 |
| Agent执行时是否使用 | 不使用，Agent不会读取metadata中的内容来指导执行 |
metadataSKILL.md的frontmatter只允许出现6个标准字段：
name、
description、
license、
compatibility、
metadata、
allowed-tools。
任何未定义的字段都会导致验证失败：
# ❌ 错误！"author" 不是标准字段，验证会报错
name: my-skill
description: My skill description
author: John # 不允许！
version: 1.0 # 不允许！
# ✅ 正确做法：把额外信息放进 metadata
name: my-skill
description: My skill description
metadata:
author: John
version: "1.0"
不同的Agent平台（Claude Code、Codex CLI、Gemini CLI、Cursor等）可能需要读取不同的自定义属性。metadata提供了一个标准化的"扩展插槽"，各平台可以从中提取自己需要的信息：
Agent 平台 A 可能读取 → metadata.category 用于分类展示
Agent 平台 B 可能读取 → metadata.tags 用于搜索索引
Skill 市场可能读取 → metadata.author 用于展示作者信息
对于团队协作、开源分发等场景，metadata可以记录版本、作者、分类等管理信息，方便后续维护和检索。
metadata 的实战技巧键名应该直观反映信息的含义，避免使用缩写或含糊的名称：
# ❌ 含糊的键名
metadata:
a: John
v: "1.0"
t: "csv, analysis"
# ✅ 语义清晰的键名
metadata:
author: John
version: "1.0"
tags: "csv, analysis"
官方建议使用独特的键名，避免不同平台或工具之间的键名冲突。如果你的Skill是为特定平台定制的，可以加上平台前缀：
metadata:
# 通用信息
author: example-org
version: "1.0"
# 平台特定信息，加前缀避免冲突
claude-code-category: data-processing
codex-cli-priority: high
规范要求键和值都必须是字符串。即使是数字、布尔值，也要用引号包裹：
# ❌ 错误：version 是数字类型，tags 是数组类型
metadata:
version: 1.0
tags: [csv, analysis, charts]
# ✅ 正确：所有值都是字符串
metadata:
version: "1.0"
tags: "csv, analysis, charts"
metadata是可选的，不是每个Skill都需要。以下场景建议填写：
| 场景 | 建议填写的键 |
|---|---|
| 开源分发 | author、version、repository |
| 团队协作 | maintainer、last-updated、review-status |
| 平台分类 | category、tags |
| 版本管理 | version、changelog |
