フロントマタースキーマ
アーティファクトクラス全体にわたる、YAML フロントマターブロックの構造、クラスごとの必須キー、バリデーターによる強制ルールのリファレンスガイド。
すべてのアーティファクトクラスにおける YAML フロントマターの正規リファレンス。
CLAUDE.mdの Conventions にある要約がインラインの宣言です。src/apothem/schemas/にあるクラスごとの JSON Schema（スキルとコマンドのスキーマにあるadditionalProperties: falseは未知のキーを拒否し、エージェント、出力スタイル、プランのスキーマはadditionalProperties: trueを設定しています）が機械可読な契約であり、食い違いがある場合はこちらが優先されます。本ページは必須キーの索引であり、artifact-schema.mdxはクラスごとのテンプレートと実例を扱います。どちらも、これらのスキーマを人間が読める形にした投影です。
1. フロントマターブロックの形
すべてのアーティファクトは、先頭に --- 行で区切られた YAML フロントマターを持ちます。Markdown 系のファイルでは、フロントマターがファイルの最初の内容であり、site/content/docs/reference/authorship-header.mdx に従う正規の SPDX ヘッダー行は、閉じる --- の後に続きます。
コマンドのキーは kebab-case を使います。スキルのキーは、ソースコーパスが使う camelCase の表記である userInvocable を除き、kebab-case を使います（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/ の各フォルダー）は例外で、同じ方法で折りたたみます。ルールと委任ワーカーのキーは、セクション 2 の必須キー表に示されるとおり camelCase です。スカラー値は、引用符なしか、ダブルクォートで囲むかのどちらかです。コロン、ハッシュ記号、その他 YAML で意味を持つ文字を含む文字列値は、引用符で囲みます。
2. クラスごとの必須フィールド
必須キーのセットは、アーティファクトクラスによって異なります。権威ある形は、scripts/dev/validate_ecosystem.py と、src/apothem/schemas/ ディレクトリ配下のクラスごとの JSON Schema によって強制されます。ヘルパー、スキル、コマンド、出力スタイル、プランの各クラスにはそれぞれ 1 つのスキーマファイルがあり、下に列挙します。CLAUDE.md とルールのクラスにはスキーマファイルがなく、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 に名前変更され、スキーマは、各スキルが 2 つの綴りのうちちょうど 1 つを持つことを要求し、両方を持つことは決して認めない。Qwen Code のインストールは allowed-tools を allowedTools リストとして書き込む。これは Qwen Code が読み取るキーと形式である |
出力スタイル（src/apothem/output-styles/*.md） | name、description。出荷されるすべてのスタイルは keep-coding-instructions: true も設定しており、Claude Code がソフトウェアエンジニアリングの指示を保持するようにしている |
src/apothem/schemas/ にあるクラスごとのスキーマは、型、形式、enum、パターンの制約、および長さの制限を含む、制約の完全なセットを備えています: スキルまたはコマンドの description は最大 1,024 文字で、これは Agent Skills の上限です。
3. バリデーター
scripts/dev/validate_ecosystem.py はアーティファクトツリーを走査し、上記の必須キーのセットを適用して、必須フィールドが欠けているアーティファクトがあれば [FAIL] を報告します。src/apothem/conformity/frontmatter_grep.py にある書き込みごとの frontmatter-grep は、PreToolUse の Write/Edit フックの境界で同じ形を強制します。