wSkills

Skills reutilizáveis de Claude Code, extraídas de um portal operacional em produção (Vue 3 + PrimeVue 4 + Django REST) e generalizadas para servir a qualquer projeto com o mesmo stack.

Uma skill é um conjunto de instruções que o agente carrega sozinho quando a tarefa combina com a descrição dela — regra de arquitetura, padrão de tela, convenção de commit. Em vez de repetir "lembra que aqui a gente faz assim" a cada sessão, a regra mora num arquivo versionado.

npx @wgalleti/wskills list                    # ver o catálogo
npx @wgalleti/wskills add frontend-kickstart  # instalar no projeto atual

Catálogo

Não sabe por onde começar? Instale tudo (npx @wgalleti/wskills add --all) e diga "quero criar um sistema" — a skill novo-projeto é a porta de entrada: ela orquestra as demais na ordem certa, sem você precisar conhecê-las. Guia de uso detalhado, com exemplos fase a fase: docs/novo-projeto.md.

| Skill | Para quê | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | novo-projeto | A porta de entrada para criar um projeto do zero: descobre a fase (ideia → documentação → dados/API → telas → ondas → conversão) e orquestra as outras skills na ordem certa, carregando só o que a fase atual precisa. | | frontend-kickstart | Iniciar um frontend novo com o stack completo: bootstrap (Vite, PrimeVue 4 unstyled, Tailwind 4, Pinia), arquitetura em camadas, design system em tokens, regras de usabilidade e um tokens.css pronto para copiar. | | portal-frontend | Trabalhar num app já montado nesse padrão: regras inegociáveis, árvore de decisão de tela, o que fica no app × o que vai para a suite, gotchas que já custaram tempo. | | wpvc | API da suite @wgalleti/primevue-components (W*): setup, useCrudManager, ColumnDef/FieldDef, migração de código ad-hoc para os componentes. | | mr | Padrão editorial de Merge Request (Problema → Análise → Solução → Validação, legível por gestão não técnica) + regras de commit. | | documento | Escrever documento de projeto renderizado por WMarkdownView: vocabulário de marcação rica (alertas, passos, cards, abas, mermaid) e regras editoriais. | | sdd | Documentar um projeto no padrão SDD simplificado: quatro arquivos em docs/ (context, tasks, notes, validation) e uma linha no CLAUDE.md que obriga o padrão — para qualquer pessoa modelar um projeto que depois possa ser convertido em estrutura maior (portal, API, app). | | prototipo-api | Backend de protótipo sem Docker/WSL: servidor Node de arquivo único que gera a API a partir de um db.json declarativo, no mesmo contrato do portal (envelope, take/skip, erros DRF em pt-BR) — o frontend funciona sem adaptação e a conversão para Django/DRF sai barata. | | ui-rica | Direção e auto-revisão visual de telas, independente de stack: carregar a direção de design disponível (plugin de frontend design, tokens do projeto, guias das outras skills), usar os componentes que já existem antes de reinventar, e passar um checklist de espaço/hierarquia/riqueza antes de entregar — para a primeira versão da tela já sair boa. | | geojson | Padrões de GeoJSON/geometria (contornos de área): formato canônico WGS84 2D, importação com reprojeção UTM, geometria nunca em listagem, endpoint paginado + render progressivo no mapa, versionamento de desenhos. | | manual-doc | Produzir página de manual de uso de um app web: levantar o comportamento real no código, operar a tela com dados de demonstração (zero dado real — o manual é público), capturar screenshots/GIFs e redigir no vocabulário da documento. | | projeto | Amarrar o worktree a um card de projeto (kanban do portal) e manter documento, tarefas e status em dia via um CLI de boca única (implementação de referência em Django incluída): resolução híbrida uuid → nome → branch, saída JSON, ambiguidade = pergunta. | | prototipo-portal | Prototipar fora do portal (Lovable, MVP, prova de conceito) já no padrão do destino: identidade visual com tokens prontos, os 7 padrões de tela e a forma de dados/API — para a conversão custar menos. |

Detalhe de uma skill antes de instalar:

npx @wgalleti/wskills info portal-frontend

Instalação

O CLI copia a pasta da skill para o diretório de skills do Claude Code. Não precisa de install prévio nem de dependência de runtime.

# no projeto (fica em ./.claude/skills — versione junto do repositório)
npx @wgalleti/wskills add frontend-kickstart wpvc

# para todos os seus projetos (fica em ~/.claude/skills)
npx @wgalleti/wskills add mr --global

# tudo de uma vez
npx @wgalleti/wskills add --all

Reinicie a sessão do Claude Code depois de instalar. Confirme com /skills — a skill aparece pelo name do frontmatter.

Sem acesso ao npm? Clone e rode o CLI direto — o comportamento é idêntico:

git clone https://github.com/wgalleti/wSkills.git ~/wSkills
cd meu-projeto
node ~/wSkills/bin/wskills.mjs add frontend-kickstart

Projeto ou global? Skill que descreve como este repositório trabalha (portal-frontend, documento) vai no projeto e é versionada com ele — assim todo mundo do time e todo agente pegam a mesma regra. Skill de método pessoal (mr) costuma render mais no global.

