Skill de design serve para vários projetos ou tem que refazer em cada repositório?

Ninguém merece manter cinco cópias do mesmo padrão de interface espalhadas por cinco repositórios

Fala aí, beleza? Essa dúvida aparece sempre que alguém escreve a primeira skill de design caprichada: hierarquia visual, espaçamento, critério de acessibilidade, tom da interface, tudo redondinho

Aí abre o projeto novo e vem a pergunta: copia e cola de novo? mantém uma versão por repo? e quando mudar a regra, sai atualizando um por um?

A resposta curta é que quase nunca você reescreve o conteúdo

O que muda é ONDE o arquivo mora, e é isso que decide quem enxerga a skill, se ela viaja com o clone do projeto e quem ganha quando dois arquivos têm o mesmo nome

Bora destrinchar isso?

Pessoal, projeto ou plugin: onde guardar a skill de design

O Claude Code lê skills de níveis diferentes, e cada nível responde uma pergunta diferente de reaproveitamento

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

E quando o mesmo nome aparece em mais de um lugar?

A ordem de precedência é enterprise, depois pessoal, depois projeto

Na prática: se você tem uma skill deploy em ~/.claude/skills e o repositório também tem uma deploy em .claude/skills, quem roda é a pessoal

Skill vinda de plugin é o caso tranquilo, porque ela é namespaced

Um meu-plugin/skills/deploy/SKILL.md vira /meu-plugin:deploy e convive numa boa com a deploy do projeto, sem brigar por nome

A regra prática de escolha fica assim:

• é o SEU jeito de fazer interface, que você quer em qualquer projeto? escopo pessoal
• é regra daquele produto, que o time inteiro precisa receber? escopo de projeto, commitado
• é padrão que precisa atravessar times e organizações? plugin de marketplace

Quando o padrão de interface viaja e quando ele é específico demais

Aqui mora a parte que quase ninguém separa, e é justamente ela que gera manutenção duplicada

Tem coisa em design que é MÉTODO, e método viaja liso entre projetos:

• princípios de layout e de hierarquia visual
• critérios de acessibilidade que você não abre mão
• tom da interface (sóbrio, divertido, denso, respirado)
• checklist de revisão de tela antes de dar por pronto
• o jeito de justificar uma decisão visual em vez de só "ficou bonito"

E tem coisa que é DICIONÁRIO daquele produto, e dicionário não viaja:

• tokens de cor, tipografia e espaçamento daquele design system
• nomes dos componentes internos e o que cada um já resolve
• convenção de pastas e de nomenclatura daquele repositório
• as exceções históricas ("esse botão aqui é legado, não copie ele")

A fatura chega quando as duas camadas viram um arquivo só

Aí qualquer ajuste de método obriga a mexer em N repositórios, e qualquer token novo te empurra a editar a skill pessoal que não tem nada a ver com aquele produto

O corte que resolve é simples: o método vai pra skill pessoal em ~/.claude/skills, o dicionário vai pra skill de projeto em .claude/skills e é commitado, porque a de projeto viaja junto com o clone do repo

É a mesma lógica de quem reaproveita templates prontos de automação no n8n em vez de montar tudo do zero: você reusa o esqueleto e troca só o que é do cliente

Se você conhece a ideia de biblioteca compartilhada versus configuração local, é exatamente isso, só que em markdown 🙂

Um teste à parte: o que o Open Design me mostrou sobre o que viaja

Antes de seguir, um aviso pra ninguém misturar as coisas: o Open Design é OUTRA ferramenta, não é uma skill do Claude Code

Ele não usa o mecanismo de SKILL.md que a gente está destrinchando aqui, tem instalação e interface próprias, então nada do fluxo dele serve como passo pra configurar skill

Citei ele porque a lição de reaproveitamento bateu certinho com o assunto do post

Criei projetos diferentes dentro da MESMA base: primeiro uma landing page de SaaS, depois uma apresentação em slides sobre o mesmo projeto

E é aí que a ficha cai sobre o que viaja e o que não viaja

O que se manteve foi a base: ter design system pronto me poupou de planejar tipografia e paleta de cores do zero a cada projeto novo

O que precisou ser decidido por projeto foi a escolha do design system e o nível de fidelidade, que acontecem na criação de cada projeto e não ficam presas ao projeto anterior

Teve ajuste de contexto também: configurei o idioma pra português, porque na minha experiência essas ferramentas tendem a gerar conteúdo em inglês por padrão

E durante a geração a ferramenta fez perguntas de contexto de marca e de direção visual antes de entregar a primeira versão, ou seja, o específico do produto entra na conversa, não no padrão reaproveitado

Traduzindo isso pro mundo das skills do Claude Code: o que se manteve é o que merece virar skill pessoal, e o que mudou a cada projeto é o que merece virar skill de projeto

No vídeo abaixo eu mostro esse fluxo inteiro na prática, do setup até o projeto pronto:

Como distribuir a mesma skill de design sem manter cópias

Agora o passo a passo do que dá pra fazer hoje, só com o que está documentado

1. Crie a pasta da skill com um SKILL.md dentro

Toda skill é uma pasta com um arquivo SKILL.md, formado por frontmatter YAML entre os marcadores --- e o conteúdo em markdown

---
name: design-review
description: Revisa telas e componentes de interface aplicando hierarquia visual, espaçamento e acessibilidade. Use ao criar ou revisar UI.
---

## Como revisar uma tela

1. Confira a hierarquia visual antes de olhar cor
2. Valide contraste e alvo de toque
3. Justifique cada decisão em uma frase

