Como reaproveitar sua skill de frontend em outro projeto e compartilhar com o time

Fala aí, beleza? Sua skill de frontend finalmente parou de inventar componente fora do padrão em um repositório, aí você abre o próximo projeto e… nada, a regra ficou pra trás

O reflexo é copiar a pasta pro outro repo

Funciona uma vez, funciona duas, e na terceira você tem três versões levemente diferentes da mesma regra, cada uma apontando pra um caminho de pasta que só existe em um lugar 😅

Esse post trata justamente do meio do caminho: separar o que é regra universal de frontend do que é específico daquele repositório, e só depois escolher como distribuir (pasta pessoal, pasta de projeto versionada ou plugin com marketplace)

O que você precisa antes de mover a skill

Nada exótico, mas confere os três itens:

• Uma skill já funcionando: uma pasta com um arquivo SKILL.md, composto de frontmatter YAML delimitado por --- e um corpo em markdown com as instruções
• Claude Code CLI: é por ele que roda o claude plugin validate
• git: a versão de projeto da skill é compartilhada com o time por estar versionada junto com o código

E um aviso de escopo que pesa MUITO na hora de decidir o formato de distribuição: o campo allowed-tools do SKILL.md só é suportado no Claude Code CLI, e não se aplica quando a skill é usada pelo SDK

Ou seja, se a mesma skill vai rodar nos dois mundos, não dependa de allowed-tools pra ela se comportar

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Passo a passo: separar o genérico do específico e distribuir a skill

1. Separe o conteúdo em duas colunas antes de tocar no arquivo

Antes do como, o porquê: skill que não roda em outro projeto quase sempre é skill que misturou regra com endereço

Pega o SKILL.md atual e marca cada instrução:

• Genérico: convenção de componente, padrão de estado, acessibilidade, regra de nomenclatura, o que você faria igual em qualquer app
• Específico: caminho de pasta, design system interno, nomes das libs daquele repo, tokens de tema, estrutura de rotas

Se você já passou por isso ao escrever uma skill para uma stack específica, a lógica é a mesma, só que agora em sentido contrário: em vez de amarrar na stack, você está soltando

O erro comum deste passo: classificar "usamos Tailwind" como genérico

Não é, isso é decisão do repositório

2. Reescreva o SKILL.md deixando o corpo genérico e a description precisa

Você trabalha no SKILL.md que já está dentro do projeto, e ele vira a versão genérica

Só que antes de apagar qualquer coisa, salva a coluna do específico num rascunho, um arquivo de texto qualquer, porque ela volta no passo 4

Feito isso, o corpo vira regra pura, sem endereço

E o frontmatter merece atenção especial, porque o campo description é o que permite ao Claude descobrir e acionar a skill no momento certo

---
name: design-frontend
description: Aplica as convenções de UI do time ao criar ou revisar componentes de interface, incluindo padrão de estado, acessibilidade e nomenclatura
---

# Convenções de frontend

## Componentes
- um componente por arquivo
- estado local fica no componente, estado compartilhado sobe
...

As propriedades permitidas no frontmatter são allowed-tools, compatibility, description, license, metadata e name

Qualquer coisa fora disso não é campo, é enfeite

O erro comum deste passo: description genérica tipo "ajuda com frontend"

Aí a skill não é acionada na hora certa e você acha que ela quebrou, quando na real ela nunca foi chamada

3. Suba a parte genérica para a pasta pessoal

Skill colocada na pasta pessoal fica disponível em todos os projetos do mesmo usuário, sem precisar copiar para cada repositório

mkdir -p ~/.claude/skills/design-frontend
cp .claude/skills/design-frontend/SKILL.md ~/.claude/skills/design-frontend/SKILL.md

Depois de copiar, dá uma última lida no arquivo: ele tem que estar exatamente como saiu do passo 2, regra pura, sem caminho de pasta

O erro comum deste passo: copiar antes de terminar a limpeza do passo 2

Aí src/components/ui do projeto antigo viaja junto pra dentro da skill pessoal, e o chato é que o sintoma aparece só semanas depois, num projeto que nem tem essa pasta

