frontmatter-check

O que é

Um conferidor do cabeçalho de recursos do AmFlow. Ele lê o bloco de informações que fica no topo de uma skill, agent, command ou hook, aponta o que está errado e devolve o bloco corrigido pronto para colar.

Problema que resolve

Todo recurso do AmFlow começa com um bloco de informações — nome, descrição, versão, autor, estado. Não é decoração: é a identidade do recurso. A descrição é o que o marketplace indexa e o que o Claude lê para decidir se aquele recurso serve; a versão precisa ser maior que a publicada para uma atualização ser aceita; o estado governa o ciclo de publicação.

Um campo errado ali não quebra nada na hora. Quebra depois, e de três formas que custam caro:

• A publicação é recusada, e a mensagem nem sempre diz qual campo causou
• O recurso é publicado e nunca é encontrado, porque a descrição não diz quando usá-lo
• O recurso é instalado e o Claude não o invoca, pelo mesmo motivo

Conferir à mão funciona até o quarto campo. Do quinto em diante, o erro que passa é sempre o de coerência — dois campos que, isolados, estão certos, e juntos se contradizem.

Como funciona

A skill lê o arquivo e faz quatro passagens, nesta ordem:

1. Campos presentes — os treze campos obrigatórios existem? Alguns podem estar vazios, outros não.
2. Valores válidos — cada campo aceita um conjunto fechado de valores. status é um de cinco;

version é um número de três partes; datas seguem um formato só.

1. Coerência entre campos — a passagem que pega o que as duas primeiras não pegam. Uma data de

atualização anterior à de criação. Um nome diferente do nome da pasta. Um recurso marcado como publicado sem o identificador que só o marketplace atribui.

1. A descrição — tratada à parte, porque é o campo de maior efeito e o mais fácil de escrever mal.

O resultado não é um relatório de tudo que passou. São os problemas, um por linha, cada um dizendo o campo, o que está errado e por que importa — seguidos do bloco corrigido inteiro.

A skill nunca altera o arquivo. Ela lê e reporta; quem edita é quem pediu.

Como usar

Peça a conferência e informe o arquivo:

Confira o frontmatter da skill deep-research

Ou invoque pelo nome, quando quiser ser explícito:

/frontmatter-check

Três momentos em que ela vale:

• Antes de publicar um recurso no marketplace
• Ao revisar um recurso que outra pessoa escreveu
• Quando uma submissão foi recusada e o motivo não ficou claro

Exemplos de uso

Recusa de publicação sem motivo claro. O Creator submete uma atualização e recebe recusa. A skill aponta: a versão local é 1.0.0, igual à publicada — uma atualização precisa de versão maior. Devolve o bloco com 1.0.1 e a data de atualização corrigida.

Recurso publicado que ninguém encontra. A descrição diz *"skill de exemplo"*. A skill sinaliza que isso descreve o formato, não o uso, e propõe uma frase que diz o que a skill faz e quando vale invocá-la — que é o que o marketplace indexa e o Claude lê.

Revisão de recurso de terceiro. Antes de aprovar, a conferência mostra que o nome no cabeçalho não bate com o nome da pasta. Os dois estão certos isoladamente; juntos, quebram a instalação, porque o marketplace resolve pelo nome declarado e o erro só aparece depois de instalado.

Fundamentação

O padrão conferido é o Padrão de Frontmatter do AmFlow, definido nas instruções do projeto: treze campos em três blocos — identidade, histórico e sistema — mais os campos que o marketplace preenche sozinho na publicação.

A ordem das quatro passagens não é arbitrária. Verificação campo a campo pega ausência e valor inválido, mas é cega para contradição entre campos válidos — por isso a terceira passagem existe e é a que encontra os erros caros. A quarta passagem separa a descrição das demais por uma razão de efeito: é o único campo cujo erro não impede nada e mesmo assim inutiliza o recurso.

Base de conhecimento

• O padrão de frontmatter e os valores aceitos em cada campo, extraídos das instruções do projeto AmFlow
• Os campos que o marketplace atribui na publicação, e por que inventar valor para eles corrompe a

submissão

• O critério de uma boa descrição: o que o recurso faz e quando vale usá-lo, numa frase, sem repetir o

nome

Não carrega base externa, não consulta a internet e não depende de nenhum serviço.

Limites

• Não edita o arquivo. Devolve o bloco corrigido; aplicar é de quem pediu.
• Não confere o corpo do recurso — só o cabeçalho. Se a skill está bem escrita, se as instruções

funcionam ou se o exemplo faz sentido, ela não olha.

• Não substitui a revisão da publicação. O marketplace tem verificações próprias, e passar aqui não

garante aprovação lá.

• Não julga se a descrição está boa em termos de marketing. Aponta quando ela descreve o formato em

vez do uso, e propõe alternativa — não otimiza texto de venda.

• Não trata a ausência do identificador do marketplace como erro num recurso que nunca foi publicado.
• Não cobre módulos, cuja identidade não vive em frontmatter.