Frontmatter 模式
YAML frontmatter 块结构、逐类必需键，以及各制品类别校验器强制规则的参考指南。
每个制品类别上 YAML frontmatter 的规范参考。
CLAUDE.md的 Conventions 部分中的摘要是内联声明；src/apothem/schemas/下的逐类 JSON Schema（skill 和 command 的 schema 中additionalProperties: false会拒绝未知键；agent、输出样式与 plan 的 schema 设置了additionalProperties: true）是机器可读的契约，出现任何不一致时以其为准。本页是必需键索引，而artifact-schema.mdx承载逐类的模板与完整示例——两者都是这些 schema 的人类可读投影。
1. Frontmatter 块形态
每个制品都在头部带有 YAML frontmatter，由 --- 行分隔。在 Markdown 系列文件上，frontmatter 是文件的第一项内容，而按照 site/content/docs/reference/authorship-header.mdx 的规范 SPDX 头部行紧随闭合的 --- 之后。
命令键使用 kebab-case。技能键使用 kebab-case，但 userInvocable 除外；它是源语料库所用的 camelCase 拼写（Claude Code 安装时会将其重命名为 user-invocable）。Claude Code 安装和插件还会把技能或命令中仅 Apothem 使用的键（version、updated、archetype、portability）移入末尾一个由带引号字符串组成的 metadata: 映射，并按这一固定顺序排列，因为 Claude Code 会忽略未知的顶层键，而 Agent Skills 标准把额外的键放在 metadata 中；源文件和其他所有工具都把这些键保留在顶层，但共享的用户级技能文件夹（~/.agents/skills/ 以及 ~/.codebuddy/skills/、~/.kiro/skills/ 和 ~/.trae/skills/ 文件夹）除外，它们以同样的方式折叠这些键。规则与委派工作者的键使用 camelCase，如第 2 节的必需键表所列。标量值可以不加引号，也可以使用双引号；包含冒号、井号或其他对 YAML 有特殊含义字符的字符串值需要加引号。
2. 逐类必需字段
必需键集合因制品类别而异。权威形态由 scripts/dev/validate_ecosystem.py 和 src/apothem/schemas/ 目录下的逐类 JSON Schema 强制执行。辅助器、技能、命令、输出样式和计划这几个类别各有一个 schema 文件，列于下方；CLAUDE.md 和规则这两个类别没有 schema 文件，其键由 validate_ecosystem.py 检查。计划文件不在下表中；它们的键列于计划纪律。
src/apothem/schemas/agent.schema.json
src/apothem/schemas/skill.schema.json
src/apothem/schemas/command.schema.json
src/apothem/schemas/output-style.schema.json
src/apothem/schemas/plan.schema.json| 类别 | 必需键 |
|---|---|
CLAUDE.md（根配置） | name、version、updated、description、scope、portability |
规则（src/apothem/rules/*.md） | name、description、pathFilter、alwaysApply |
命令（src/apothem/commands/*.md） | name、version、updated、description、argument-hint、disable-model-invocation、portability、allowed-tools |
辅助器，也称为委派工作者（src/apothem/agents/*.md） | name、version、updated、description、tools（可选：省略它的辅助器会继承所有工具；若要为列出了 tools 的辅助器提供某个 MCP 服务器，请在配置档案的 agent_mcp_servers 键中指明该服务器）、disallowedTools、maxTurns、effort |
技能（src/apothem/skills/*/SKILL.md） | name、version、updated、description、archetype、userInvocable、disable-model-invocation、allowed-tools；Claude Code 安装和插件以及共享的用户级技能文件夹会将 userInvocable 重命名为 user-invocable，并且 schema 要求每个技能恰好带有这两种拼写中的一种，绝不能同时带有两种；Qwen Code 安装会把 allowed-tools 写成一个 allowedTools 列表，这是 Qwen Code 读取的键与形态 |
输出样式（src/apothem/output-styles/*.md） | name、description；每个随附样式还会设置 keep-coding-instructions: true，以便 Claude Code 保留其软件工程指令 |
src/apothem/schemas/ 下的逐类 schema 承载完整的约束集，包括类型、格式、枚举和模式限制，以及长度限制：技能或命令的 description 最多 1,024 个字符，即 Agent Skills 的限制。
3. 校验器
scripts/dev/validate_ecosystem.py 遍历制品树，应用上述必需键集合，并对任何缺少必需字段的制品报告 [FAIL]。位于 src/apothem/conformity/frontmatter_grep.py 的逐次写入 frontmatter-grep 在 PreToolUse Write/Edit 钩子边界处强制执行相同的形态。