JMBargueno/skanvil

O que skanvil faz?

Objetivo

Alterar bibliotecas de skills através do CLI skanvil, para que as pastas de skills, o frontmatter do SKILL.md, o índice README e as convenções da biblioteca permaneçam consistentes e a validação permaneça verde.

Quando Ativar Esta Skill

• O repositório possui um .skanvilrc.json, uma pasta skills/ com arquivos SKILL.md, ou skanvil em seu package.json.
• O usuário pede para adicionar, escrever, renomear, mover, retitular, redescrever, excluir, listar, validar ou indexar skills.
• skanvil validate, npm test ou CI falha com diagnósticos do skanvil.
• O usuário deseja que as skills de uma biblioteca estejam disponíveis para Claude Code, GitHub Copilot ou Codex em outro projeto.

Instruções

1. Oriente-se

1. Leia .skanvilrc.json. Ele define as categorias (id, prefixo de pasta prefix, título do README title, aliases), as seções obrigatórias, placeholders e severidades de regras. Um arquivo ausente significa o preset padrão: front-, back-, transversal sem prefixo (o padrão) e _internal.
2. Execute npx skanvil list --json para ver cada skill com sua categoria, presença no README e validade.
3. Execute npx skanvil validate --json antes de alterar qualquer coisa, para saber quais problemas já existiam.

2. Regras de ouro

• Nunca renomeie, mova ou exclua pastas de skills manualmente, e nunca edite o índice README manualmente. Use skanvil edit, que mantém a pasta, o name do frontmatter, o # heading e a entrada README sincronizados, e reverte em caso de falha.
• Nunca crie pastas de skills manualmente. Use skanvil add, que aplica o prefixo da categoria, o template, os metadados do frontmatter e a entrada README.
• Sempre passe todas as opções em shells não interativos. add precisa de --type, --name e --description. edit --remove precisa de --yes. Caso contrário, o comando solicita entrada, ou falha sem um TTY.
• Nunca execute skanvil sem argumentos ou skanvil wizard. Eles abrem um menu interativo destinado a humanos. Use os comandos explícitos abaixo. Se o usuário preferir menus, sugira que ele execute npx skanvil diretamente.
• Adicione --json sempre que precisar analisar a saída. Os dados vão para stdout; avisos e erros vão para stderr.
• Execute npx skanvil validate após cada alteração e termine sem erros. Código de saída 1 significa erros, ou avisos quando --strict é usado.
• Prefixe cada comando com npx a menos que skanvil esteja no PATH. Use -C <caminho> para direcionar uma biblioteca em outra pasta.

3. Tarefas comuns

Criar uma skill e depois escrever seu conteúdo.

npx skanvil add --type <categoria> --name "<nome curto>" \
  --description "<o que faz>. Use quando <situações de gatilho>."

Depois edite skills/<prefixo><nome>/SKILL.md:

• Preencha cada seção obrigatória com conteúdo concreto e acionável.
• Substitua todas as sentenças genéricas do template. Até que você faça isso, validate relata um aviso template-unchanged, e validate --strict (o npm test da biblioteca) falha.
• Mova material longo para references/, e vincule apenas a arquivos que existem (broken-references).

Use --no-scripts, --no-assets ou --no-references quando essas pastas ficarem vazias. Use --template <nome> para um template customizado em .skanvil/templates/.

Renomear ou mover uma skill.

npx skanvil edit <skill> --rename <novo-nome>          # prefixo é reaplicado automaticamente
npx skanvil edit <skill> --type <outra-categoria>      # novo prefixo, seção README, metadados
npx skanvil edit <skill> --title "<Título>" --description "<texto>"

--rename pega o nome base: edit front-a --rename b resulta em front-b.

Excluir uma skill. Confirme com o usuário primeiro; isso é permanente.

npx skanvil edit <skill> --remove --yes

Corrigir erros de validação.

1. Execute npx skanvil doctor --fix. Ele repara entradas README, incompatibilidades de name, tabs no frontmatter e converte tools para allowed-tools.
2. Corrija o que restar editando SKILL.md. Use a tabela de diagnóstico abaixo.
3. Execute npx skanvil validate novamente.

