Como saber se a skill de frontend design está sendo aplicada no Claude Code?

Fala aí, beleza? Você escreveu a sua skill de design, caprichou nas regras, rodou o prompt… e a tela que saiu tem exatamente a mesma cara de sempre 🙂

Aí bate a dúvida: será que o Claude leu aquilo? Ou leu e ignorou?

E essa é a parte que confunde a maioria: skill acionada e skill obedecida são DUAS coisas diferentes

Dá pra ela ser descoberta, entrar no contexto, ser acionada e mesmo assim o modelo voltar pro padrão dele na hora de escrever CSS

Então bora separar o diagnóstico em três camadas: sinais no resultado, sinais de configuração e prova objetiva de que a skill rodou

Sintoma: a tela saiu com cara de página gerada

Você abre o resultado no navegador e sente aquele déjà vu

Os sinais são bem concretos, e o melhor é que dá pra checar direto no código, sem adivinhação:

• <code>font-family</code> caindo em Arial, Inter, Roboto ou um system stack qualquer
• uma única palavra do headline destacada em itálico, negrito ou numa cor diferente do resto
• nenhum elemento de assinatura, nada que faça a página ser lembrada por alguma coisa
• nenhuma justificativa: o agente foi direto pro código, sem dizer por que escolheu o que escolheu

Esses dois primeiros não são implicância minha, se liga: o SKILL.md oficial do frontend-design manda escolher tipografia deliberadamente e cita justamente Arial, Inter, Roboto e system stacks como sinal de pensamento default

E acentuar uma única palavra do título está na lista de tells tipográficos a evitar, por ser um dos sinais mais comuns de página gerada

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

Causa provável:

Duas hipóteses, e elas pedem tratamentos diferentes

Ou o corpo do SKILL.md nunca foi lido (problema de descoberta ou de acionamento, e isso é assunto das próximas seções)

Ou foi lido e o modelo voltou pro padrão dele no meio do caminho, que é o caso mais chato de perceber

Solução: peça o plano ANTES do código

O frontend-design exige um plano antes de construir, com um sistema compacto de tokens

E o plano tem partes nomeadas, o que facilita demais a sua conferência:

• paleta com 4 a 6 valores hex nomeados
• tipografia para 2 ou mais papéis: display com moderação, body complementar e utility pra legendas ou dados
• um conceito de layout
• o signature element, o único elemento pelo qual a página vai ser lembrada

Se a resposta do agente não trouxe NADA parecido com isso antes do primeiro bloco de código, você já tem a sua resposta

Como prevenir:

Exija a revisão do plano contra o brief, do jeito que o próprio SKILL.md oficial define: se alguma parte do plano parecer o default genérico que sairia pra qualquer página parecida, ela deve ser revisada, e a mudança precisa ser declarada com o motivo

Essa declaração é o seu recibo

Vale a mesma lógica pra regras mais miúdas de interface, tipo padronizar botões, erros e estados vazios: regra que não pede declaração explícita é regra que você não consegue auditar depois

Sintoma: o Claude nunca menciona a skill (ela foi descoberta?)

Aqui o cenário é mais radical: a skill simplesmente não existe pro agente

Nenhuma referência, em momento nenhum da sessão

Causas verificáveis:

1. Arquivo fora do lugar

Cada skill mora na PRÓPRIA pasta, com um arquivo <code>SKILL.md</code> dentro:

<pre><code>~/.claude/skills/&lt;nome&gt;/SKILL.md # skill pessoal .claude/skills/&lt;nome&gt;/SKILL.md # skill do projeto </code></pre>

O erro comum deste passo: jogar um <code>frontend-design.md</code> solto dentro de <code>~/.claude/skills</code> e achar que basta o nome bater

2. Frontmatter sem o <code>—</code> na primeira linha

O SKILL.md usa frontmatter YAML entre marcadores <code>—</code>, e o Claude Code só lê esse frontmatter quando o <code>—</code> de abertura é a PRIMEIRA linha do arquivo

Caso contrário, ele trata o arquivo inteiro como conteúdo

<pre><code>— name: minha-skill-de-design description: Usar quando o pedido envolver criar ou revisar interface web, landing page ou protótipo visual —

# Regras de design … </code></pre>

O erro comum deste passo: deixar uma linha em branco, um comentário ou um título antes do <code>—</code>. Já me ferrei com coisa parecida, e o pior é que o arquivo continua bonito de ler, então você não desconfia dele

3. Skill criada ou editada no meio da sessão