Comandos

| Comando | O que faz | | ------------------- | ------------------------------------------------------- | | list | lista o catálogo com um resumo de cada skill | | info <skill> | descrição completa e arquivos que serão copiados | | add <skill...> | instala (--all para todas) | | update [skill...] | reinstala sobrescrevendo — traz a versão nova do pacote | | remove <skill...> | remove skills instaladas | | status | o que está instalado, em que versão, e o que divergiu |

| Flag | Efeito | | ----------------- | --------------------------------------------------------- | | -g, --global | instala em ~/.claude/skills | | --dir <caminho> | diretório alvo (default: ./.claude/skills) | | --all | todas as skills do catálogo | | -f, --force | sobrescreve skill existente, inclusive editada localmente | | --dry-run | mostra o que faria, sem escrever nada | | --json | saída em JSON (list, status) |

Atualizar

npx sempre busca a última versão publicada, então:

npx @wgalleti/wskills status   # vê o que está desatualizado ou editado
npx @wgalleti/wskills update   # reinstala tudo que foi instalado por aqui

O CLI grava um manifesto .wskills.json no diretório de skills com versão e checksum de cada instalação. É ele que permite ao add recusar sobrescrever uma skill que você editou — o aviso vem com a instrução de usar --force se a sobrescrita for mesmo o que você quer.

Editou uma skill e quer manter a edição? Renomeie a pasta (e o name: do frontmatter): ela sai do controle do CLI e vira sua.

Usar no Lovable (e em IAs sem suporte a skills)

A skill prototipo-portal existe também em formato "cola e usa": o arquivo skills/prototipo-portal/references/lovable-knowledge.md reúne os três guias (identidade visual, padrões de frontend, dados/API) num markdown único, sem nada específico de Claude Code.

Passo a passo no Lovable:

1. Abra (ou crie) o projeto no Lovable.

2. Clique no nome do projeto → Settings (engrenagem) → seção Knowledge. O Knowledge é um texto que o Lovable relê em toda geração do projeto — é o lugar certo para o guia valer sempre, sem repetir a cada prompt.

3. Copie o conteúdo inteiro de skills/prototipo-portal/references/lovable-knowledge.md e cole no campo. Salve.

4. No primeiro prompt, reforce:

   Siga o Knowledge do projeto como direção de design e de dados: ele descreve o sistema final para onde este protótipo será convertido. Em conflito, prefira o guia — mas proponha algo melhor quando tiver motivo, sinalizando o desvio.

Projeto que já existe no Lovable: cole o Knowledge do mesmo jeito e peça num prompt "alinhe o visual ao design system descrito no Knowledge". Se a interface mudar de lugar, procure por "Knowledge" nas configurações do projeto — o conceito permanece.

Outras IAs: ChatGPT/Gemini — crie um Project/GPT com o arquivo como conhecimento; v0/Bolt — cole no prompt inicial.

O arquivo é gerado a partir dos guias em references/ (o cabeçalho dele diz como regenerar). Edite os guias, nunca o gerado.

Começando no Claude Code

Time novo no Claude Code (principalmente no plano Pro, onde token conta):

docs/claude-code.md — guia completo, do zero a produtivo: instalar (Windows/macOS/Linux, passo a passo com o terminal na mão), logar, instalar as skills deste pacote, montar o CLAUDE.md com prompt pronto, a rotina de trabalho que faz o Pro render o dia, e as ferramentas que multiplicam o plano (rtk, graphify, ccusage, MCPs) — quase tudo instalado pedindo ao próprio Claude.

Worktrees paralelos com Orca

Além das skills, o repositório traz um kit para rodar um monorepo dentro do Orca com API, frontend e banco Postgres isolados por worktree — portas por slot, clone do banco de dev, teardown/limpeza automáticos e MR draft por frente de trabalho. O contexto assumido: banco em Docker, API e frontend subindo nativos no terminal.

docs/orca-worktrees.md — o desenho completo e o checklist de adaptação; scripts prontos para copiar em docs/orca/.

Adaptar ao seu projeto

frontend-kickstart e wpvc funcionam como vêm. portal-frontend, documento, geojson, manual-doc e projeto descrevem regras de um portal específico e trazem um bloco "adapte ao instalar" no topo: ajuste os caminhos de arquivo, o nome da paleta e os gotchas para a sua realidade, e apague o que não se aplica. Skill que descreve um repositório que não é o seu vira ruído — e ruído o agente segue à risca.

Contribuir

Veja CONTRIBUTING.md. Em resumo: uma pasta por skill em skills/, com SKILL.md (frontmatter name + description) e o material pesado em references/. Antes de abrir PR:

npm run validate

O validador checa estrutura (frontmatter, name batendo com a pasta, referências existentes) e vazamento: caminho absoluto de máquina, token, IP interno, e-mail. Este repositório é público — nome de cliente e de pessoa não entram nas skills.

yarn validate   # estrutura + vazamento
yarn smoke      # instala o catálogo num tmp e confere o ciclo do CLI
yarn format     # prettier

Release e publicação no npm: PUBLISHING.md — bump por commit-and-tag-version a partir dos conventional commits, publicação manual (yarn release:publish).

Licença

MIT.