/skill-lint — valida uma skill contra as convenções do ateliê

Linter de uma skill por vez (o caso "antes de fechar esta skill"). A parte determinística e repetitiva vive em scripts/lint-skill.ps1 (parse do frontmatter, contagem de linhas, inventário de scripts/references, checagens de convenção, AST-parse dos .ps1) e devolve JSON. Você (modelo) lê o JSON, dá o veredito, prioriza e — só com aceite — oferece corrigir os triviais e smoke-rodar os scripts. O script nunca escreve nem executa nada.

Parâmetros

• [nome-da-skill | caminho] — nome resolvido sob ~/.claude/skills, caminho da pasta da skill, ou caminho de um SKILL.md. Sem argumento: se o diretório atual é uma skill (tem SKILL.md), use-a; senão liste as skills do ateliê e pergunte qual via AskUserQuestion.

Fluxo

1. Resolver o alvo

Determine a pasta da skill (regra acima). Se nada resolver, liste ~/.claude/skills\*\SKILL.md e pergunte qual.

2. Rodar o motor (determinístico)

pwsh -NoProfile -File "<dir-da-skill>/scripts/lint-skill.ps1" -Path "<nome|caminho>"

Devolve { skill, path, resolvedScope, frontmatter{name,description,scope,userInvocable,argumentHint, allowedTools[],unknownKeys[]}, bodyLineCount, scriptsDir, scripts[{file,parseOk,error}], checks[{id,severity,ok,message,hint,evidence}], summary{errors,warnings,infos,readyToClose} }. Severidades: error (impede carregar/fechar) · warning (degrada descoberta/qualidade) · info (nota). Se o JSON trouxer error no topo, o alvo não foi encontrado — reporte e pare.

3. Renderizar o relatório (julgamento seu)

Apresente nesta forma:

• Placar: <skill> — N erros, M warnings + veredito a partir de summary.readyToClose ("✅ pronta pra fechar" / "⛔ ainda não — resolva os erros").
• Erros e Warnings como punch list: id · message · → hint (cite evidence quando útil).
• Ações priorizadas: erros primeiro, depois warnings de alto valor (description sem gatilho, PowerShell faltando, body > 200). Não despeje os ok:true — só o que falha + o veredito.

4. Smoke-run dos scripts (opcional, COM aceite)

O AST-parse (estático) já roda no motor. Para o smoke-run de verdade — executar cada .ps1 de scripts/ com args de exemplo só pra ver se não explode — há efeito colateral (alguns scripts clonam, chamam API, escrevem). Então: pergunte antes (AskUserQuestion), peça/infira args de exemplo seguros, rode com timeout curto e reporte apenas "subiu / quebrou (+stderr)". Não julgue a saída — isso é trabalho da skill-eval. Pule este passo se o usuário não quiser.

5. Oferecer fix dos triviais (SEMPRE perguntar)

Para defeitos mecânicos e seguros, ofereça aplicar via Edit — só após aceite explícito:

• scope ausente → adicionar scope: project (ou global, perguntando).
• name ≠ pasta → alinhar o name ao nome da pasta (ou sugerir renomear a pasta).
• scripts/ sem PowerShell no allowed-tools → adicionar PowerShell.
• user-invocable sem argument-hint → adicionar argument-hint: "".
• tool mal-capitalizada (read → Read). Defeitos de julgamento (description fraca, corpo longo, erro de sintaxe em script) não se auto-corrigem: explique e deixe pro autor. Nunca escreva sem o "sim".

6. Fechar

Se ficou verde, lembre: para usar num projeto → /install-skill <nome> (global → --global).

Guardrails

• Read-only por padrão. O motor não escreve nem executa; smoke-run e fix exigem aceite.
• Estático é do script; veredito é seu. Não reimplemente o parse no chat — chame o .ps1 e consuma o JSON. Não invente checagens que o JSON não traz.
• Uma skill por vez. Para saúde geral do ateliê, rode em loop por fora — esta skill foca uma.
• Convenções vêm de ~/.claude/skills\CLAUDE.md. Se ele mudar, ajuste scripts/lint-skill.ps1 (allowlist de chaves/tools, limite de linhas) — é a fonte de verdade.

Ativação

Esta skill é scope: global (família da forja, como skill-scout/skill-prospector). A cópia canônica vive no ateliê; para ativá-la em qualquer workspace: /install-skill skill-lint --global.