A varredura que descobre as skills roda uma vez, no início da sessão

Ou seja: skill nova (ou editada) só passa a valer depois de reiniciar

É o clássico de escrever a skill numa aba, voltar pro Claude Code que já estava aberto e testar na hora

Solução:

1. Confira o caminho e garanta a pasta própria com <code>SKILL.md</code> dentro
2. Confira se o <code>—</code> de abertura é mesmo a primeira linha do arquivo
3. Reinicie a sessão e teste de novo

Como prevenir:

Pra quem vive mexendo em skill, existe o hook <code>SessionStart</code> com <code>reloadSkills: true</code>, que faz o Claude Code reescanear os diretórios de skills depois que o hook termina, disponibilizando na sessão atual as skills instaladas por ele

Muito útil pra fluxo em que a skill é instalada junto com o projeto

Sintoma: a skill existe, aparece, mas nunca é acionada sozinha

Esse é diferente do anterior, se liga nisso

Aqui a skill está instalada, tudo no lugar, e mesmo assim o Claude ignora ela nos pedidos de interface

Causa: a description é quem decide

No início da sessão apenas o <code>name</code> e a <code>description</code> do frontmatter de cada skill entram no contexto

O corpo do SKILL.md só é lido quando a skill é acionada

Então é isso: aquelas suas linhas e linhas de regra de tipografia não influenciam NADA na decisão de acionar, porque o modelo nem viu elas ainda

Quem decide é a description. Se ela não diz em que situação usar, o modelo não conecta o seu pedido com a skill

Outra causa: o campo que bloqueia a auto-invocação

O frontmatter aceita os campos <code>name</code>, <code>description</code>, <code>disable-model-invocation</code> e <code>allowed-tools</code>

E <code>disable-model-invocation: true</code> impede que o próprio Claude acione a skill sozinho, deixando o acionamento só pro usuário

Se esse campo está lá, não tem redação de description que salve

Solução: force o acionamento pra isolar o problema

Uma skill pode ser invocada manualmente pelo usuário como slash command, com o nome dela:

<pre><code>/nome-da-skill </code></pre>

Esse teste é ouro porque separa duas coisas que a gente costuma confundir

Se você força a skill e o resultado melhora: o conteúdo está bom, o problema é a description não estar puxando o gatilho

Se você força e o resultado continua genérico: a description está ok, quem precisa de conserto é o corpo da skill

Como prevenir:

Escreva a description em termos de SITUAÇÃO de uso, não de identidade da skill

Nada de "skill de design" e ponto. Diga quando ela deve entrar, que tipo de pedido dispara ela, que tipo de artefato ela cobre

E revise esse campo antes de sair culpando o corpo da skill 😀

Sintoma: você não quer adivinhar, quer prova de que a skill rodou

Tem um momento em que o resultado melhorou, mas você fica com aquela pulga atrás da orelha: foi a skill ou foi sorte no prompt?

Pergunta legítima, e ela é a mesma que aparece quando você tenta descobrir se a skill de marketing está funcionando: sem medida, tudo vira impressão

Causa: ainda não tem painel pra isso

Não existe hoje um painel de analytics de invocação de skills no Claude Code, e a comunidade já pediu: tem issue aberta no repositório <code>anthropics/claude-code</code> pedindo justamente rastreamento e analytics de invocação de skills

Então bora usar o que existe

Solução: telemetria, a prova real

Essa aqui é a resposta objetiva de verdade, a única que diz QUAL skill foi acionada

O Claude Code registra o evento de telemetria <code>claude_code.skill_activated</code> quando uma skill é acionada, tanto pela ferramenta Skill quanto por slash command do usuário

E o evento carrega o atributo <code>skill.name</code>, ou seja: dá pra saber exatamente qual skill entrou

A telemetria é exportada via OpenTelemetry e precisa ser habilitada por variável de ambiente:

<pre><code>CLAUDE_CODE_ENABLE_TELEMETRY=1 </code></pre>

Pra ver os eventos, o <code>OTEL_LOGS_EXPORTER</code> também precisa estar configurado

O erro comum deste passo: habilitar só o <code>CLAUDE_CODE_ENABLE_TELEMETRY</code> e ficar esperando evento aparecer

Checagem de apoio: o <code>/context</code>

O comando <code>/context</code> mostra a repartição do uso da janela de contexto por categoria na sessão atual

<pre><code>/context </code></pre>

