Esquema del Frontmatter
Guía de referencia para la estructura del bloque de frontmatter YAML, las claves obligatorias por clase y las reglas de aplicación del validador en las distintas clases de artefacto.
Referencia canónica del frontmatter YAML en cada clase de artefacto. El resumen en
CLAUDE.mdConvenciones es la declaración en línea; los JSON Schemas por clase enschemas/son el contrato legible por máquina; esta página es la referencia independiente que citan los colaboradores posteriores.
1. Estructura del bloque de frontmatter
Cada artefacto lleva frontmatter YAML al inicio, delimitado por líneas ---. El banner canónico de encabezado de autoría según site/content/docs/reference/authorship-header.mdx se sitúa por encima del frontmatter en los archivos de la familia Markdown; el frontmatter va inmediatamente después.
Las claves usan kebab-case. Los valores escalares van desnudos o entre comillas dobles; los valores de cadena que contienen dos puntos, almohadillas u otros caracteres significativos para YAML se entrecomillan.
2. Campos obligatorios por clase
El conjunto de claves obligatorias varía según la clase de artefacto. La estructura autoritativa la aplican scripts/dev/validate_ecosystem.py y los JSON Schemas por clase bajo el directorio schemas/ (un archivo de esquema por clase de artefacto).
schemas/agent.schema.json
schemas/skill.schema.json
schemas/command.schema.json
schemas/output-style.schema.json
schemas/plan.schema.json| Clase | Claves obligatorias |
|---|---|
CLAUDE.md (configuración raíz) | name, version, updated, description, scope, portability |
Reglas (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Comandos (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation |
| Asistentes (directorio canónico mostrado abajo) | name, version, updated, description, tools, disallowedTools, maxTurns, effort |
Habilidades (src/apothem/skills/*/SKILL.md) | name, description, archetype, userInvocable |
Los esquemas por clase en schemas/ llevan el conjunto completo de restricciones, incluidas las de tipo, formato, enum y patrón.
3. Validadores
scripts/dev/validate_ecosystem.py recorre el árbol de artefactos, aplica los conjuntos de claves obligatorias anteriores e informa [FAIL] en cualquier artefacto al que le falte un campo obligatorio. El frontmatter-grep por escritura en src/apothem/conformity/frontmatter_grep.py aplica la misma estructura en los límites del hook PreToolUse Write/Edit.
Convenciones de nomenclatura
Prescribe nombres de archivo en kebab-case, formato de claves de frontmatter, nomenclatura de ramas con prefijos de tipo y la semántica de los prefijos numéricos para secuencias de artefactos ordenadas.
Convenciones de Markdown
Estandarizar el sabor de Markdown, la estructura de encabezados, las declaraciones de bloques de código, los formatos de enlaces internos, los banners de autoría y la aplicación por validadores.