Skill de design em projeto legado: como escrever regras sem quebrar o CSS que já existe?

Pedir uma tela nova e receber, de brinde, um refactor no CSS que ninguém pediu: esse é o medo real de quem mantém projeto legado

Sabe aquela folha de estilo com sobrescrita em cima de sobrescrita, que meia dúzia de telas dependem sem ninguém saber direito? Basta o modelo achar que está "limpando" e o layout de produção vai junto…

Uma skill no Claude Code é uma pasta com um arquivo SKILL.md dentro, que o Claude lê quando o assunto fica relevante. Ou seja: é o lugar certo pra escrever UMA vez a regra "o padrão novo vale só no código novo", em vez de tu repetir isso em todo prompt e torcer pra colar

A ideia aqui não é ensinar o Claude a fazer design bonito

É ensinar ele a saber onde NÃO encostar

O que você precisa antes de escrever a skill

Pouca coisa, mas cada item evita uma dor lá na frente

• Claude Code instalado e rodando na raiz do repositório legado
• Uma decisão de escopo: skill pessoal em ~/.claude/skills/ ou skill de projeto em .claude/skills/
• O inventário mínimo do CSS antigo: quais pastas, arquivos e telas são zona congelada
• O padrão novo minimamente escrito: tokens, espaçamentos, componentes base, o que for

Sobre a decisão de escopo, se liga nisso: a skill de projeto é a que viaja com o repositório e com o time. Skills commitadas em .claude/skills/ do repositório também são carregadas em sessões na nuvem, enquanto o ~/.claude/skills/ da tua máquina local NÃO é lido por sessões de nuvem e pelo Cowork

Traduzindo pro nosso caso: se a regra é "não mexa no CSS legado", ela precisa valer pro time inteiro, não só pra tua máquina. Então é projeto, sem discussão 🙂 (e dá sim pra levar a mesma skill pra outros repositórios, eu volto nisso lá no fim)

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 por que não colocar isso no CLAUDE.md?

Pergunta justa, e a resposta tem a ver com QUANDO cada coisa entra na conversa

O CLAUDE.md dá instruções persistentes de projeto e é lido no início de cada sessão. A skill é carregada dinamicamente, quando o Claude julga que ela ficou relevante

Isso muda o desenho: guardrails curtos e sempre válidos combinam com o arquivo de memória, enquanto o manual gordo do design system (tokens, exemplos, exceções) combina com a skill, que só ocupa espaço quando o papo é de interface. Se tu quiser aprofundar essa escolha, tem um post inteiro sobre skill ou CLAUDE.md pra regras de design

A mecânica por trás disso se chama progressive disclosure e funciona em três níveis: no início da sessão só os metadados (name e description) de todas as skills são pré-carregados, o SKILL.md é lido quando a skill fica relevante, e os arquivos de referência extras só são lidos quando realmente precisam

Guarda esses três níveis na cabeça

Eles explicam quase todo comportamento estranho de skill mais pra frente

Passo a passo: criando a skill de design que não mexe no legado

Bora ver na prática?

1. Criar o diretório da skill e o SKILL.md

Cada skill é um diretório contendo um arquivo SKILL.md. Na raiz do projeto:

mkdir -p .claude/skills/aplicando-design-system
touch .claude/skills/aplicando-design-system/SKILL.md

O erro comum deste passo: criar o arquivo solto em .claude/skills/design.md, sem pasta. A estrutura é diretório + SKILL.md, não um markdown avulso

2. Escrever o frontmatter YAML com name e description

O SKILL.md começa com frontmatter YAML, e os campos mínimos são name e description

---
name: aplicando-design-system
description: Aplica o design system novo em telas e componentes criados do zero neste repositório, e protege o CSS legado de refatoração não solicitada. Use quando o pedido envolver criar tela, criar componente de UI, ajustar layout, estilos, tokens de cor ou espaçamento.
---

Repara em duas coisas que as boas práticas oficiais pedem: a description em terceira pessoa e o nome da skill em forma de gerúndio (o exemplo citado na doc é processing-pdfs). E ela precisa dizer o que a skill faz E quando usar, recheada de termos-chave que aparecem nos pedidos reais

O erro comum deste passo: escrever description: regras de design. Genérico assim, o Claude não tem como saber que a skill serve pro pedido que acabou de chegar, porque no início da sessão ele só enxerga esses metadados

3. Escrever o padrão novo com regra + justificativa

