Frontmatter Schema
Reference guide for YAML frontmatter block structure, per-class required keys, and validator enforcement rules across artifact classes.
Canonical reference for YAML frontmatter on every artifact class. The summary at
CLAUDE.mdConventions is the inline declaration; the per-class JSON Schemas atsrc/apothem/schemas/(additionalProperties: falsein the skill and command schemas rejects unknown keys; the agent, output-style, and plan schemas setadditionalProperties: true) are the machine-readable contract and win on any disagreement. This page is the required-key index, andartifact-schema.mdxcarries the per-class templates and worked examples — both are human-readable projections of those schemas.
1. Frontmatter Block Shape
Every artifact carries YAML frontmatter at the head, delimited by --- lines. On Markdown-family files the frontmatter is the first content of the file, and the canonical SPDX header line per site/content/docs/reference/authorship-header.mdx follows the closing ---.
Command keys use kebab-case. Skill keys use kebab-case except userInvocable, the camelCase spelling the source corpus uses (the Claude Code install renames it to user-invocable). The Claude Code install and plugin also move the Apothem-only keys (version, updated, archetype, portability) of a skill or command under a trailing metadata: map of quoted strings, in that fixed order, because Claude Code ignores unknown top-level keys and the Agent Skills standard keeps extras in metadata; the source files and every other harness keep them at the top level, except the shared user-level skill folders (~/.agents/skills/ and the ~/.codebuddy/skills/, ~/.kiro/skills/, and ~/.trae/skills/ folders), which fold them the same way. Rule and delegated-worker keys are camelCase, as the required-key table in section 2 lists. Scalar values are either bare or double-quoted; string values containing colons, hash marks, or other YAML-significant characters are quoted.
2. Per-Class Required Fields
The required-key set varies by artifact class. The authoritative shape is enforced by scripts/dev/validate_ecosystem.py and the per-class JSON Schemas under the src/apothem/schemas/ directory. The helper, skill, command, output-style, and plan classes each have one schema file, listed below; the CLAUDE.md and rule classes have none, and validate_ecosystem.py checks their keys. Plan files are not in the table below; their keys are listed in Plans discipline.
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| Class | Required keys |
|---|---|
CLAUDE.md (root config) | name, version, updated, description, scope, portability |
Rules (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 |
Helpers, also called delegated workers (src/apothem/agents/*.md) | name, version, updated, description, tools (optional: a helper that omits it inherits every tool; to give a helper that lists tools an MCP server, name the server in the profile's agent_mcp_servers key), disallowedTools, maxTurns, effort |
Skills (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools; the Claude Code install and plugin, and the shared user-level skill folders, rename userInvocable to user-invocable, and the schema requires each skill to carry exactly one of the two spellings, never both; the Qwen Code install writes allowed-tools as an allowedTools list, the key and shape Qwen Code reads |
Output styles (src/apothem/output-styles/*.md) | name, description; every shipped style also sets keep-coding-instructions: true so Claude Code keeps its software engineering instructions |
Per-class schemas at src/apothem/schemas/ carry the full constraint set including type, format, enum, and pattern restrictions, and length limits: a skill or command description is at most 1,024 characters, the Agent Skills limit.
3. Validators
scripts/dev/validate_ecosystem.py walks the artifact tree, applies the required-key sets above, and reports [FAIL] on any artifact missing a required field. The per-write frontmatter-grep at src/apothem/conformity/frontmatter_grep.py enforces the same shape at PreToolUse Write/Edit hook boundaries.
Naming Conventions
Prescribe kebab-case filenames, frontmatter key format, branch naming with type prefixes, and numeric prefix semantics for ordered artifact sequences.
Markdown Conventions
Standardize Markdown flavor, heading structure, code fence declarations, internal link formats, authorship headers, and validator enforcement.