Frontmatter 元数据分层策略
本策略用于区分 Claude Code Skill 的通用加载字段和项目发布字段，避免把个人或项目默认配置误写成所有 Skill 都必须遵守的通用规范。
1. 通用最小 Frontmatter
普通 Skill 只要求两个字段：
---
name: skill-name
description: 本技能应在用户需要...时使用。不要用于：...
---name：技能唯一名称，使用小写字母和连字符description：触发指纹，说明功能、触发场景和不触发场景
缺少 name 或 description 是严重问题。
2. 发布字段
以下字段属于项目发布策略，不是普通 Skill 的通用硬要求：
versionlicenseauthorhomepagesource
审查规则：
- 普通 Skill 缺少这些字段，不应判为问题
- 如果字段存在，应检查格式和一致性
- 如果项目规则、Marketplace 或发布平台明确要求这些字段，再按该项目规则审查
- 不应在通用模板中硬编码个人作者、个人主页或特定仓库地址
3. 个人 / 项目默认值
个人或项目默认值应来自外部规则，而不是写入通用 Skill 模板。
可接受来源：
- 项目级
AGENTS.md - 项目 README 或发布规范
- Marketplace 清单
- 本地个人规则文件，例如从
config/review-profile.example.yaml复制得到的config/review-profile.local.yaml - 用户当轮明确指定的发布配置
本地个人规则文件只作为审查上下文，不应写入公开仓库。
4. 可复用配置模板
config/review-profile.example.yaml 提供可复制的审查配置结构：
frontmatter.minimal_required：普通 Skill 的通用必需字段frontmatter.publishing_fields：项目发布字段及默认来源frontmatter.third_party_review：审查他人 Skill 时如何处理发布字段缺失privacy：公开文件去具体化规则severity：问题严重程度映射report：报告是否暴露本地配置值
使用方式：
- 复制
config/review-profile.example.yaml为config/review-profile.local.yaml - 在 local 文件中填写个人或项目默认值
- 审查时把 local 文件作为本地上下文
- 不提交 local 文件
5. legal-skills 项目特例
在本仓库中，version、license、author、homepage 可以作为发布字段维护，因为项目规范要求公开 Skill 支持 ClawHub、README 与其他实际启用渠道的索引同步。
但这只是本仓库的发布策略，不应被 skill-lint 当成所有 Skill 的通用要求。
不同加载器对扩展字段的位置要求可能不同：项目允许时可使用顶层 version；要求官方 Codex 兼容时，将版本写为 metadata.version。稳定性合同把两种写法归一为同一个 skill.version；若两处同时存在，值必须一致，否则按身份歧义阻断。
---
name: skill-name
description: 本技能应在用户需要...时使用。不要用于：...
metadata:
version: "1.0.0"
---审查第三方 Skill 时：
- 不因为缺少
homepage、author、version、license直接判错 - 若这些字段明显复制了本项目个人配置，且目标不是本项目 Skill，应标为警告
- 若这些字段含真实个人信息、客户信息或不可公开地址，应按公开内容清洁度规则处理
6. 报告建议
当发现发布字段问题时，报告应区分两类：
### Frontmatter
- 通用必填字段：通过 / 不通过
- 发布字段：适用 / 不适用 / 需按项目规则补充
- 个人或项目默认值：未发现 / 疑似误写入 / 明显误写入设计理念（为什么这样要求）
frontmatter 不只是元数据，它会随 Skill 加载进入系统提示，因此字段标准化不只是整洁要求。元数据类建议在报告里要带一句话理念，可直接引用以下表述。
- frontmatter 进系统提示，是注入面：frontmatter 内容会被注入系统提示，XML 尖括号、冒充官方的命名（如 claude-/anthropic- 前缀）或非标字段都可能成为指令注入载体或被平台忽略。所以坚持"最小必需字段"、references 不携带 frontmatter、术语统一、第三人称。对应"通用最小 Frontmatter""references 不携带 frontmatter"。
- 报告话术：「frontmatter 含非标字段或 XML 尖括号——这些内容会进系统提示，存在注入或失效风险。收敛为最小必需字段，references 不再带 frontmatter。」