É o retrato de como o seu contexto está sendo gasto naquela sessão, o que ajuda a entender o que entrou junto com você na conversa

Mas fique esperto: ele é sinal indireto, não diz qual skill foi acionada durante a conversa. Prova mesmo, só a telemetria

Como prevenir:

Deixe a telemetria habilitada nos projetos em que você REALMENTE depende de skill

Aí a pergunta "será que rodou?" para de ser papo de fé e vira consulta 🙂

O que muda quando a skill realmente assume o volante

Agora o outro lado da moeda: como é a cara de uma skill de frontend design que está mesmo mandando no processo?

No vídeo eu instalei uma skill de design a nível de projeto e fui testando em cima de pedidos diferentes

No primeiro projeto eu nem pedi a skill: só descrevi o protótipo de app iOS que eu queria, e ela carregou sozinha

Mas atenção, porque isso não é garantido: se o agente interpretar o seu pedido como um projeto web comum, você vai precisar ser explícito no prompt pra forçar

O primeiro sinal apareceu na PRÓPRIA resposta do agente, antes de qualquer código: veio um bloco de decisões de design com tipografia, paleta de cores, status bar, dynamic island e animações, além do resumo de telas e navegação

Depois abri no navegador com live server e naveguei pelo protótipo: telas ligadas entre si, tab bar funcionando, player com timer, visual bonito mesmo

E no pedido de slides ficou ainda mais claro o comportamento de skill ativa:

• o agente propôs 3 direções visuais pra eu escolher, cada uma com um resumo de quando faz sentido, e só começou a produzir depois da escolha
• ele parou no meio e deixou 6 slides pendentes, devolvendo perguntas e pontos a confirmar
• colocou 3 placeholders onde faltava dado real do projeto

Sacou o padrão? Skill ativa INTERROMPE

Ela planeja, propõe caminho, declara lacuna e pede confirmação, em vez de cuspir código pronto de primeira

É o oposto exato do sintoma da primeira seção, onde o agente vai direto pro CSS sem justificar nada

Nem tudo foi lindo, pra ser honesto: quando testei as setas do teclado no deck pronto, elas não funcionaram, mesmo eu tendo pedido isso no prompt

Pra slides eu precisei ser mais explícito sobre funcionalidade do que estava acostumado

E teve um detalhe que também é sinal visível no resultado: crédito de marca aparecendo nos artefatos gerados, tanto no player HTML quanto no slide. Fiquei com a suspeita de que venha da própria skill, já que referências assim já foram relatadas em outros pacotes

Ah, e uma dica de bastidor: dá um clear entre um projeto e outro, pra não ficar queimando contexto à toa

Conclusão

Se a sua skill de frontend design parece que não está pegando, siga nessa ordem, beleza?

Primeiro confirme a DESCOBERTA: caminho certo (<code>~/.claude/skills/&lt;nome&gt;/SKILL.md</code> ou <code>.claude/skills/&lt;nome&gt;/SKILL.md</code>), <code>—</code> na primeira linha e sessão reiniciada

Depois confirme o ACIONAMENTO: force com <code>/nome-da-skill</code>, cheque se tem <code>disable-model-invocation: true</code> no caminho e, se quiser prova dura, vá de <code>claude_code.skill_activated</code> com a telemetria ligada

Só então avalie o RESULTADO pelos tells: tipografia default, palavra do título destacada, ausência de signature element, código sem plano antes

E por último ajuste a REDAÇÃO, cada coisa no seu lugar: description pro gatilho, corpo pras regras

Próximo passo que eu recomendo: compare a sua skill com a oficial da Anthropic

O SKILL.md do frontend-design está publicado em <code>anthropics/skills</code>, em <code>skills/frontend-design/SKILL.md</code>, e também vem empacotado como plugin em <code>anthropics/claude-plugins-official</code>, em <code>plugins/frontend-design/skills/frontend-design/SKILL.md</code>

Pra instalar pelo marketplace oficial:

<pre><code>/plugin install frontend-design@claude-plugins-official </code></pre>

Se por algum motivo o marketplace não estiver lá, ele é adicionado com:

<pre><code>/plugin marketplace add anthropics/claude-plugins-official </code></pre>

Ler o SKILL.md oficial como referência de REDAÇÃO vale mais que qualquer checklist, viu? Repara como ele nomeia os tells a evitar e como obriga o agente a declarar o que mudou e por quê

É esse tipo de regra verificável que transforma "acho que a skill rodou" em "a skill rodou, e aqui está a prova"

até o próximo post!