O erro comum aqui é jogar as instruções num arquivo solto sem a pasta e sem o frontmatter, e depois estranhar que nada acontece

2. Escreva o description pensando em GATILHO, não em título

O campo description do frontmatter é o que o Claude usa pra decidir se a skill é relevante pro pedido

Escreva o que ela faz E quando usar

O erro comum é description: skill de design, que não diz ao modelo em que momento ela serve

3. Decida o escopo movendo o arquivo, não reescrevendo ele

Se é o seu método, vai pra ~/.claude/skills e passa a valer em todos os seus projetos

Se é regra daquele produto, vai pra .claude/skills na raiz do repositório

O erro comum é deixar tudo no pessoal e depois descobrir que o time nunca recebeu a regra

4. Commite .claude/skills pro time receber ao clonar

git add .claude/skills
git commit -m "add skill de design do projeto"

Skills de projeto entram no controle de versão e chegam a quem clona o repo, é esse o mecanismo de distribuição pro time

O erro comum é a pasta cair no .gitignore junto com outras configs locais, e aí a skill nunca sai da sua máquina

5. Pra atravessar projetos e times, empacote como plugin de marketplace

Um marketplace de plugins do Claude Code é um repositório git (ou um diretório local) com o arquivo .claude-plugin/marketplace.json, que cataloga os plugins e diz de onde buscar cada um

Ele suporta fontes em repositório git e caminhos locais, com descoberta centralizada e atualização

O erro comum é confundir marketplace com plugin instalado: ter o marketplace não instala nada, a instalação é individual

6. Instale pelo /plugin e teste com um exemplo oficial

O comando /plugin abre o navegador de plugins pra descobrir e instalar a partir dos marketplaces, e a instalação direta segue o formato /plugin install nome-do-plugin@nome-do-marketplace

O marketplace claude-plugins-official é mantido pela Anthropic e já vem disponível, sem precisar adicionar na mão

Quer ver de perto como uma skill de design distribuída assim se parece? tem o plugin oficial frontend-design, cuja skill vive em plugins/frontend-design/skills/frontend-design/SKILL.md no repositório anthropics/claude-code

/plugin install frontend-design@claude-plugins-official

O erro comum é tentar instalar sem o @nome-do-marketplace e ficar batendo cabeça com o nome do plugin sozinho

E tem um bônus de portabilidade: as Agent Skills usam o mesmo formato nos apps do Claude, no Claude Code e na API, e o formato foi publicado como padrão aberto

No Agent SDK a lógica é a mesma, skills são artefatos de sistema de arquivos, cada uma na sua pasta com um SKILL.md em .claude/skills/<nome>/SKILL.md

Problemas comuns ao reaproveitar a skill em vários repositórios

A skill do projeto simplesmente não roda

Sintoma: o repo tem a regra certinha em .claude/skills, mas o comportamento que aparece é o antigo, o seu de sempre

Causa: existe uma skill de mesmo nome no seu escopo pessoal, e a precedência é enterprise, depois pessoal, depois projeto

Com uma deploy em ~/.claude/skills e outra em .claude/skills, roda a pessoal

Correção: renomeie um dos lados, ou tire do pessoal aquilo que já virou regra do produto

Prevenção: combine um prefixo pros nomes de projeto e deixe o pessoal com nomes claramente seus

Se é padrão que precisa vencer em qualquer lugar sem essa disputa, empacote como plugin, porque skill de plugin usa namespace e não colide

A skill existe mas o Claude nunca lembra dela

Sintoma: você pede uma tela, ele entrega do jeito dele, e a sua skill de design fica lá quietinha

Causa: no início da sessão o Claude enxerga só nome e descrição das skills disponíveis, e carrega o SKILL.md inteiro apenas quando decide que aquilo é relevante

Se o description não diz quando a skill serve, ela não é acionada

Correção: reescreva o description dizendo o que a skill faz e em que situação usar, com as palavras que você realmente usa no pedido

Prevenção: trate o description como a parte mais importante do arquivo, não como enfeite do frontmatter

Tome cuidado com descrição genérica: ela é o gatilho de relevância, e conteúdo bom atrás de descrição vaga é conteúdo que nunca carrega

O comando e a skill têm o mesmo nome

Sintoma: você chama /deploy esperando o comando de sempre e vem outro comportamento

Causa: se uma skill e um comando têm o mesmo nome, a skill tem precedência

Com .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md no mesmo projeto, /deploy executa a skill

Correção: renomeie um dos dois, e prefira o nome mais específico pro que for mais raro de usar

Prevenção: antes de criar skill nova, dê uma olhada nos comandos que o repositório já tem, principalmente nos nomes curtinhos tipo build, test e deploy

Conclusão

Então, respondendo direto: não é refazer a skill de design em cada repositório

É escolher o nível certo e separar o que é MÉTODO do que é dicionário do produto

Método (princípios, hierarquia, acessibilidade, checklist de revisão) sobe pro escopo pessoal em ~/.claude/skills e passa a valer em qualquer projeto seu

Dicionário (tokens, componentes internos, convenções daquele repo) fica em .claude/skills, commitado, chegando a quem clona

E quando o padrão precisa atravessar times, ele vira plugin de marketplace, com namespace próprio e sem briga de nome

Próximo passo sugerido: pega a sua skill atual, corta ela em duas nessas linhas, e testa em dois projetos bem diferentes pra ver o que continua fazendo sentido e o que era específico demais pra viajar

É um teste de dez minutos que economiza meses de manutenção duplicada 😀

Até o próximo post!