Frontmatter-Schema
Referenzleitfaden zur Struktur des YAML-Frontmatter-Blocks, zu den Pflichtschlüsseln pro Klasse und zu den Durchsetzungsregeln der Validatoren über alle Artefaktklassen hinweg.
Kanonische Referenz für YAML-Frontmatter in jeder Artefaktklasse. Die Zusammenfassung unter „Conventions“ in
CLAUDE.mdist die Inline-Deklaration; die JSON-Schemas pro Klasse untersrc/apothem/schemas/(additionalProperties: falsein den Schemas für Skills und Befehle lehnt unbekannte Schlüssel ab; die Schemas für Agenten, Output-Styles und Pläne setzenadditionalProperties: true) sind der maschinenlesbare Vertrag und haben bei jeder Abweichung Vorrang. Diese Seite ist der Index der Pflichtschlüssel;artifact-schema.mdxenthält die Vorlagen und ausgearbeiteten Beispiele pro Klasse. Beide sind menschenlesbare Projektionen dieser Schemas.
1. Struktur des Frontmatter-Blocks
Jedes Artefakt trägt am Kopf YAML-Frontmatter, begrenzt durch ----Zeilen. Bei Dateien der Markdown-Familie ist das Frontmatter der erste Inhalt der Datei, und die kanonische SPDX-Header-Zeile gemäß site/content/docs/reference/authorship-header.mdx folgt auf das schließende ---.
Befehlsschlüssel verwenden kebab-case. Skill-Schlüssel verwenden kebab-case, mit Ausnahme von userInvocable, der camelCase-Schreibweise des Quell-Korpus (die Installation für Claude Code benennt sie in user-invocable um). Die Installation und das Plugin für Claude Code verschieben außerdem die nur für Apothem bestimmten Schlüssel (version, updated, archetype, portability) eines Skills oder Befehls unter eine abschließende metadata:-Map aus Zeichenketten in Anführungszeichen, in dieser festen Reihenfolge, weil Claude Code unbekannte Schlüssel auf oberster Ebene ignoriert und der Agent-Skills-Standard zusätzliche Schlüssel in metadata ablegt; die Quelldateien und jeder andere Harness behalten sie auf oberster Ebene, mit Ausnahme der gemeinsam genutzten Skill-Ordner auf Benutzerebene (~/.agents/skills/ sowie die Ordner ~/.codebuddy/skills/, ~/.kiro/skills/ und ~/.trae/skills/), die sie auf dieselbe Weise einfalten. Schlüssel für Regeln und delegierte Worker sind camelCase, wie die Tabelle der Pflichtschlüssel in Abschnitt 2 auflistet. Skalare Werte stehen entweder ohne Anführungszeichen oder in doppelten Anführungszeichen; Zeichenkettenwerte, die Doppelpunkte, Rautezeichen oder andere in YAML bedeutsame Zeichen enthalten, werden in Anführungszeichen gesetzt.
2. Pflichtfelder pro Klasse
Die Menge der Pflichtschlüssel variiert je nach Artefaktklasse. Die maßgebliche Struktur wird von scripts/dev/validate_ecosystem.py und den JSON-Schemas pro Klasse im Verzeichnis src/apothem/schemas/ durchgesetzt. Die Klassen Helfer, Skill, Command, Output-Style und Plan haben jeweils eine Schemadatei, unten aufgelistet; die Klassen CLAUDE.md und Regel haben keine, und validate_ecosystem.py prüft ihre Schlüssel. Plan-Dateien stehen nicht in der Tabelle unten; ihre Schlüssel sind unter Plan-Disziplin aufgeführt.
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| Klasse | Pflichtschlüssel |
|---|---|
CLAUDE.md (Wurzelkonfiguration) | name, version, updated, description, scope, portability |
Regeln (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Commands (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
Helfer, auch delegierte Worker genannt (src/apothem/agents/*.md) | name, version, updated, description, tools (optional: Ein Helfer, der ihn weglässt, erbt jedes Werkzeug; um einem Helfer, der tools auflistet, einen MCP-Server zu geben, nennen Sie den Server im Profilschlüssel agent_mcp_servers), disallowedTools, maxTurns, effort |
Skills (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools; die Claude Code-Installation und das Plugin sowie die gemeinsam genutzten Skill-Ordner auf Benutzerebene benennen userInvocable in user-invocable um, und das Schema verlangt, dass jeder Skill genau eine der beiden Schreibweisen trägt, niemals beide; die Qwen Code-Installation schreibt allowed-tools als allowedTools-Liste, den Schlüssel und die Form, die Qwen Code liest |
Output-Styles (src/apothem/output-styles/*.md) | name, description; jeder ausgelieferte Stil setzt außerdem keep-coding-instructions: true, damit Claude Code seine Anweisungen für Software-Engineering beibehält |
Die Schemas pro Klasse unter src/apothem/schemas/ enthalten den vollständigen Satz an Einschränkungen, einschließlich Typ-, Format-, Enum- und Musterrestriktionen, sowie Längenbegrenzungen: Die description eines Skills oder Commands umfasst höchstens 1.024 Zeichen, die Grenze der Agent Skills.
3. Validatoren
scripts/dev/validate_ecosystem.py durchläuft den Artefaktbaum, wendet die obigen Mengen an Pflichtschlüsseln an und meldet [FAIL] für jedes Artefakt, dem ein Pflichtfeld fehlt. Der bei jedem Schreibvorgang laufende frontmatter-grep in src/apothem/conformity/frontmatter_grep.py setzt dieselbe Struktur an den Grenzen der PreToolUse-Hooks für Write/Edit durch.
Namenskonventionen
Schreibt kebab-case-Dateinamen, das Frontmatter-Schlüsselformat, die Branch-Benennung mit Typ-Präfixen und die Semantik numerischer Präfixe für geordnete Artefaktsequenzen vor.
Markdown-Konventionen
Markdown-Variante, Überschriftenstruktur, Sprachdeklarationen von Codeblöcken, Formate interner Links, Autorschafts-Header und die Durchsetzung durch Validatoren vereinheitlichen.