Tome cuidado com isso!

4. Reescreva a parte específica em .claude/skills e commite

Agora volta no SKILL.md do projeto e escreve nele só a coluna do específico, aquela que você guardou no rascunho do passo 2

Caminho de pasta, design system interno, nome das libs daquele repo: é isso que fica no repositório

git add .claude/skills/design-frontend/SKILL.md
git commit -m "skill de frontend do projeto: convenções locais"

Skills de projeto são compartilhadas com o time via git, por estarem versionadas junto com o código

É literalmente isso: quem clonar, recebe

O erro comum deste passo: colocar a pasta no .gitignore "pra não poluir o repo"

Aí ninguém do time recebe nada e a skill vira coisa sua, de novo

5. Valide os dois lados

Dá pra validar o frontmatter dos arquivos SKILL.md com o comando claude plugin validate apontado para a pasta de skills:

claude plugin validate .claude/skills
claude plugin validate ~/.claude/skills

Quando a validação passa, o Claude Code imprime uma confirmação de validação aprovada, com aviso de warnings quando houver

Leia os warnings, não ignore, eles costumam apontar exatamente o campo que você digitou errado

O erro comum deste passo: validar só a pasta de projeto e esquecer a pessoal

São dois escopos, são duas checagens

6. Vários repositórios? Empacote como plugin

Quando a mesma regra precisa chegar em muitos projetos, a pasta pessoal resolve pra você, mas não pro resto do mundo

Aí entra o plugin

Em um plugin do Claude Code, as skills ficam em skills/<nome-da-skill>/SKILL.md na raiz do plugin, e apenas o plugin.json vive dentro de .claude-plugin/:

meu-plugin-frontend/
  .claude-plugin/
    plugin.json
  skills/
    design-frontend/
      SKILL.md

E se você não quiser escrever manifesto? O plugin.json é opcional: sem ele, o Claude Code descobre os componentes pelo layout de diretórios do plugin

Só lembra que skills vindas de plugin são sempre namespaced, no formato /nome-do-plugin:nome-da-skill, pra evitar conflito entre plugins com skills de mesmo nome

O prefixo vem do campo name do plugin.json

O erro comum deste passo: jogar a pasta skills/ pra dentro de .claude-plugin/

Lá dentro vive o manifesto, o resto fica na raiz

7. Distribua com um marketplace

Para distribuir um conjunto de skills, cria-se um arquivo .claude-plugin/marketplace.json na raiz do repositório, definindo nome do marketplace, owner e a lista de plugins com seus sources:

{
  "name": "skills-do-time",
  "owner": { "name": "Time de Frontend" },
  "plugins": [
    {
      "name": "meu-plugin-frontend",
      "source": "./meu-plugin-frontend"
    }
  ]
}

Marketplaces aceitam múltiplos tipos de source, incluindo repositórios git e caminhos locais

O caminho local é ótimo pra testar antes de publicar, e depois você troca pelo git

Do lado do time, são dois comandos:

/plugin marketplace add <repositório-do-marketplace>
/plugin marketplace update

O erro comum deste passo: publicar sem validar

Antes de submeter um plugin, a recomendação é rodar claude plugin validate ./seu-plugin na pasta do plugin, porque o pipeline de revisão roda a mesma checagem

Melhor descobrir o erro na sua máquina que na revisão, né? 😀

8. Tire o atrito do onboarding

Ninguém do time vai lembrar de rodar comando de marketplace na segunda-feira

Então pré-configure: dá pra deixar o marketplace e os plugins do time no .claude/settings.json do projeto, usando extraKnownMarketplaces e enabledPlugins

O enabledPlugins usa o formato nome-do-plugin@nome-do-marketplace com valor true ou false:

{
  "enabledPlugins": {
    "meu-plugin-frontend@skills-do-time": true
  }
}

Os marketplaces configurados no .claude/settings.json do projeto são adicionados sem prompt extra depois que a pessoa do time confia na pasta do repositório

O erro comum deste passo: achar que isso funciona antes de a pessoa confiar na pasta

