Skill de design para web e app: vale manter uma só ou separar?
Skill de design no Claude Code é só uma pasta com um SKILL.md, então "web e app juntos ou separados" é decisão de arquivo, não de gosto. A parte comum (tokens de cor, tipografia, hierarquia, estados, acessibilidade) é maior do que parece; o que mais gera erro é o específico, tipo alvo de toque, que na web tem WCAG 2.2 pedindo 24×24 px CSS no nível AA, enquanto Apple fala em 44×44 pt e Material em 48×48 dp. Critério curto: mantenha uma skill de design única enquanto o comum pesar mais e o arquivo estiver enxuto; separe quando web e app quase nunca aparecem no mesmo pedido ou o corpo passar de 500 linhas
Tu já tem uma skill de design rodando bonitinho no projeto web, aí entra o app na jogada e bate aquela dúvida: duplico a skill ou estico a que já existe? 🙂
Fala aí, beleza? Essa pergunta parece papo de arquitetura abstrata, mas ela é bem concreta
No Claude Code, uma skill é uma pasta com um arquivo SKILL.md: skills pessoais ficam em ~/.claude/skills/<nome-da-skill>/SKILL.md e skills de projeto em .claude/skills/<nome-da-skill>/SKILL.md
Ou seja, "juntar ou separar" na prática é escolher entre um arquivo ou dois arquivos, cada um com seu frontmatter YAML (onde name e description são obrigatórios)
E isso é ótimo, porque decisão de arquivo tu revisa, mede e desfaz
Formação Claude Code
Domine Claude Code do absoluto zero até o avançado
- 120 aulas
- 4 projetos
- 9h 45min
O que muda de verdade entre web e app (e o que se repete)
Antes de decidir a montagem, vale olhar o que realmente diverge entre as duas superfícies
Porque a resposta muda MUITO quando tu percebe o tamanho real da duplicação
| O que | Web | App (toque) |
|---|---|---|
| Alvo de toque/clique | WCAG 2.2, critério 2.5.8 Target Size (Minimum), nível AA: mínimo 24×24 pixels CSS, com exceções de espaçamento, alvos inline e casos essenciais (o 2.5.5, nível AAA, pede 44×44 px CSS) | Apple HIG recomenda 44×44 pt para controles em iOS e iPadOS; Material Design recomenda no mínimo 48×48 dp, separados por 8 dp ou mais |
| Navegação | Rota, URL, histórico e botão voltar do navegador fazem parte do modelo mental | O caminho vive dentro do próprio app e segue os padrões da plataforma |
| Componentes | Componentes do seu design system em HTML e CSS | Componentes nativos da plataforma (ou do framework escolhido), com comportamento próprio |
| O que se repete | Tokens de cor, tipografia, escala e hierarquia, tom de escrita da interface, regras de estado (vazio, carregando, erro) e princípios de acessibilidade | Igualzinho, é o mesmo conteúdo |
Olha a última linha com carinho
A maior parte da sua skill de design provavelmente é a linha de baixo, não as de cima
Só que as linhas de cima são justamente as que estragam entrega: uma regra de alvo de toque de app aplicada numa tabela densa de web (ou o contrário) sai errado e ninguém percebe na hora
Skill única x skills separadas: comparação direta
Agora sim, a comparação que interessa, critério por critério
| Critério | Skill única (web + app juntos) | Skills separadas (uma por superfície) |
|---|---|---|
| Tamanho do corpo | Soma tudo e engorda rápido; a recomendação oficial de autoria é manter o SKILL.md abaixo de 500 linhas e, acima disso, quebrar em arquivos referenciados | Cada arquivo fica menor e mais fácil de manter enxuto |
| Precisão do acionamento | Uma description só (limite de 1024 caracteres) tem que cobrir os dois mundos, e é exatamente esse texto que o Claude compara com o pedido pra decidir se aciona | Duas descriptions, cada uma dizendo o que faz e quando usar, sem disputar espaço |
| Consumo de tokens | O corpo carrega inteiro, mesmo quando o pedido é só de uma superfície | A documentação de boas práticas orienta que, quando os contextos são mutuamente exclusivos ou raramente usados juntos, manter os caminhos separados reduz o uso de tokens |
| Manutenção do que é comum | Ponto forte: token de cor muda em um lugar só | Ponto fraco: risco de as duas versões desandarem com o tempo |
| Risco de regra cruzada | Maior: as duas regras estão no mesmo contexto e podem se misturar | Menor: cada skill fala de uma superfície só |
Repara que não tem coluna vencedora
Os dois primeiros e o terceiro critério puxam pra separar; o quarto puxa forte pra manter junto
O quinto critério é o que costuma decidir na prática, porque erro silencioso de interface é caro
Vale considerar também quantas skills tu já tem ativas antes de sair criando mais uma, já que toda skill disponível entra com sua description no contexto
Quando cada montagem faz sentido
Três cenários bem diferentes, e a resposta muda em cada um
Cenário 1: uma superfície manda no projeto
Site ou app único, time pequeno, e a esmagadora maioria dos pedidos cai numa superfície só
Aqui skill única resolve, sem drama
O pouquinho de regra da outra superfície entra como uma seção curta dentro do mesmo SKILL.md, e o arquivo continua enxuto
Começar simples é o certo: skill que ninguém mantém vira documentação morta
Cenário 2: web e app convivendo, pedidos que não misturam
Produto com as duas superfícies vivas, mas o pedido do dia é "ajusta a tela de checkout no app" ou "revisa o dashboard web", quase nunca os dois juntos
Esse é o caso clássico de contexto mutuamente exclusivo
Duas skills, e o segredo está na description de cada uma: ela precisa dizer o que a skill faz E quando usar, porque é o gatilho de acionamento
Description vaga tipo "regras de design do produto" nas duas é pedir pra dar ruim, o Claude não tem como escolher
Cenário 3: design system compartilhado por vários projetos
Aqui o desenho muda: uma base comum com os fundamentos (tokens, tipografia, tom, estados, acessibilidade) e skills por superfície com as regras específicas
Dá pra apostar na composição, porque skills são componíveis: o Claude identifica quais são necessárias e coordena o uso de várias na mesma tarefa
Se tu distribui isso via plugin, o namespace resolve o conflito de nome, já que skill de plugin usa o formato plugin-name:skill-name (e o comando /plugin abre o navegador de plugins no terminal)
Tome cuidado com uma pegadinha: quando existem skills com o MESMO nome em níveis diferentes, a skill pessoal (~/.claude/skills/) tem precedência sobre a de projeto (.claude/skills/)
Ou seja, aquela skill pessoal que tu criou meses atrás pode estar silenciosamente ganhando da skill do repositório
Se esse é o teu caso, dá uma olhada em como reaproveitar a skill entre projetos antes de duplicar arquivo
Veredito: o critério de decisão em uma linha
Separe quando web e app forem contextos que raramente aparecem no mesmo pedido, ou quando o corpo do SKILL.md passar do tamanho recomendado de 500 linhas
Mantenha junto enquanto a parte comum for maior que a parte específica e o arquivo continuar enxuto
É isso, sem mistério e sem fórmula mágica
E tem um detalhe que tira o peso da decisão: ela é reversível
Começar com uma skill de design única e dividir depois custa pouco, porque o conteúdo já está escrito em arquivo, é recorte e cola em duas pastas com dois frontmatters
O caro é o contrário: manter duas skills desde o dia zero pra um produto que ainda nem definiu direito o que é regra de superfície
Próximo passo
Ação pra hoje, bem direta:
- Abre o teu SKILL.md atual e mede o tamanho do corpo, comparando com as 500 linhas recomendadas. O erro comum aqui é medir só "no olho": um arquivo cheio de exemplo longo estoura rápido sem parecer grande
- Marca cada trecho com dois rótulos: comum (tokens, tipografia, hierarquia, tom, estados, acessibilidade) ou de superfície (alvo de toque, navegação, componentes). Se a coluna "de superfície" ficar magrinha, tu já tem tua resposta
- Reescreve a description pensando no gatilho: o que a skill faz e quando usar, dentro do limite de 1024 caracteres. O erro comum é escrever description bonita de README, que descreve mas não diz QUANDO acionar
- Confere o name: máximo 64 caracteres, só letras minúsculas, números e hífens
Depois de alguns dias de uso real, volta e observa uma coisa só: o Claude está acionando a skill certa pro pedido certo?
Se estiver acionando de menos, o problema costuma estar na description
Se estiver misturando regra de app em tela de web, aí sim é hora de separar
Bora testar e ver no que dá… até o próximo post! 😀
Perguntas frequentes
Se eu tiver uma skill de design pessoal e outra de projeto com o mesmo nome, qual delas o Claude Code usa?
A skill pessoal, guardada em ~/.claude/skills/, tem precedência sobre a skill de projeto que fica em .claude/skills/. Isso vale mesmo quando os arquivos SKILL.md têm nomes idênticos, então vale conferir os dois lugares antes de duplicar algo.
Quantas linhas o SKILL.md de uma skill de design pode ter antes de precisar dividir o conteúdo?
A recomendação oficial de autoria é manter o corpo do SKILL.md abaixo de 500 linhas. Passando disso, o ideal é quebrar o conteúdo em arquivos separados e referenciá-los a partir do SKILL.md principal.
Quais campos são obrigatórios no frontmatter de uma skill de design?
O frontmatter YAML do SKILL.md exige dois campos: name e description. O name aceita até 64 caracteres, só letras minúsculas, números e hífens; a description aceita até 1024 caracteres e não pode ficar vazia.
Dá pra usar a skill de design do site e a do app na mesma tarefa?
Sim, skills são componíveis: o Claude identifica quais são necessárias para o pedido e coordena o uso de várias no mesmo fluxo. Por isso uma base comum de fundamentos combinada com skills por superfície funciona bem no cenário de design system compartilhado.
Como instalar uma skill de design pronta feita por outra pessoa?
Skills também podem ser distribuídas via plugins do Claude Code, e o comando /plugin abre o navegador de plugins no terminal. Skills vindas de plugin usam o formato plugin-name:skill-name, o que evita conflito de nome com as suas próprias.
Qual o tamanho mínimo de área de toque para botões em uma skill de design de app?
A Apple recomenda 44×44 pt para controles em iOS e iPadOS, enquanto o Material Design pede no mínimo 48×48 dp com espaçamento de pelo menos 8 dp entre alvos. Já na web, o WCAG 2.2 exige só 24×24 pixels CSS no nível AA (o 44×44 px CSS é do critério AAA).
Matheus Battisti
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 27min
Blog | Mais populares
Como criar uma skill de design para dashboards no Claude Code: regras de gráficos, tabelas e densidade
Aprenda a criar uma skill de design para dashboards no Claude Code: regras de gráficos, cor com significado (WCAG) e densidade de tabelas.
Skill de design serve para vários projetos ou tem que refazer em cada repositório?
Skills Claude Design funcionam em vários projetos ou é preciso recriar em cada repositório? Veja a diferença entre escopo pessoal e escopo de projeto.
Dark mode em skill de design: como escrever as regras de tema sem duplicar tudo
Dark mode em skill de design sem duplicar paleta: contrato semântico, light-dark(), Tailwind v4 e a régua de contraste da WCAG explicados na prática.