Reconstruir o índice README após alterar títulos de categoria em .skanvilrc.json:

npx skanvil index          # reescreve as seções do índice
npx skanvil index --check  # verificar apenas (CI)

Instalar as skills em um projeto.

npx skanvil sync <dir-projeto> -C <dir-biblioteca> --target claude,copilot --dry-run   # pré-visualizar
npx skanvil sync <dir-projeto> -C <dir-biblioteca> --target claude,copilot
npx skanvil sync --from @escopo/pacote --target agents                             # pacote instalado

Destinos:

• claude instala em .claude/skills;
• copilot instala em .github/skills;
• agents e codex instalam em .agents/skills.
• Um caminho customizado deve ser uma pasta dentro do projeto.
• --global (sem diretório de projeto) instala nas pastas ~/.claude/skills, ~/.copilot/skills ou ~/.agents/skills do usuário. Use apenas quando o usuário pedir skills disponíveis em todos os projetos.

Como o sync se comporta:

• Ele nunca sobrescreve pastas que não instalou.
• Ele remove skills que foram removidas da biblioteca.
• Ele pula skills com erros de validação, a menos que --force seja fornecido.
• Ele nunca publica skills _internal.

Adicionar ou alterar categorias. Edite categories em .skanvilrc.json:

• exatamente uma categoria tem "default": true e sem prefixo;
• toda outra categoria tem um prefixo que é _ ou kebab-case terminando em -;
• nenhum prefixo pode começar com outro prefixo.

Depois mova as skills existentes com edit --type, e execute skanvil index.

4. Escreva um bom conteúdo de skill

• description diz o que a skill faz e quando usá-la, com as palavras-chave de gatilho que um agente veria. Deve ter no máximo 1024 caracteres.
• name é igual ao nome da pasta: letras minúsculas, dígitos e hífens simples, no máximo 64 caracteres.
• Corpo: mantenha SKILL.md abaixo de 500 linhas. Escreva instruções como etapas numeradas e verificáveis, e coloque exemplos, casos extremos e listas de verificação longas em references/ (um nível de profundidade).
• Placeholders: nunca deixe texto de preenchimento. Qualquer entrada de validation.placeholders (marcadores de afazeres, texto latino fictício, notas "a decidir") falha na validação.
• metadata: apenas valores string, então coloque números entre aspas, como em version: "1.0".
• allowed-tools: uma string separada por espaços, não uma lista.

5. Diagnóstico → correção

Regra	Correção
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix, ou edit --rename se o nome da pasta estiver errado
frontmatter-tabs, tools-field	doctor --fix
frontmatter	Repare o YAML entre as linhas --- (coloque entre aspas valores contendo : ou #).
required-sections	Adicione a ## Seção faltante listada em validation.requiredSections.
placeholders	Substitua o texto placeholder por conteúdo real.
description-length, max-lines	Encurte; mova detalhes para references/.
metadata-format	Coloque entre aspas valores não string.
duplicate-name	Duas pastas compartilham um name: renomeie uma com edit --rename.
broken-references	Crie o arquivo referenciado, ou corrija o link (caminhos são relativos à skill).
template-unchanged	Reescreva as sentenças genéricas do scaffold com instruções específicas da skill.

Veja references/REFERENCE.md para todas as opções de comando, o esquema de configuração e as formas da saída JSON.

Formato de Saída

Relate ao usuário:

• os comandos skanvil que você executou;
• as skills criadas, alteradas ou removidas, com seus nomes de pasta;
• o resultado final de skanvil validate (erros e avisos), e qualquer coisa que tenha ficado para ele decidir.

Critérios de Qualidade

• Cada alteração estrutural passou por skanvil add ou skanvil edit. Não há renomeações manuais de pastas ou edições manuais do índice README.
• npx skanvil validate não relata erros, e npx skanvil index --check passa.
• Skills novas ou editadas têm descrições específicas com gatilhos, e nenhum filler de template ou placeholders.
• Exclusões e sincronizações em outros projetos foram confirmadas com o usuário.