Schema de frontmatter
Guia de referência para a estrutura do bloco de frontmatter YAML, as chaves obrigatórias por classe e as regras de imposição dos validadores entre as classes de artefato.
Referência canônica do frontmatter YAML em todas as classes de artefato. O resumo na seção Conventions do
CLAUDE.mdé a declaração em linha; os JSON Schemas por classe emsrc/apothem/schemas/(additionalProperties: falsenos schemas de skill e de comando rejeita chaves desconhecidas; os schemas de agente, de output-style e de plano definemadditionalProperties: true) são o contrato legível por máquina e prevalecem em qualquer divergência. Esta página é o índice de chaves obrigatórias, eartifact-schema.mdxtraz os templates e exemplos práticos por classe — ambas são projeções legíveis por humanos desses schemas.
1. Forma do bloco de frontmatter
Todo artefato carrega frontmatter YAML no início, delimitado por linhas ---. Nos arquivos da família Markdown, o frontmatter é o primeiro conteúdo do arquivo, e a linha de cabeçalho SPDX canônica conforme site/content/docs/reference/authorship-header.mdx vem depois do --- de fechamento.
As chaves de comando usam kebab-case. As chaves de skill usam kebab-case, exceto userInvocable, a grafia em camelCase que o corpus de origem usa (a instalação do Claude Code a renomeia para user-invocable). A instalação do Claude Code e o plugin também movem as chaves exclusivas do Apothem (version, updated, archetype, portability) de uma skill ou de um comando para um mapa metadata: final de strings entre aspas, nessa ordem fixa, porque o Claude Code ignora chaves de nível superior desconhecidas e o padrão Agent Skills mantém os extras em metadata; os arquivos de origem e todos os outros harnesses as mantêm no nível superior, exceto as pastas de skills compartilhadas no nível do usuário (~/.agents/skills/ e as pastas ~/.codebuddy/skills/, ~/.kiro/skills/ e ~/.trae/skills/), que as agrupam da mesma forma. As chaves de regra e de trabalhador delegado são em camelCase, como lista a tabela de chaves obrigatórias da seção 2. Os valores escalares ficam sem aspas ou entre aspas duplas; valores de string que contêm dois-pontos, cerquilhas ou outros caracteres significativos em YAML ficam entre aspas.
2. Campos obrigatórios por classe
O conjunto de chaves obrigatórias varia conforme a classe de artefato. A forma autoritativa é imposta por scripts/dev/validate_ecosystem.py e pelos JSON Schemas por classe sob o diretório src/apothem/schemas/. As classes de auxiliar, skill, comando, output-style e plano têm cada uma um arquivo de schema, listado abaixo; as classes CLAUDE.md e de regra não têm nenhum, e validate_ecosystem.py verifica as suas chaves. Os arquivos de plano não estão na tabela abaixo; suas chaves estão listadas em Disciplina de planos.
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 | Chaves obrigatórias |
|---|---|
CLAUDE.md (configuração raiz) | name, version, updated, description, scope, portability |
Regras (src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
Comandos (src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
Auxiliares, também chamados de trabalhadores delegados (src/apothem/agents/*.md) | name, version, updated, description, tools (opcional: um auxiliar que a omite herda todas as ferramentas; para dar um servidor MCP a um auxiliar que lista tools, nomeie o servidor na chave agent_mcp_servers do perfil), disallowedTools, maxTurns, effort |
Skills (src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools; a instalação do Claude Code e o plugin, e as pastas de skills compartilhadas no nível do usuário, renomeiam userInvocable para user-invocable, e o schema exige que cada skill carregue exatamente uma das duas grafias, nunca as duas; a instalação do Qwen Code grava allowed-tools como uma lista allowedTools, a chave e o formato que o Qwen Code lê |
Output-styles (src/apothem/output-styles/*.md) | name, description; todo estilo distribuído também define keep-coding-instructions: true para que o Claude Code mantenha as suas instruções de engenharia de software |
Os schemas por classe em src/apothem/schemas/ carregam o conjunto completo de restrições, incluindo restrições de tipo, formato, enum e padrão, além de limites de tamanho: a description de uma skill ou de um comando tem no máximo 1.024 caracteres, o limite do Agent Skills.
3. Validadores
scripts/dev/validate_ecosystem.py percorre a árvore de artefatos, aplica os conjuntos de chaves obrigatórias acima e reporta [FAIL] em qualquer artefato ao qual falte um campo obrigatório. O frontmatter-grep por gravação, em src/apothem/conformity/frontmatter_grep.py, impõe a mesma forma nos limites do hook PreToolUse de Write/Edit.
Convenções de nomenclatura
Prescreve nomes de arquivo em kebab-case, formato de chaves de frontmatter, nomenclatura de branches com prefixos de tipo e a semântica de prefixos numéricos para sequências de artefatos ordenadas.
Convenções de Markdown
Padronize o sabor de Markdown, a estrutura de títulos, as declarações de blocos de código cercados, os formatos de links internos, os cabeçalhos de autoria e a imposição por validadores.