O efeito é condicionado a esse passo, então na dúvida avisa a galera no onboarding

Skill pessoal, skill de projeto ou plugin: qual usar em cada situação

Três cenários, três destinos, e dá pra usar os três ao mesmo tempo:

O plugin ainda tem uma vantagem que a pasta solta não tem: além de skills, ele pode conter outros componentes como agents, hooks, servidores MCP e servidores LSP

Ou seja, o padrão de frontend viaja junto com o resto do ferramental do time

Vale pensar também em quem entra e quem sai do grupo, porque remover alguém do Claude Team levanta exatamente a pergunta de onde cada coisa estava guardada

E por que não jogar tudo no CLAUDE.md?

Pergunta justa, e a resposta é sobre contexto

O CLAUDE.md é carregado em toda conversa, enquanto a skill é carregada apenas quando o pedido combina com ela

Skills carregam sob demanda: inicialmente só o name e a description entram no contexto, e o conteúdo completo entra quando a skill combina com o pedido

Por isso regra longa de frontend (aquele documentão de convenção de componente, estado, acessibilidade) sai MUITO melhor como skill

No CLAUDE.md ela pesa em toda conversa, inclusive naquela que só mexe em script de build

Na prática: 6 skills que rodam em todos os projetos

Eu mantenho um conjunto fixo de skills que aplico em praticamente todos os projetos novos que começo com o Claude Code, usando as mesmas em sequência, do planejamento até o código

No vídeo eu mostro 6 delas, e o repositório de skills que eu uso saiu instalado com 2 comandos ali na tela mesmo

Depois disso, o plano rodou no meu projeto e fechou 14 tarefas concluídas

O caso que casa direto com o assunto deste post é o do app de controle de despesas: ele ficou funcionando, mas a interface tinha ficado genérica, sem identidade nenhuma

Aí eu ativei a skill de design de frontend no mesmo projeto já pronto e pedi o redesenho com um prompt descritivo: visual clean e moderno que passasse confiança financeira, modo escuro, sensação de controle sem sobrecarga

Comparando antes e depois, a mudança foi grande na tipografia, o estilo ficou mais sóbrio e os elementos visuais bem mais consistentes

Mas se liga: o resultado varia MUITO conforme o prompt

Na minha avaliação, boa parte das reclamações de que a IA não entrega o que a pessoa quer vem de prompt mal escrito, não da ferramenta

Eu prefiro usar uma skill de design já pronta em vez de sair instalando pacote de terceiro, e essa é uma das que mais gosto de repetir nos projetos

Existe mais de uma opção de skill de frontend por aí, então testa e escolhe a tua, a que eu uso já resolve a maior parte dos casos que caem na minha mão

E também dá pra criar skills próprias (custom skills), justamente porque cada projeto tem necessidade diferente

Nada disso é bala de prata, beleza? É o que funciona no meu dia a dia, não garantia

Repara no ponto que conecta com o post: esse conjunto que eu repito não mora em um repositório único, ele vive fora dos projetos e desce pra cada um deles

Esse é exatamente o movimento que os passos acima ensinam

No vídeo você vê as skills sendo instaladas, o plano sendo montado e o antes e depois da interface do app depois da skill de design entrar em ação

Conclusão

A regra de bolso cabe em uma linha: genérico sobe para a pasta pessoal ou para o plugin, específico fica versionado no repositório

Tudo o que é convenção de componente, estado e acessibilidade vai pra ~/.claude/skills e te acompanha em todo projeto

Tudo o que é caminho de pasta, design system interno e nome de lib fica em .claude/skills, commitado, chegando no time junto com o código

E quando isso precisa escalar pra vários repositórios, empacota como plugin e distribui por marketplace, de preferência já pré-configurado no .claude/settings.json pra ninguém precisar decorar comando

Próximo passo concreto, pra fazer hoje: abre o teu SKILL.md, marca cada instrução como genérica ou específica, roda claude plugin validate nas duas pastas e commita a parte de projeto

Aí o time já usa amanhã 🙂

até o próximo post!