Aqui vem a parte que muita gente pula: as boas práticas oficiais orientam explicar o PORQUÊ de cada regra dentro da skill, pro Claude conseguir generalizar pra casos que a skill não detalhou

## Padrão de estilo em código novo

Use os tokens de `styles/tokens.css` para cor, espaçamento e tipografia.
Porquê: os valores literais espalhados no legado são a razão de o tema
não trocar de forma consistente hoje. Token novo mantém a tela nova
fora desse problema, mesmo em casos não listados aqui.

Não use `!important` em código novo.
Porquê: `!important` no legado existe para vencer seletores antigos de
alta especificidade. Em componente novo e isolado, ele só transfere o
problema para o próximo dev.

É a diferença entre um MUST seco e uma regra que o modelo consegue estender sozinho quando aparece a situação que tu não previu

O erro comum deste passo: lista de proibições sem uma linha de justificativa. Aí o Claude acerta os casos escritos e inventa moda em todo o resto

4. Escrever a seção de áreas intocáveis

Nomeia os caminhos, um por um, e explica o motivo de cada bloqueio:

## Zona congelada (não editar)

- `legacy/css/**` : folhas globais carregadas por telas antigas.
  Alterar um seletor daqui muda telas que não estão no pedido atual.
- `styles/overrides.css` : sobrescritas acumuladas para corrigir
  layout específico de telas antigas. Parecem código morto, não são.
- `templates/admin/**` : marcação antiga acoplada aos seletores acima.

Regra: ao receber um pedido que exigiria tocar nesses caminhos,
PARE e pergunte antes de editar. Descreva o que precisaria mudar e
espere confirmação. Nunca "aproveite para limpar" nada nessa zona.

Agora um aviso importante, e é honestidade em vez de vender mágica: isso é instrução de comportamento, não uma trava

O frontmatter do SKILL.md até aceita um campo allowed-tools, mas existe issue pública aberta no repositório anthropics/claude-code relatando que ele não restringe o acesso a ferramentas (volto nisso lá embaixo, no bloco de sintomas). A skill orienta o comportamento, ela não bloqueia escrita

Ou seja: a zona congelada funciona porque está escrita de forma clara e justificada, não porque o sistema impede fisicamente a edição. Tome cuidado com quem te vender o contrário

O erro comum deste passo: escrever "não mexa no CSS antigo" sem citar caminho nenhum. O modelo não adivinha qual pasta é antiga no teu repositório

5. Definir o gatilho de escopo

A skill precisa saber diferenciar "tela nova" de "tela existente", e o que fazer quando o pedido cruza a fronteira

## Escopo

ARQUIVO NOVO criado nesta sessão: aplique o padrão completo.

ARQUIVO EXISTENTE fora da zona congelada: aplique o padrão apenas nas
linhas que o pedido exige tocar. Não normalize o resto do arquivo.

ARQUIVO NA ZONA CONGELADA: não edite. Proponha a alternativa (novo
arquivo, novo componente, escopo isolado) e pergunte.

Se o pedido do usuário for ambíguo entre criar e migrar, pergunte qual
dos dois antes de escrever qualquer linha.

O erro comum deste passo: assumir que "tela nova" é óbvio. Componente novo dentro de tela antiga é o caso que mais derruba skill mal escrita

6. Mover o detalhe longo pra arquivos de referência

A documentação oficial recomenda manter o corpo do SKILL.md abaixo de 500 linhas e mover o excedente pra arquivos separados. E o checklist pede que as referências a arquivos tenham apenas um nível de profundidade

.claude/skills/aplicando-design-system/
├── SKILL.md
├── tokens.md
└── exemplos-componentes.md

No corpo, tu só aponta:

Tabela completa de tokens: veja `tokens.md`.
Exemplos de componente já migrado: veja `exemplos-componentes.md`.

Lembra do nível 3 do progressive disclosure? Esses arquivos só são lidos quando realmente precisam, então o custo fica onde deve ficar

O erro comum deste passo: fazer referência em cadeia, tipo o SKILL.md aponta pro tokens.md, que aponta pro paleta.md, que aponta pra outro. Um nível, só

7. Rodar a skill e conferir o comportamento

A skill pode ser acionada de duas formas: explicitamente pelo comando de barra ou automaticamente, quando o Claude julga o pedido compatível com a description

Pra testar do jeito determinístico, chama na mão:

/aplicando-design-system

