Uma skill que nunca roda raramente tem problema de sintaxe. Ela carrega, aparece na lista e nunca é escolhida — porque a descrição não diz quando se aplica, ou diz com palavras que ninguém usaria. Essa falha é silenciosa por natureza: não há erro, nem aviso, nem sinal de que algo esteja errado. Este linter lê o arquivo do mesmo jeito que o carregador, relata o que estiver malformado e depois dedica quase toda a atenção à descrição: se nomeia um gatilho, se é longa o bastante para haver associação e se começa repetindo que é uma skill. Campos que o carregador ignora também são apontados, já que um erro de digitação numa chave tem exatamente a mesma aparência de um arquivo correto.
Recursos
Lê o frontmatter com um analisador YAML de verdade e indica onde falha
Aponta campos que o carregador não lê: a cara de um erro de digitação numa chave
Confere a descrição quanto a cláusula de gatilho e tamanho
Informa a contagem de caracteres da descrição em relação ao limite
Confere se as instruções passam do tamanho abaixo do qual não ajudam
Pontuação com erros pesando mais que sugestões
Solte um arquivo, ou cole
Um exemplo quebrado de propósito para ver o que ele pega
Como usar Linter de skills
Solte um SKILL.md ou cole o conteúdo
Leia os achados, do pior para o melhor
Corrija a descrição se ela for apontada — é a que importa
Confira de novo até a pontuação ficar limpa
Exemplo
Entrada
description: Helps with PDFs
Saída
Warning: says what the skill is, but not when to use it
O motivo mais comum de uma skill nunca ser escolhida.
Erros comuns e solução de problemas
Diz que não há frontmatter, mas claramente há. — Os três hifens têm que ser a primeiríssima linha: sem linha em branco, sem comentário, sem nada acima.
O YAML falha numa descrição longa. — Uma descrição com dois-pontos seguidos de espaço precisa de aspas, senão o YAML a lê como outra chave.
Aponta um campo que uso de propósito. — Campos desconhecidos aparecem como notas, não erros. O carregador os ignora; a nota existe porque uma chave escrita errado é idêntica a uma correta.
A pontuação continua baixa sem erros listados. — Avisos também custam pontos. A dupla habitual é uma descrição sem cláusula de gatilho e instruções curtas demais.
Perguntas frequentes
Por que minha skill carrega mas nunca é escolhida?
A descrição é comparada com a tarefa, então se ela só descreve o assunto — “trabalha com planilhas” — não há nada com que casar um pedido. Acrescentar uma cláusula que nomeie a situação, os tipos de arquivo ou as palavras que uma pessoa usaria costuma resolver.
O que conta como cláusula de gatilho?
Qualquer coisa que nomeie o momento em que a skill se aplica: “Use quando o usuário pedir…”, “Sempre que um arquivo de migração mudar…”, “Para tarefas envolvendo…”. O linter procura esse formato e avisa quando não encontra.
Uma descrição longa é ruim?
Em si não: o limite é generoso e a contagem é mostrada. O que prejudica é uma descrição longa que ainda assim nunca diz quando usar a skill, uma combinação surpreendentemente comum.
Posso analisar uma skill que não escrevi?
É um bom uso. Soltar uma skill de outro lugar mostra na hora se a descrição dela vai competir com as suas e se declara ferramentas que você não esperava.
Um resultado limpo garante que a skill funciona?
Não. Significa que o arquivo vai carregar e que a descrição tem o formato que é comparado. Se as instruções são boas é um julgamento que nenhum linter faz.
Ferramentas relacionadas
Construtor de skills — Escreva um SKILL.md com o frontmatter verificado enquanto você digita.
Construtor de subagentes — Monte o arquivo de definição de um subagente com ferramentas e modelo.
Linter de prompts — Encontre contradições, instruções mortas e marcadores não preenchidos.
Verificador de esquemas — Cole uma definição e descubra por que ela é rejeitada ou chamada errado.