Skilldeck: skills de IA que leem o repo antes da stack
Skilldeck reúne 36 skills de IA para JS/TS que detectam padrões/definições do repo antes de escolher a stack. As decisões, os becos e o que o 1.0 ensinou.
Jonathan Juliani
Engenheiro de Software Sr - Full Stack · WithClutch Inc. | Juliani Tecnologia
Node.jsTypeScriptIAClaude CodeCursorOpen Source
Você instala skills de IA e, na primeira tarefa, o agente troca o Jest do repo por Vitest, ou o npm por pnpm, ou empurra uma biblioteca que ninguém no time pediu.
A skill parou de ler o projeto e começou a decidir por ele.
Foi isso que me fez construir o skilldeck: 36 skills (no momento em que eu escrevo isso) para JavaScript e TypeScript que primeiro leem o repositório e só depois recomendam alguma coisa. Este post é uma retrospectiva do conceito, da versão 0.1.0 à 1.0.2, com as três decisões principais que importaram e o que ainda está torto.
O que você vai aprender:
Por que eu construí outro pacote de skills
Quais skills moldaram ele
Se ele substitui outros pacotes, e por que usar ou não
Stacks que as mesmas skills ainda atendem, de Jest e npm a Express, NestJS e Redux Toolkit
Por que o peso do pacote é engineering, e onde um companion como o caveman entra
A cadeia de precedência: um standard de projeto ou de empresa fica acima da skill
Por que existe um marketplace só, e não vários para cada "categoria"/"assunto"
O que o Cursor recusa (symlink) e como contornei [trabalho em andamento para corrigir isso]
O que eu faria diferente, e o que eu ainda não sei
O que vem agora no skilldeck
Por que mais um pacote de skills de IA?
Vários pacotes que eu testei nascem em volta de uma stack, ou de um harness só. Isso é uma escolha de verdade, e alguns deles são o motivo dessas skills existirem. O skilldeck faz a outra escolha: o mesmo conjunto de skills, padrões, standards e helpers, em cima do que o projeto já usa.
Eu tentei desenhar ele como um companion que não interfere na stack do projeto, e sim ajuda o projeto a seguir, e claro, se precisar, oferece alternativa e melhoria.
Ele fica quase quieto sobre vendor. Tenta definir e se apoiar em com base na minha experiência, em pacotes novos e ferramentas da comunidade que estão surgindo no ecossistema, e também em qualquer convenção do projeto ou standard da empresa que já esteja definido ou embutido no projeto, e isso fica acima da skill quando existe. O lema do repositório resume:
Inscreva-se no Ledger da Engenharia
Receba notas de arquitetura e performance na sua caixa de entrada. Mesma lista do convite—inscreva-se aqui quando quiser.
Detect before you decide.
Recommend before you impose.
Ask before you assume.
Prove before you claim.
As mesmas skills rodam no Claude Code, no Cursor, no Codex, no Gemini, e possivelmente em outros que usam o setup de .agents. Confesso que ainda não consegui testar todos (e agradeço a ajuda nisso). Também rodam quando o repo já está em Jest, npm, Express, NestJS, Redux Toolkit, Cypress, Prisma ou CSS Modules (aparecem o tempo todo, e o trabalho da skill é conviver com elas). Um serviço legado com npm e Jest, um monorepo com pnpm e Vitest, ou um app Expo recém-criado recebem a mesma ajuda.
Algumas skills moldaram e inspiraram pedaços deste pacote. Ainda são as que eu abro quando quero aquele pedaço, ou algo específico, bem a fundo:
O skilldeck fica com esse conjunto. Esses pacotes continuam separados, e a stack preferida também. O objetivo é as mesmas skills, padrões, standards e helpers, na ferramenta que o projeto ou a empresa já escolheu.
São 36 skills em quatro grupos:
Grupo
Skills
Foundation
3
Engineering
22
Design
6
Process
5
22 das 36 são engineering. Design e process fazem parte do pacote. O peso é engineering, e são essas skills que mais escrevem, então um companion que corta token de saída melhora a sessão inteira. O caveman faz isso. Ele fica ao lado do skilldeck (não é uma das 36), e o trabalho de engineering continua, com menos prosa em volta.
Cada grupo separado. Foundation detecta, configura e escreve o arquivo de instruções.
Engineering é o grupo pesado, desenhado nos quatro degraus do mapa do pacote.
Design decide a superfície antes de qualquer build.
Process fica em volta do trabalho: alinhar, investigar, planejar, desenhar, olhar para trás.
Linha do tempo: do 0.1.0 ao 1.0.2
Em duas semanas saíram oito versões. Quase todas as 0.1.x foram conserto de instalação e de nome, não de conteúdo.
Versão
Data
O que mudou
0.1.0
07/10
Baseline
0.1.1
08/10
Ajustes de instalação e nomes
0.1.2 a 0.1.4
09/10
Mais ajustes de instalação e nomes
1.0.0
09/10
Release 1.0
1.0.1
16/10
Mapa de skills em Mermaid no README
1.0.2
21/10
Zip para OpenAI anexado a cada release
O 1.0.0 saiu no mesmo dia do 0.1.4. As três decisões abaixo são o que sustenta a coleção desde então.
Decisão 1: a cadeia de precedência das skills de IA
Skill que troca a stack está decidindo pelo repo. Então a primeira decisão foi quem manda em quem. A cadeia para na primeira camada que responde:
Pensa num dev que acabou de entrar no time. Ele não chega reescrevendo tudo com a stack que ele curte: primeiro olha como o código já é feito, depois o guia interno da empresa, e só usa o gosto pessoal quando as duas coisas não dizem nada. A cadeia é isso, só que para o agente.
Na prática:
Projeto: o que o agente detecta no repo (gerenciador de pacotes, test runner, estrutura) vence sempre.
Empresa: padrões do time entram depois do que o código já mostra.
Pessoal: só desempata, não manda.
Comunidade: só vale em projeto novo (greenfield), e o agente oferece com um motivo e espera confirmação. Nada de aplicar no automático.
Um repo em Jest e npm, ou um standard da empresa que diz a mesma coisa, é a resposta. O snapshot da comunidade pode preferir Vitest e pnpm. A skill não troca.
Então, por que não só um AGENTS.md bem escrito?
Porque a skill só chega no modelo quando algo vai procurar por ela, e um arquivo lido a cada turno chega sempre. Por isso o setup-skills pode escrever, se você quiser, um bloco de verificação e um bloco de roteamento no AGENTS.md ou CLAUDE.md. A skill ensina; o arquivo garante que o agente lembre.
Uma objeção que eu mesmo fiz: "detectar custa tempo e token". Custa, sim. Mas errar a stack custa mais, porque você só descobre no code review.
Decisão 2: um marketplace só
Marketplace aqui é o catálogo de onde o agente instala plugins. O skilldeck tem um. Claude Code, Cursor, Codex, Gemini e Copilot instalam todos desse mesmo catálogo, e o id de instalação é skilldeck@skilldeck.
Um segundo marketplace é uma segunda cópia das mesmas skills. O agente não sabe qual cópia está atual, então pede para escolher uma. Cada ferramenta tem o próprio manifesto, e todo manifesto descreve esse plugin só. O validador mantém eles alinhados, para não virarem dois pacotes.
Outro detalhe que me custou um tempo: instalar o plugin e rodar npx skills carrega cada skill em dobro, e o agente te pergunta "Pick one". Ele não sabe qual das duas cópias é a certa, e com razão, né? Hoje a documentação diz para escolher um caminho só.
Decisão 3: sobre o Cursor e os symlinks
Aqui eu apanhei. Eu abro o Cursor, importo do GitHub e... nenhuma skill. Zero. Aí eu vou olhar a estrutura e o problema está lá: o pacote era um symlink saindo de plugins/skilldeck.
Symlink é um atalho de pasta, tipo o atalho da área de trabalho que aponta para o arquivo de verdade em outro lugar. O Claude segue o atalho. O Cursor não segue, simplesmente ignora.
A solução foi inverter: os arquivos reais agora ficam em plugins/skilldeck/, e a pasta skills/ na raiz é que virou o atalho para eles, para o npx skills continuar funcionando. Dava para apontar o source do Claude direto para a raiz (./), que é válido para ele, mas o Cursor rejeita esse formato. Por isso os arquivos ficaram mesmo dentro de plugins/skilldeck/.
Dois outros tropeços do mesmo tipo, os "pequenininhos" que ninguém avisa:
Descrição de skill com dois-pontos sem aspas vira um mapa YAML em vez de texto. O validate.py agora checa isso.
Skills que chamam umas às outras podem formar ciclo. O validate.py também detecta ciclos no grafo de chamadas.
O formato das descrições ficou fixo: o que a skill faz, "Use when" e "Not for". Isso ajuda o agente a escolher a skill certa em vez de disparar duas.
O que eu faria diferente
Algumas coisas que eu faria diferente:
Eu testaria a instalação em cada agente alvo antes de publicar a primeira versão: as releases iniciais depois do baseline foram quase só conserto de instalação e de nome, e um teste simples de instalação teria pego isso. Os comandos de aceitação do Codex e do Gemini eu pulei na fase 1, porque nenhum dos dois estava no PATH nem instalado, e isso ainda é dívida.
Eu checaria, e provavelmente vou checar e adaptar, as skills para ficarem mais compatíveis com outras linguagens e frameworks, e não só o ecossistema JavaScript/TypeScript.
Eu focaria um pouco mais em outras áreas maiores, tipo system design, security, observability e process, em vez de focar mais em convenção e standard de código. Mas olha o que vem logo abaixo, é exatamente nisso que eu estou trabalhando.
O que eu ainda não sei
Não sei se uma cadeia de precedência com quatro níveis é simples o bastante para outras pessoas, ou se só faz sentido pra mim.
Também não testei o skilldeck fora do ecossistema JS/TS, que é algo que eu quero fazer e vou fazer em breve.
Não medi se os blocos no AGENTS.md mudam o comportamento do agente em tarefas longas.
É um trabalho constante, e eu fico feliz de contar com a sua ajuda nisso.
O que vem agora no skilldeck
A próxima rodada provavelmente inclui algumas das dívidas acima. Ainda não sei quando, mas em breve:
Rodar os comandos de aceitação no Codex e no Gemini, que ficaram de fora.
Medir se os blocos no AGENTS.md mudam o comportamento do agente em tarefas longas, em vez de achar que mudam.
Testar a instalação em outros agentes alvo.
Junto com isso, conforme eu trabalho em projetos e produtos diferentes, já está rascunhado e eu estou curando e testando alguns companions que vão pegar system design, security, observability e process.
As skills não vão crescer. As de baixo são companions que só disparam quando a tarefa é sobre aquele assunto e precisa delas:
api-design ganha idempotência. A chave nomeia uma tentativa, e todo retry dessa tentativa reusa essa chave (chave nova no retry é como a mesma tentativa roda duas vezes). A mesma chave com um body diferente é conflito.
data-model ganha dinheiro e transações. Um valor é um inteiro na menor unidade, com a moeda, e o servidor recalcula o total. Dois writers não leem uma quantidade e os dois escrevem de volta. Uma chamada para outro sistema fica fora da transação do banco.
frontend-craft ganha um client resiliente, e regras para um dispositivo desassistido ou compartilhado. Toda request tem timeout. Timeout é um resultado desconhecido, então a tela confere o status em vez de convidar um segundo envio. Uma tela compartilhada reseta quando fica parada, e o texto de recuperação assume que não tem ninguém ali para perguntar.
testing-strategy ganha caminhos de falha. O teste afirma o que foi gravado, não quantas vezes uma função foi chamada.
state-management guarda o trabalho em andamento no session storage, com a chave de idempotência, para um reload retomar a mesma tentativa.
security-hardening nomeia o que um cartão pode deixar para trás: um token, os últimos 4 dígitos, a bandeira e a validade. O número completo e o código de segurança nunca são gravados.
ts-standards diz a mesma coisa sobre dinheiro, numa linha. design-brief nomeia um dispositivo desassistido ou compartilhado como superfície, e design-review pergunta se um estranho nessa superfície consegue se recuperar sozinho.
bootstrap-repo pede um readme que um estranho consiga seguir. verify-before-done roda esse readme num ambiente limpo só quando a afirmação é que ele consegue.
Projeto detectado > empresa > pessoal (desempate) > comunidade (só projeto novo, com confirmação)
Um marketplace
Um catálogo só, id skilldeck@skilldeck. Um segundo catálogo é uma segunda cópia que o agente não distingue
Cursor e symlink
Arquivos reais em plugins/skilldeck/, skills/ na raiz como symlink
Instalação
Plugin ou npx skills, nunca os dois
Peso
22 das 36 são engineering. Um standard de projeto ou de empresa vence. Compressão no estilo caveman é um companion, não uma skill do skilldeck
E agora é com você
Qual convenção do seu repo a sua IA ignora toda vez, e que você já cansou de explicar? Me conta, porque é aí que a próxima skill nasce. Se o seu agente já deu uma zika dessas, manda nos comentários ou na newsletter.