E aqui mora uma pegadinha que pega MUITA gente: em skill pessoal ou de projeto, o comando de barra vem do NOME DA PASTA. O campo name do frontmatter define apenas o rótulo exibido nas listagens de skill

O erro comum deste passo: pasta chamada design, campo name: aplicando-design-system, e tu digitando /aplicando-design-system sem entender por que não aparece. O comando é /design, porque é o nome da pasta que manda

Quando a skill deve agir e quando deve ficar quieta

Esses quatro cenários são o teste de fogo da tua skill de design no Claude Code em base legada. Escreve cada um deles em texto dentro do SKILL.md, com o comportamento esperado do lado

O segundo caso é o mais traiçoeiro

É ali que o modelo olha em volta, vê o CSS antigo do container, acha inconsistente e resolve "padronizar" a tela toda. Deixa isso escrito com todas as letras: o escopo do componente novo é o componente novo, ponto

E o quarto caso merece uma frase explícita na skill, algo como "a migração de tela existente só acontece quando o usuário pedir migração de forma direta, citando a tela". Sem isso, todo pedido vira convite pra refatorar

A skill continua refatorando o CSS antigo: o que checar

Escreveu tudo e mesmo assim o Claude passou o trator? Bora depurar por sintoma

Sintoma: a skill não carrega sozinha

Causa quase certa: description genérica demais

No início da sessão só os metadados são pré-carregados, então a description é a ÚNICA chance da skill ser escolhida. Se ela não tem os termos que aparecem nos pedidos reais (tela, componente, layout, estilo, CSS, tokens), o Claude não conecta

Ajuste: description específica, com termos-chave, em terceira pessoa

Sintoma: a skill carrega na hora errada

Causa: a description diz o que a skill faz, mas não diz QUANDO usar

O checklist oficial cobra as duas coisas na mesma frase. Sem o "quando", a skill vira aposta

Sintoma: a regra é ignorada num caso que tu não previu

Causa: falta a justificativa

É exatamente o que as boas práticas apontam: o porquê é o que permite o modelo generalizar pra situações não detalhadas. Regra seca cobre o exemplo e nada além dele

Ajuste: volta em cada regra e escreve uma linha de motivo. Chato? Um pouco. Resolve? Muito 😀

Sintoma: SKILL.md gigante com a regra crítica soterrada

Causa: corpo acima das 500 linhas recomendadas, com detalhe que deveria estar em arquivo de referência

Ajuste: tokens, exemplos e catálogos vão pros arquivos separados. No corpo ficam escopo, zona congelada e as regras com justificativa

Sintoma: você contou com allowed-tools como trava de segurança

Essa aqui é a armadilha mais perigosa do post

Existe uma issue pública aberta no repositório do Claude Code, de número 37683, relatando que o campo allowed-tools no frontmatter do SKILL.md não restringe o acesso a ferramentas

Enquanto isso estiver em aberto, não construa a tua proteção do legado em cima desse campo. A zona congelada tem que funcionar por instrução escrita, clara e justificada, e a revisão do diff continua sendo tua

Como prevenir tudo isso de uma vez

Revisa a skill pelo checklist oficial antes de compartilhar com o time: description específica e com termos-chave, description dizendo o que faz E quando usar, corpo abaixo de 500 linhas, detalhes em arquivos separados e referências com apenas um nível de profundidade

E tem um atalho massa: a Anthropic mantém um repositório público de Agent Skills em github.com/anthropics/skills, que inclui a skill-creator, um guia pra criar e revisar outras skills. Dá pra usar ela justamente pra revisar a tua

Conclusão

Uma skill de design em projeto legado vale menos pelo que ela manda fazer e mais pelo que ela proíbe

O padrão novo tu escreve uma vez e pronto. A zona congelada, o gatilho de escopo e o "pergunte em vez de refatorar" são o que impede a tela nova de sair cara demais

Próximo passo prático: começa curtinho, cobrindo UMA tela nova. Frontmatter com name e description, o padrão novo com justificativa, os caminhos intocáveis nomeados e o que fazer quando o pedido cruzar a fronteira

Commita em .claude/skills/ do repositório pra o time inteiro herdar a regra sem combinar nada por mensagem, e vai engordando os arquivos de referência conforme o padrão novo cresce

E lembra do que ficou pendente lá em cima: quando a skill amadurecer e tu quiser levar ela pra outros times e outros repositórios, skills também podem ser distribuídas através de plugins do Claude Code

Até o próximo post! =)