Schéma du frontmatter
Guide de référence sur la structure du bloc de frontmatter YAML, les clés requises par classe et les règles d'application des validateurs pour l'ensemble des classes d'artefacts.
Référence canonique du frontmatter YAML de chaque classe d'artefact. Le résumé de la section Conventions de
CLAUDE.mdest la déclaration en ligne ; les JSON Schemas par classe soussrc/apothem/schemas/(additionalProperties: falsedans les schémas de skill et de commande rejette les clés inconnues ; les schémas d'agent, d'output-style et de plan définissentadditionalProperties: true) constituent le contrat lisible par machine et l'emportent en cas de désaccord. Cette page est l'index des clés requises, etartifact-schema.mdxporte les modèles et exemples détaillés par classe ; toutes deux sont des projections lisibles par un humain de ces schémas.
1. Forme du bloc de frontmatter
Chaque artefact porte un frontmatter YAML en tête, délimité par des lignes ---. Dans les fichiers de la famille Markdown, le frontmatter est le premier contenu du fichier, et la ligne d'en-tête SPDX canonique définie dans site/content/docs/reference/authorship-header.mdx suit le --- de fermeture.
Les clés de commande utilisent kebab-case. Les clés de skill utilisent kebab-case, à l'exception de userInvocable, orthographe camelCase employée par le corpus source (l'installation Claude Code la renomme en user-invocable). L'installation Claude Code et le plugin déplacent aussi les clés propres à Apothem (version, updated, archetype, portability) d'une skill ou d'une commande sous une table metadata: finale de chaînes entre guillemets, dans cet ordre fixe, car Claude Code ignore les clés de premier niveau inconnues et le standard Agent Skills range les extras dans metadata ; les fichiers sources et tous les autres environnements les conservent au premier niveau, à l'exception des dossiers de skills partagés de niveau utilisateur (~/.agents/skills/ et les dossiers ~/.codebuddy/skills/, ~/.kiro/skills/ et ~/.trae/skills/), qui les replient de la même manière. Les clés des règles et des travailleurs délégués sont en camelCase, comme l'indique le tableau des clés obligatoires de la section 2. Les valeurs scalaires sont soit nues, soit entre guillemets doubles ; les valeurs de chaîne contenant des deux-points, des dièses ou d'autres caractères significatifs en YAML sont mises entre guillemets.
2. Champs requis par classe
L'ensemble des clés requises varie selon la classe d'artefact. La forme qui fait autorité est appliquée par scripts/dev/validate_ecosystem.py et par les JSON Schemas par classe situés dans le répertoire src/apothem/schemas/. Les classes des auxiliaires, des skills, des commandes, des output-styles et des plans ont chacune un fichier de schéma, listé ci-dessous ; les classes CLAUDE.md et des règles n'en ont aucun, et validate_ecosystem.py vérifie leurs clés. Les fichiers de plan ne figurent pas dans le tableau ci-dessous ; leurs clés sont énumérées dans Discipline des plans.
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| Classe | Clés requises |
|---|---|
CLAUDE.md (configuration racine) | name, version, updated, description, scope, portability |
Règles (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Commandes (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
Auxiliaires, aussi appelés travailleurs délégués (src/apothem/agents/*.md) | name, version, updated, description, tools (facultatif : un auxiliaire qui l'omet hérite de tous les outils ; pour donner un serveur MCP à un auxiliaire qui liste tools, nommez le serveur dans la clé agent_mcp_servers du profil), disallowedTools, maxTurns, effort |
Skills (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools ; l'installation Claude Code et le plugin, ainsi que les dossiers de skills partagés de niveau utilisateur, renomment userInvocable en user-invocable, et le schéma exige que chaque skill porte exactement une des deux graphies, jamais les deux ; l'installation Qwen Code écrit allowed-tools sous forme de liste allowedTools, la clé et la forme que lit Qwen Code |
Output-styles (src/apothem/output-styles/*.md) | name, description ; chaque style livré définit aussi keep-coding-instructions: true afin que Claude Code conserve ses instructions d'ingénierie logicielle |
Les schémas par classe sous src/apothem/schemas/ portent l'ensemble complet des contraintes, y compris les restrictions de type, de format, d'énumération et de motif, ainsi que les limites de longueur : la description d'une skill ou d'une commande compte au plus 1 024 caractères, la limite fixée par Agent Skills.
3. Validateurs
scripts/dev/validate_ecosystem.py parcourt l'arbre des artefacts, applique les ensembles de clés requises ci-dessus et signale [FAIL] pour tout artefact auquel manque un champ requis. Le frontmatter-grep appliqué à chaque écriture, situé dans src/apothem/conformity/frontmatter_grep.py, impose la même forme aux points d'interception du hook PreToolUse Write/Edit.
Conventions de nommage
Prescrit les noms de fichiers en kebab-case, le format des clés de frontmatter, le nommage des branches avec préfixes de type et la sémantique des préfixes numériques pour les séquences d'artefacts ordonnées.
Conventions Markdown
Normaliser la variante Markdown, la structure des titres, la déclaration des blocs de code, le format des liens internes, les en-têtes de paternité et leur application par les validateurs.