Introdução
São 2 da manhã. Você está usando Claude Code para refatorar um componente crítico. Mas algo está errado.
Você está digitando as mesmas instruções que já deu centenas de vezes antes:
- "Antes de fazer alterações, leia o arquivo primeiro"
- "Execute os testes após cada alteração"
- "Crie um commit git com mensagem descritiva"
- "Certifique-se de seguir o estilo de código do projeto"
Toda. Única. Vez.
Então você descobre skills.
Cinco minutos depois, Claude Code automaticamente:
- Lê arquivos antes de editá-los
- Executa testes após cada alteração
- Cria commits formatados apropriadamente
- Segue os padrões do seu projeto
- Nunca comete o mesmo erro duas vezes
Esta é a promessa de Claude Code skills. Mas aqui está o que a documentação não te conta: a maioria dos desenvolvedores descobre skills por acidente. Eles tropeçam em um comando /skill meses depois de começar a usar Claude Code. Nunca aprendem quais skills existem. Definitivamente não constroem as suas próprias.
A diferença entre usar Claude Code como um chatbot chique e desbloquear produtividade 10x não é o modelo em si. É conhecer o sistema de skills.
Depois de construir dezenas de skills personalizadas e usar centenas de existentes—e treinar dezenas de equipes em desenvolvimento orientado a skills—identifiquei os padrões que separam maestria de confusão com skills.
Este artigo não é outro tutorial "o que é uma skill?". É um manual testado em batalha para fazer Claude Code 10x mais capaz sem se repetir nunca mais.
A Mudança de Modelo Mental
Antes de mergulhar em comandos de skill e frontmatter, você precisa entender o que torna skills diferentes de todo outro padrão de interação com IA que você já usou.
O Que Skills Realmente São
Skills não são prompts. São expertise codificada que Claude Code carrega antes de agir.
Pense em skills como memória muscular:
- Antes da memória muscular: Toda vez que você digita, conscientemente pensa sobre cada movimento dos dedos
- Depois da memória muscular: Seus dedos se movem automaticamente, seguindo padrões praticados
Antes de skills: Toda sessão Claude, você repete as mesmas instruções, contexto e correções
Depois de skills: Claude automaticamente segue workflows estabelecidos, padrões de codificação e melhores práticas
A Diferença Crítica
Interação tradicional com Claude Code:
Você: "Corrija o bug de login"
Claude: *lê arquivos aleatórios, faz alterações sem testar*
Você: "Espere, execute testes primeiro"
Claude: *executa testes*
Você: "Agora corrija apropriadamente, seguindo nossos padrões de auth"
Claude: *corrige com testes*
Você: "Crie um commit"
Claude: *cria commit*
Dia seguinte, bug diferente:
Você: "Corrija o bug de logout"
Claude: *lê arquivos aleatórios, faz alterações sem testar*
Você: "Espere, execute testes primeiro..."
As MESMAS correções. Toda. Única. Sessão.
Com skills:
Você: "Corrija o bug de login"
Claude: *invoca automaticamente skill de debugging*
- Lê arquivos relevantes primeiro
- Analisa o problema sistematicamente
- Executa testes antes de mudar qualquer coisa
- Faz correções mínimas e direcionadas
- Verifica que testes passam
- Cria um commit descritivo
Você: *bebe café enquanto Claude segue o workflow inteiro*
Dia seguinte:
Você: "Corrija o bug de logout"
Claude: *segue o mesmo processo sistemático automaticamente*
Você define o workflow uma vez. Claude segue para sempre.
O Que Isso Significa Para Você
Pare de se repetir. Skills codificam suas preferências, workflows e padrões. Você diz uma vez, Claude lembra para sempre.
Pare de corrigir os mesmos erros. Se Claude continua cometendo um erro, crie uma skill. A correção se torna automática.
Pare de trocar contexto. Uma skill para debugging, uma para trabalho de feature, uma para refatoração. Claude sabe qual workflow seguir.
A mudança de frustração para produtividade acontece quando você para de tratar Claude como um desenvolvedor júnior que precisa microgerenciamento e começa a tratá-lo como um colega de equipe que lembra suas preferências.
Padrão 1: Descobrindo Skills Ocultas em 10 Minutos
A maneira mais rápida de entender skills é ver o que já existe. Claude Code vem com dezenas de skills poderosas que a maioria dos desenvolvedores nunca descobre.
O Que Você Está Perdendo
Skills existem para:
- Test-Driven Development - Escreva testes primeiro, depois implementação
- Systematic Debugging - Debug metodicamente, não aleatoriamente
- Brainstorming - Explore requisitos antes de codificar
- Code Review - Revise implementações contra planos
- Git Worktrees - Isole trabalho de feature automaticamente
- Writing Documentation - Crie docs claros e estruturados
- E dezenas mais...
O Processo de Descoberta
1. Liste todas skills disponíveis:
Você verá seções para:
- Skills integradas (enviadas com Claude Code)
- Skills de usuário (suas skills personalizadas)
- Skills de projeto (skills específicas da equipe)
2. Entenda quando usar cada skill:
Skills não são apenas ferramentas—são padrões de acionamento. Cada documento de skill inclui uma seção "quando usar":
superpowers:brainstorming
Use isto ANTES de qualquer trabalho criativo - criar features, construir
componentes, adicionar funcionalidade, ou modificar comportamento.
3. Teste uma skill imediatamente:
Então pergunte:
Preciso adicionar autenticação de usuário a este projeto
Observe Claude:
- Invocar a skill de brainstorming automaticamente
- Fazer perguntas esclarecedoras sobre suas necessidades
- Explorar diferentes abordagens
- Apresentar opções com trade-offs
- Aguardar sua decisão antes de codificar
Você não ensinou Claude este workflow. A skill fez.
A Mina de Ouro de Skills Ocultas
A maioria dos desenvolvedores só descobre 20% das skills disponíveis. Aqui estão as que mudam o jogo que você provavelmente está perdendo:
systematic-debugging
Pare de adivinhar. Debug metodicamente:
- Reproduza o problema primeiro
- Forme hipóteses
- Teste cada hipótese
- Verifique a correção
- Previna regressão
test-driven-development
Testes primeiro, implementação depois:
- Escreva teste falhando
- Implemente solução mínima
- Verifique que testes passam
- Refatore com segurança
verification-before-completion
Nunca alegue "funciona" sem prova:
- Execute comandos reais
- Verifique saída real
- Confirme antes de relatar sucesso
code-reviewer
Obtenha code review automático:
- Verifica contra requisitos originais
- Identifica problemas potenciais
- Sugere melhorias
- Valida padrões
Quando Usar
- Imediatamente após instalar Claude Code (descubra o que está disponível)
- Quando você se pega repetindo instruções
- Antes de começar trabalho complexo (encontre a skill certa primeiro)
- Quando Claude comete o mesmo erro duas vezes
Exemplo Real
Estava debugando uma condição de corrida em um serviço de pagamento. Gastei 2 horas adicionando logging aleatoriamente, reiniciando serviços, verificando diferentes cenários.
Abordagem tradicional (frustrante):
- Claude sugere correções aleatórias
- Eu as testo
- Não funcionam
- Repito 20 vezes
- Eventualmente tropeço na correção
Abordagem com skills (sistemática):
Claude então:
- Me pediu para reproduzir o problema confiavelmente
- Formou 4 hipóteses sobre a causa
- Criou testes direcionados para cada hipótese
- Identificou a condição de corrida exata
- Propôs uma correção com prova de que funciona
- Adicionou testes para prevenir regressão
Tempo: 15 minutos. Taxa de sucesso: 100%.
A skill transformou troubleshooting aleatório em um processo sistemático.
Skills dão a Claude capacidades poderosas. Com poder vem responsabilidade—e riscos que a maioria dos desenvolvedores não antecipa.
O Padrão
Regra 1: Entenda o que uma skill pode fazer
Antes de usar uma skill, leia sua descrição:
cat .claude/skills/skill-name.md
Procure por:
- Quais ferramentas ela tem acesso (Bash, Edit, Write, etc.)
- Quais permissões ela requer
- Para o que ela foi projetada
Bandeira vermelha: Skills com acesso Bash podem executar comandos. Skills com acesso Write podem criar arquivos. Saiba o que você está habilitando.
Regra 2: Skills são instruções, não sandboxes
Uma skill pode dizer a Claude para:
- "Tenha cuidado com operações destrutivas"
- "Pergunte antes de executar comandos arriscados"
- "Verifique antes de deletar arquivos"
Mas se uma skill diz "delete todos arquivos de teste," Claude tentará seguir essa instrução.
Skills são orientação, não restrições.
Regra 3: Revise skills geradas
Quando você pede a Claude para criar uma skill:
Crie uma skill que me ajude a fazer deploy para produção
PARE. Antes de usá-la:
cat .claude/skills/deploy-production.md
Procure por:
- Permissões excessivamente amplas
- Operações destrutivas sem salvaguardas
- Acesso a sistemas sensíveis
- Condições de acionamento pouco claras
Regra 4: Princípio do menor privilégio
Ao criar skills, conceda capacidades mínimas:
❌ Ruim:
Você tem acesso a todas as ferramentas. Use o que precisar.
✅ Bom:
Você tem acesso a:
- Ferramenta Read (apenas ler arquivos)
- Ferramenta Grep (buscar código)
- Ferramenta Bash (para executar testes com `npm test`)
Regra 5: Teste isoladamente primeiro
Skill nova? Teste em um projeto não crítico:
mkdir /tmp/skill-test
cd /tmp/skill-test
git init
claude
Se comportar corretamente, então use em projetos reais.
Padrões Perigosos a Evitar
Skills Excessivamente Autônomas
❌ Perigoso:
Quando o usuário disser "deploy," automaticamente:
1. Execute todos os testes
2. Construa assets de produção
3. Faça push para branch main
4. Deploy para produção
5. Notifique equipe
Faça isso sem pedir confirmação.
✅ Seguro:
Quando o usuário disser "deploy," ajude-os:
1. Verifique que testes passam
2. Verifique que build tem sucesso
3. Mostre plano de deployment
4. PEÇA CONFIRMAÇÃO
5. Só então prossiga com deployment
Skills com Operações Destrutivas
❌ Perigoso:
Para limpar o projeto:
- Delete todos diretórios node_modules
- Remova todos arquivos .log
- Limpe todos diretórios de cache
- Delete dependências não usadas
✅ Seguro:
Para limpar o projeto:
1. MOSTRE o que seria deletado
2. Peça ao usuário para confirmar cada categoria
3. Só delete após aprovação explícita
4. Registre o que foi deletado
Skills que Desviam Verificações de Segurança
❌ Perigoso:
Ao fazer push de código, use --force para sobrescrever proteção de branch.
Ao fazer commit, use --no-verify para pular hooks.
✅ Seguro:
Ao fazer push de código, respeite proteção de branch.
Se push falhar, explique por quê e sugira correções.
Nunca desvie mecanismos de segurança sem solicitação explícita do usuário.
O Checklist de Segurança
Antes de usar ou criar uma skill, pergunte:
-
Qual é a pior coisa que esta skill poderia fazer?
- Se a resposta é "deletar dados de produção," adicione salvaguardas
-
Ela pergunta antes de operações destrutivas?
- Deleções, deployments, publicações devem requerer confirmação
-
Ela pode acessar sistemas sensíveis?
- Bancos de dados de produção, sistemas de pagamento, dados de usuário precisam cuidado extra
-
Ela segue o padrão verification-before-completion?
- Nunca alegue sucesso sem prova
-
Você confiaria em um desenvolvedor júnior com estas instruções?
Quando Usar
- Antes de usar qualquer skill pela primeira vez
- Ao criar skills personalizadas
- Após atualizar skills existentes
- Ao trabalhar em sistemas de produção
- Em ambientes de equipe com skills compartilhadas
Exemplo Real
Minha equipe criou uma skill de "quick deploy" para acelerar nosso processo de deployment. A primeira versão foi:
Quando usuário disser "deploy," automaticamente execute:
1. git add .
2. git commit -m "Deploy"
3. git push origin main
4. Execute script de deployment
Pegamos os problemas durante code review:
- Sem verificação de teste
- Sem passo de confirmação
- Poderia commitar código quebrado
- Poderia deployar builds falhando
- Desviava nosso processo normal de review
Versão revisada:
Quando usuário disser "deploy," ajude-os a fazer deploy com segurança:
1. Verifique que todos testes passam (mostre resultados)
2. Verifique que build tem sucesso (mostre saída)
3. Mostre git status (o que seria commitado)
4. Pergunte: "Testes passam, build tem sucesso. Confirmar deployment?"
5. Só prossiga após "sim" explícito
6. Crie commit apropriado com detalhes de deployment
7. Faça push para branch de deployment (não main)
8. Aguarde CI passar
9. Forneça URL de deployment quando pronto
A skill revisada preveniu 3 deployments quebrados na primeira semana.
Padrão 3: Construindo Sua Primeira Skill Personalizada
Skills da comunidade cobrem workflows comuns. Mas o poder real é desbloqueado quando você constrói skills para SEUS padrões específicos.
Quando Construir Personalizado
Construa uma skill personalizada quando:
- Você repete as mesmas instruções toda sessão
- Você tem workflows específicos do projeto
- Você quer aplicar convenções da equipe
- Skills da comunidade não correspondem suas necessidades
A Skill Mais Simples Possível
Vamos construir uma skill que ajuda Claude a seguir as convenções de mensagem de commit do seu projeto.
Crie o arquivo da skill:
mkdir -p .claude/skills
touch .claude/skills/commit-conventions.md
Escreva a skill:
---
name: commit-conventions
description: Siga o formato de mensagem de commit da nossa equipe
---
Ao criar commits git para este projeto, SEMPRE siga este formato:
## Estrutura de Mensagem de Commit
```text
<tipo>(<escopo>): <assunto>
<corpo>
<rodapé>
Tipos (obrigatório):
- feat: Nova feature
- fix: Correção de bug
- docs: Apenas documentação
- style: Estilo de código (formatação, falta de ponto-e-vírgula, etc.)
- refactor: Mudança de código que não corrige bug nem adiciona feature
- test: Adicionar ou atualizar testes
- chore: Tarefas de manutenção
Escopo (opcional mas recomendado):
- auth: Autenticação
- api: Endpoints de API
- ui: Interface do usuário
- db: Banco de dados
- deploy: Deployment
Exemplos:
feat(auth): adiciona funcionalidade de reset de senha
Implementa fluxo de reset de senha:
- Adiciona endpoint /reset-password
- Envia email de reset com token
- Valida expiração de token
- Atualiza senha seguramente
Closes #123
fix(api): trata caso extremo de perfil de usuário nulo
Anteriormente travava quando usuário não tinha dados de perfil.
Agora retorna estrutura de perfil padrão.
Fixes #456
Regras:
- Linha de assunto: máximo 50 caracteres
- Use modo imperativo ("adiciona" não "adicionou")
- Sem ponto final no assunto
- Corpo: quebra em 72 caracteres
- Explique O QUÊ e POR QUÊ, não COMO
- Referencie issues no rodapé
Quando pedido para fazer commit, pergunte ao usuário:
- Tipo e escopo
- Assunto breve
- Corpo detalhado se a alteração não for trivial
Então formate de acordo com esta convenção.
**Use imediatamente:**
Na sua próxima sessão Claude Code:
```text
Faça alterações para adicionar autenticação de usuário
Claude faz as alterações, então:
Crie um commit para estas alterações
Claude vai:
- Carregar automaticamente a skill commit-conventions
- Analisar as alterações feitas
- Sugerir um commit formatado apropriadamente:
feat(auth): implementa sistema de autenticação de usuário
Adiciona autenticação baseada em JWT:
- Cria endpoints /login e /register
- Implementa geração e validação de token
- Adiciona middleware de autenticação
- Protege rotas sensíveis
Closes #789
Você nunca explicou o formato. A skill fez.
Melhores Práticas para Skills Personalizadas
1. Seja específico sobre condições de acionamento
O frontmatter da skill diz a Claude QUANDO usá-la:
❌ Vago:
---
name: testing
description: Ajuda com testes
---
✅ Específico:
---
name: test-driven-development
description: Use ao implementar qualquer feature ou bugfix, antes de escrever código de implementação
---
2. Inclua exemplos concretos
Claude aprende com exemplos:
❌ Abstrato:
Escreva boas mensagens de commit.
✅ Concreto:
## Bons Exemplos:
feat(api): adiciona middleware de limitação de taxa
## Maus Exemplos:
Atualiza coisas ← Muito vago
Corrigiu um bug no endpoint de API que estava causando problemas ← Muito longo
3. Explique o "porquê" não apenas o "o quê"
## Por que seguimos estas convenções:
1. Mensagens estruturadas habilitam geração automatizada de changelog
2. Prefixos de tipo permitem filtrar commits por categoria
3. Referências de issue vinculam commits ao gerenciamento de projeto
4. Formato consistente torna histórico git legível
Isso não é burocracia—é eficiência da equipe.
4. Torne-a acionável
❌ Passivo:
✅ Acionável:
Antes de marcar qualquer tarefa como completa:
1. Execute a suite de testes: `npm test`
2. Verifique que todos testes passam
3. Mostre a saída do teste
4. Só então alegue que o trabalho está feito
Evidência antes de asserções. Sempre.
5. Inclua um checklist para workflows complexos
## Checklist de Implementação de Feature
Antes de começar qualquer feature:
- [ ] Leia e entenda os requisitos
- [ ] Faça perguntas esclarecedoras se algo não estiver claro
- [ ] Identifique os arquivos que precisam de alterações
- [ ] Verifique padrões existentes na codebase
Durante implementação:
- [ ] Escreva testes primeiro (TDD)
- [ ] Faça alterações mínimas para passar testes
- [ ] Mantenha alterações focadas na feature
- [ ] Evite over-engineering
Antes de conclusão:
- [ ] Execute suite completa de testes
- [ ] Atualize documentação
- [ ] Adicione comentários de código para lógica complexa
- [ ] Crie commit descritivo
Use este checklist para TODA feature, sem exceções.
Estrutura de Arquivo de Skill
Toda skill deve ter:
---
name: skill-name (kebab-case, identificador único)
description: Quando usar esta skill (uma frase clara)
---
# Nome da Skill
Breve introdução explicando o propósito.
## Quando Usar Esta Skill
Condições de acionamento muito explícitas:
- Usuário pede para fazer X
- Antes de fazer Y
- Após completar Z
- Quando situação W ocorre
## Princípios Core
3-5 regras fundamentais que esta skill aplica.
## Passos do Workflow
Processo passo-a-passo:
1. Faça isso primeiro
2. Então faça isso
3. Finalmente faça isso
## Exemplos
### Bom Exemplo
Mostre como é o sucesso.
### Mau Exemplo
Mostre o que evitar.
## Erros Comuns
Antecipe e previna erros:
- Erro 1: Por que está errado, o que fazer em vez disso
- Erro 2: Por que está errado, o que fazer em vez disso
## Verificação
Como confirmar que a skill foi seguida corretamente:
- Verifique X
- Verifique Y
- Confirme Z
Quando Usar
- Você repete a mesma orientação de workflow 3+ vezes
- Seu projeto tem convenções específicas
- Você quer aplicar padrões da equipe
- Você está fazendo onboarding de novos membros da equipe
- Você quer saída consistente entre sessões
Padrão 4: Exemplo do Mundo Real - Skill de Componente Frontend
Vamos construir algo prático: uma skill que aplica os padrões de componente React da sua equipe.
O Problema
Sua equipe tem convenções de componente:
- TypeScript com tipagem estrita
- Styled-components para estilização
- Stories Storybook para todo componente
- Testes unitários com React Testing Library
- Documentação apropriada de prop
- Atributos de acessibilidade
Todo componente deve seguir estes padrões. Mas Claude não os conhece. Então toda sessão, você explica:
- "Use TypeScript"
- "Adicione tipos de prop"
- "Não esqueça o arquivo Story"
- "Adicione atributos de acessibilidade"
- "Escreva testes para interações do usuário"
Repita. Todo. Componente.
A Solução da Skill
Construa uma skill que codifica seus padrões de componente uma vez:
---
name: react-component-patterns
description: Use ao criar ou modificar componentes React neste projeto
---
# Padrões de Componente React
Este projeto segue convenções específicas de componente React. Siga-as para CADA componente, sem exceções.
## Quando Usar
- Criar um novo componente React
- Modificar um componente existente
- Refatorar código de componente
- Revisar implementação de componente
## Estrutura de Componente
Todo componente deve incluir:
1. **Arquivo de definição TypeScript** (`ComponentName.tsx`)
2. **Arquivo Styled-components** (`ComponentName.styles.ts`)
3. **Arquivo Storybook** (`ComponentName.stories.tsx`)
4. **Arquivo de teste** (`ComponentName.test.tsx`)
5. **Arquivo Index** (`index.ts`) para exports limpos
## Template de Componente
### ComponentName.tsx
```typescript
import React from 'react';
import * as S from './ComponentName.styles';
export interface ComponentNameProps {
/** Breve descrição do propósito da prop */
propName: string;
/** Breve descrição, incluindo comportamento padrão */
optionalProp?: number;
/** Descrição de callback com parâmetros */
onAction?: (value: string) => void;
}
export const ComponentName: React.FC<ComponentNameProps> = ({
propName,
optionalProp = 0,
onAction,
}) => {
return (
<S.Container
role="region"
aria-label="Propósito do componente"
>
<S.Content>{propName}</S.Content>
{optionalProp > 0 && (
<S.Badge>{optionalProp}</S.Badge>
)}
</S.Container>
);
};
ComponentName.displayName = 'ComponentName';
ComponentName.styles.ts
import styled from 'styled-components';
export const Container = styled.div`
/* Use tokens de tema, nunca valores codificados */
padding: ${({ theme }) => theme.spacing.md};
background: ${({ theme }) => theme.colors.surface};
border-radius: ${({ theme }) => theme.borderRadius.sm};
`;
export const Content = styled.p`
color: ${({ theme }) => theme.colors.text.primary};
font-size: ${({ theme }) => theme.typography.body.fontSize};
margin: 0;
`;
export const Badge = styled.span`
display: inline-block;
padding: ${({ theme }) => theme.spacing.xs};
background: ${({ theme }) => theme.colors.primary};
color: ${({ theme }) => theme.colors.white};
border-radius: ${({ theme }) => theme.borderRadius.round};
`;
ComponentName.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { ComponentName } from './ComponentName';
const meta: Meta<typeof ComponentName> = {
title: 'Components/ComponentName',
component: ComponentName,
tags: ['autodocs'],
argTypes: {
propName: { control: 'text' },
optionalProp: { control: 'number' },
onAction: { action: 'action triggered' },
},
};
export default meta;
type Story = StoryObj<typeof ComponentName>;
export const Default: Story = {
args: {
propName: 'Example content',
optionalProp: 5,
},
};
export const WithoutBadge: Story = {
args: {
propName: 'No badge shown',
optionalProp: 0,
},
};
export const WithAction: Story = {
args: {
propName: 'Interactive example',
optionalProp: 3,
onAction: (value) => console.log('Action:', value),
},
};
ComponentName.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ThemeProvider } from 'styled-components';
import { ComponentName } from './ComponentName';
import { theme } from '../../theme';
const renderWithTheme = (component: React.ReactElement) => {
return render(
<ThemeProvider theme={theme}>
{component}
</ThemeProvider>
);
};
describe('ComponentName', () => {
it('renderiza com props obrigatórias', () => {
renderWithTheme(<ComponentName propName="Test content" />);
expect(screen.getByText('Test content')).toBeInTheDocument();
});
it('mostra badge quando optionalProp é maior que 0', () => {
renderWithTheme(
<ComponentName propName="Test" optionalProp={5} />
);
expect(screen.getByText('5')).toBeInTheDocument();
});
it('esconde badge quando optionalProp é 0', () => {
renderWithTheme(
<ComponentName propName="Test" optionalProp={0} />
);
expect(screen.queryByRole('badge')).not.toBeInTheDocument();
});
it('chama onAction quando acionado', async () => {
const onAction = jest.fn();
renderWithTheme(
<ComponentName propName="Test" onAction={onAction} />
);
await userEvent.click(screen.getByRole('button'));
expect(onAction).toHaveBeenCalledWith('expected-value');
});
it('tem atributos de acessibilidade apropriados', () => {
renderWithTheme(<ComponentName propName="Test" />);
const container = screen.getByRole('region');
expect(container).toHaveAttribute('aria-label', 'Propósito do componente');
});
});
index.ts
export { ComponentName } from './ComponentName';
export type { ComponentNameProps } from './ComponentName';
Regras Não-Negociáveis
- TypeScript modo strict - Sem tipos
any a menos que absolutamente justificado
- Documentação de prop - Toda prop precisa de comentário JSDoc
- Apenas tokens de tema - Nunca codifique cores, espaçamento ou fontes
- Acessibilidade primeiro - Labels ARIA apropriados, roles e HTML semântico
- Story Storybook - Deve ter pelo menos estado Default
- Cobertura de testes - Teste caminho feliz + casos extremos + interações do usuário
- Named exports - Nunca exporte componentes como default
- DisplayName - Sempre defina para melhor debugging
Checklist de Componente
Antes de considerar um componente completo:
Erros Comuns a Evitar
❌ Estilos inline
<div style={{ color: 'red', padding: '10px' }}>
❌ Documentação de prop faltante
interface Props {
title: string;
}
✅ Props documentadas
interface Props {
title: string;
}
❌ Sopa de div (sem acessibilidade)
<div>
<div onClick={handleClick}>Click me</div>
</div>
<section role="region" aria-label="Área interativa">
<button onClick={handleClick}>Click me</button>
</section>
❌ Testando detalhes de implementação
expect(component.state.value).toBe(5);
✅ Testando comportamento visível ao usuário
expect(screen.getByText('5')).toBeInTheDocument();
Ao Criar um Componente
- Pergunte ao usuário nome e propósito do componente
- Confirme requisitos de prop
- Crie todos os 5 arquivos obrigatórios
- Siga os templates exatamente
- Execute testes para verificar que passam
- Mostre ao usuário onde arquivos foram criados
Ao Modificar um Componente
- Leia o componente existente primeiro
- Identifique o que precisa mudar
- Atualize arquivo de componente
- Atualize testes se comportamento mudou
- Atualize Storybook se props mudaram
- Verifique que testes ainda passam
- Verifique que Storybook ainda renderiza
Esta skill garante que todo componente siga convenções da equipe sem você ter que lembrar ou repetir os padrões.
### Registre e Use
O arquivo de skill é detectado automaticamente pelo Claude Code. Nenhum registro necessário—apenas coloque em `.claude/skills/`.
Próxima sessão:
```text
Crie um componente UserAvatar que exibe foto de perfil do usuário com fallback para iniciais
Claude vai:
- Invocar automaticamente skill react-component-patterns
- Fazer perguntas esclarecedoras sobre props
- Criar todos os 5 arquivos obrigatórios
- Seguir a estrutura exata do template
- Usar tokens de tema
- Adicionar atributos de acessibilidade
- Criar stories Storybook
- Escrever testes abrangentes
- Verificar que tudo funciona
Tudo sem você mencionar as convenções uma vez.
Resultados
Antes da skill:
- 30 minutos por componente (explicando convenções, corrigindo erros)
- Padrões inconsistentes entre componentes
- Testes ou stories faltantes
- Problemas de acessibilidade
- Ciclos de code review para aplicar padrões
Depois da skill:
- 5 minutos por componente (Claude segue padrões automaticamente)
- Consistência perfeita
- Nunca arquivos obrigatórios faltantes
- Acessibilidade integrada
- Code review foca em lógica, não formatação
Padrão 5: O Sistema de Descoberta e Invocação de Skills
Entender como Claude descobre e usa skills ajuda você a escrever melhores arquivos de skill e saber o que esperar.
Como Funciona a Descoberta de Skills
Quando você inicia uma sessão Claude Code:
1. Escaneamento de skills:
Carregando skills de:
- ~/.claude/skills/ (skills de usuário)
- ./.claude/skills/ (skills de projeto)
- [skills integradas]
Encontradas 47 skills
2. Indexação de skills:
Claude lê de cada skill:
- Nome (identificador único)
- Descrição (quando usá-la)
- Metadata de frontmatter
- Condições de acionamento
3. Invocação automática:
Quando você envia uma mensagem, Claude:
- Analisa sua solicitação
- Corresponde contra descrições de skills
- Invoca skills relevantes ANTES de responder
- Segue instruções de skill em sua resposta
O Sistema de Prioridade de Invocação
Quando múltiplas skills podem se aplicar, Claude segue prioridade:
1. Skills de processo primeiro (como abordar trabalho)
- brainstorming
- systematic-debugging
- test-driven-development
2. Skills de domínio segundo (o que construir)
- react-component-patterns
- api-design-patterns
- commit-conventions
3. Skills de ferramenta terceiro (como usar ferramentas)
- using-git-worktrees
- mcp-integration
Exemplo:
Você: "Construa uma feature de autenticação de usuário"
Claude invoca:
1. brainstorming (processo) - explore requisitos primeiro
2. Então oferece invocar security-patterns (domínio)
3. Finalmente usa git-worktrees (ferramenta) para trabalho isolado
Otimizando Descrições de Skill para Descoberta
A descrição determina se Claude invoca sua skill corretamente.
❌ Descrição pobre:
---
name: helpers
description: Utilitários úteis
---
Claude não sabe:
- Quando usar isso
- Que problemas resolve
- Como difere de outras skills
✅ Descrição otimizada:
---
name: api-error-handling
description: Use ao criar ou modificar endpoints de API para garantir respostas de erro consistentes
---
Claude sabe:
- Condição exata de acionamento ("endpoints de API")
- Propósito ("respostas de erro consistentes")
- Quando NÃO usar (código não-API)
Testando Invocação de Skill
Debug uso de skill com invocação explícita:
Isso força Claude a carregar a skill. Você pode ver:
- Se a skill carrega corretamente
- Se instruções são claras
- Se workflow faz sentido
Verifique raciocínio do Claude:
Por que você invocou a skill brainstorming?
Claude vai explicar sua tomada de decisão.
Problemas Comuns de Invocação
Problema: Skill nunca é invocada
Causa: Descrição muito vaga ou estreita
Correção:
❌ description: Helper para coisas de banco de dados
✅ description: Use ao criar, modificar ou debugar consultas e migrations de banco de dados
Problema: Skill errada é invocada
Causa: Descrições sobrepostas
Correção: Torne descrições mutuamente exclusivas:
# Skill de Criação de API
description: Use ao CRIAR novos endpoints de API
# Skill de Modificação de API
description: Use ao MODIFICAR endpoints de API existentes
# Skill de Debug de API
description: Use ao DEBUGAR problemas de endpoint de API
Problema: Skill invocada com muita frequência
Causa: Descrição muito ampla
Correção:
❌ description: Use para todas tarefas de codificação
✅ description: Use ao refatorar código sem mudar comportamento
Padrão 6: Skills de Equipe e Compartilhamento de Conhecimento
Skills individuais são poderosas. Skills de equipe são transformacionais.
O Padrão
1. Crie um repositório de skills de equipe:
2. Defina convenções de equipe como skills:
.claude/skills/
├── commit-conventions.md
├── code-review-checklist.md
├── api-design-patterns.md
├── database-migration-process.md
└── deployment-workflow.md
3. Faça commit para git:
git add .claude/skills/
git commit -m "docs: adiciona skills Claude Code da equipe"
git push origin main
4. Todo membro da equipe recebe as skills:
Quando alguém clona o repo, recebe as skills automaticamente. Claude Code as carrega de .claude/skills/.
Exemplos de Skill de Equipe
Skill de Code Review:
---
name: code-review-checklist
description: Use ao revisar código ou antes de marcar trabalho como completo
---
# Checklist de Code Review
Antes de aprovar QUALQUER código (seu ou de outros), verifique:
## Funcionalidade
- [ ] Código faz o que alega fazer
- [ ] Casos extremos são tratados
- [ ] Estados de erro são tratados
- [ ] Sem bugs óbvios
## Testes
- [ ] Testes existem e passam
- [ ] Testes cobrem caminho feliz
- [ ] Testes cobrem casos de erro
- [ ] Nomes de teste são descritivos
## Qualidade de Código
- [ ] Sem duplicação de código
- [ ] Funções são pequenas e focadas
- [ ] Nomes de variável são claros
- [ ] Lógica complexa tem comentários
## Segurança
- [ ] Sem segredos codificados
- [ ] Entrada de usuário é validada
- [ ] Injeção SQL prevenida
- [ ] Vulnerabilidades XSS prevenidas
## Performance
- [ ] Sem problemas óbvios de performance
- [ ] Consultas de banco de dados são eficientes
- [ ] Sem problemas de consulta N+1
- [ ] Listas grandes são paginadas
## Documentação
- [ ] APIs públicas são documentadas
- [ ] Algoritmos complexos explicados
- [ ] README atualizado se necessário
- [ ] Breaking changes notadas
Ao revisar, forneça:
1. Feedback específico sobre o que precisa mudar
2. Por que precisa mudar
3. Correção sugerida quando possível
Seja construtivo, não crítico.
Skill de Workflow de Deployment:
---
name: deployment-workflow
description: Use ao fazer deploy de código para staging ou produção
---
# Workflow de Deployment
Fazemos deploy através de CI/CD. Nunca deploy manual.
## Checklist Pré-Deployment
Antes de fazer push de código que aciona deployment:
- [ ] Todos testes passam localmente: `npm test`
- [ ] Linter passa: `npm run lint`
- [ ] Build tem sucesso: `npm run build`
- [ ] Sem código de debug (console.logs, debugger statements)
- [ ] Variáveis de ambiente documentadas
- [ ] Migrations de banco de dados testadas
- [ ] Plano de rollback identificado
## Processo de Deployment
### Para Staging
1. Crie feature branch de `main`
2. Faça alterações
3. Faça push para feature branch
4. CI executa testes automaticamente
5. Se testes passam, merge para branch `staging`
6. Auto-deploy para ambiente de staging
7. Verifique em staging
8. Obtenha aprovação da equipe
### Para Produção
1. Código deve estar em `staging` primeiro
2. Crie PR de `staging` → `main`
3. Requer 2 aprovações
4. Merge para `main`
5. CI executa suite completa de testes
6. Se testes passam, auto-deploy para produção
7. Monitore por 10 minutos
8. Verifique error tracking (Sentry)
9. Verifique fluxos principais de usuário
## Se Deployment Falhar
1. Verifique logs de CI primeiro
2. Se testes falham, corrija e re-execute
3. Se deployment falha, verifique ambiente
4. Se produção quebra, FAÇA ROLLBACK IMEDIATAMENTE
## Processo de Rollback
```bash
# Reverta o merge commit
git revert -m 1 <merge-commit-hash>
git push origin main
CI vai auto-deploy o estado revertido.
Nunca:
- ❌ Faça push diretamente para
main ou staging
- ❌ Faça deploy sexta à tarde
- ❌ Faça deploy sem testar em staging primeiro
- ❌ Faça deploy sem monitorar depois
- ❌ Faça deploy quando estiver prestes a sair do trabalho
Sempre:
- ✅ Faça deploy cedo no dia
- ✅ Monitore após deployment
- ✅ Tenha plano de rollback pronto
- ✅ Teste em staging primeiro
- ✅ Comunique com equipe
### Preservação de Conhecimento
Skills de equipe preservam conhecimento que de outra forma viveria em:
- Cabeça de alguém
- Documentação dispersa
- Mensagens Slack
- Conhecimento tribal
Quando um desenvolvedor sênior sai, sua expertise permanece em skills.
Quando um novo desenvolvedor entra, recebe o conhecimento imediatamente.
### Documentação Viva
Skills são melhores que docs tradicionais porque:
- Claude as aplica automaticamente
- São usadas todo dia (então permanecem atuais)
- São version-controlled (rastreie alterações)
- São executáveis (não apenas referência)
Docs tradicionais: "Aqui está como fazemos X"
Skills: Claude automaticamente faz X corretamente
### Quando Usar
- Configurando um novo projeto
- Onboarding de novos membros da equipe
- Codificando "a forma como fazemos as coisas"
- Reduzindo fricção de code review
- Garantindo consistência em toda equipe
---
## Medindo Eficácia de Skills
Como você sabe se skills estão realmente melhorando seu workflow?
### Métrica 1: Redução em Instruções Repetidas
Rastreie com que frequência você dá a mesma instrução:
**Antes de skills:** "Execute testes antes de commitar" mencionado em 80% das sessões
**Depois de skills:** Mencionado em 5% das sessões (apenas quando skill não está funcionando)
### Métrica 2: Tempo para Onboard
Quanto tempo até um novo desenvolvedor ser produtivo?
**Antes de skills:** 2 semanas (aprender convenções, padrões, workflows)
**Depois de skills:** 3 dias (Claude segue padrões automaticamente, desenvolvedor aprende por observação)
### Métrica 3: Ciclos de Code Review
Quantas rodadas de revisão antes do código ser aprovado?
**Antes de skills:** 2.5 rodadas em média
**Depois de skills:** 1.2 rodadas em média
Skills detectam problemas antes do code review.
### Métrica 4: Score de Consistência
Audite sua codebase para consistência de padrão:
```bash
# Verifique formato de mensagem de commit
git log --oneline | grep -v "^[a-z]*([a-z]*): " | wc -l
# Verifique estrutura de componente
find src/components -name "*.test.tsx" | wc -l
find src/components -name "*.tsx" -not -name "*.test.tsx" -not -name "*.stories.tsx" | wc -l
# Deve ser proporção 1:1
Antes de skills: 60% de consistência
Depois de skills: 95% de consistência
Retrospectiva Semanal
Toda sexta-feira, revise:
- Quais skills foram mais usadas? (otimize estas)
- Quais skills nunca foram usadas? (remova ou revise)
- Quais instruções foram repetidas? (crie novas skills)
- Quais erros foram cometidos repetidamente? (adicione às skills)
Anti-Padrões Que Destroem Valor de Skills
Agora que você sabe o que funciona, aqui está o que garante frustração.
Anti-Padrão 1: Skills Que São Apenas Docs
A armadilha:
---
name: api-patterns
description: Padrões de design de API
---
Seguimos princípios de design de API RESTful.
Recursos devem ser substantivos, não verbos.
Use métodos HTTP apropriados.
Por que falha: Este é material de referência, não orientação acionável.
A correção: Torne-o executável:
Ao criar um novo endpoint de API:
1. Identifique o recurso (user, product, order)
2. Escolha método HTTP:
- GET: ler dados
- POST: criar novo recurso
- PUT: atualização completa
- PATCH: atualização parcial
- DELETE: remover recurso
3. Estruture URL:
✅ /api/users/123
❌ /api/getUser?id=123
4. Retorne códigos de status apropriados:
- 200: sucesso com corpo
- 201: criado
- 204: sucesso sem corpo
- 400: bad request
- 404: não encontrado
- 500: erro do servidor
5. Siga formato de resposta JSON:
```json
{
"success": true,
"data": { ... },
"error": null
}
Me pergunte: Que recurso você está expondo? Então ajudo a implementar corretamente.
### Anti-Padrão 2: Skills Excessivamente Complexas
**A armadilha:**
Uma skill de 500 linhas que tenta cobrir todo cenário, caso extremo e possibilidade.
**Por que falha:**
- Demais para Claude processar efetivamente
- Difícil de manter
- Difícil de entender
- Torna lento o carregamento de skills
**A correção:** Divida em skills focadas:
❌ Uma mega skill: "complete-coding-standards.md" (500 linhas)
✅ Múltiplas skills focadas:
- commit-conventions.md (50 linhas)
- testing-patterns.md (60 linhas)
- code-style.md (40 linhas)
- error-handling.md (45 linhas)
### Anti-Padrão 3: Skills com Instruções Conflitantes
**A armadilha:**
```markdown
# Skill A:
Sempre escreva testes primeiro antes da implementação.
# Skill B:
Ao fazer protótipo, pule testes para mover rápido.
Por que falha: Claude não sabe qual seguir.
A correção: Torne condições explícitas:
# test-driven-development.md
Ao implementar features de produção, SEMPRE escreva testes primeiro.
# rapid-prototyping.md
Quando explicitamente dito para prototipar ou fazer spike, pule testes temporariamente.
Adicione testes antes de produção.
Anti-Padrão 4: Condições Vagas de Acionamento
A armadilha:
---
name: best-practices
description: Siga melhores práticas
---
Por que falha: "Melhores práticas" não significa nada. Quando isso deve ser invocado?
A correção:
---
name: security-code-review
description: Use ao revisar código que lida com entrada de usuário, autenticação ou dados sensíveis
---
Anti-Padrão 5: Skills sem Exemplos
A armadilha:
Escreva código limpo e manutenível.
Funções devem ser focadas e bem nomeadas.
Por que falha: Muito abstrato. Claude precisa de exemplos concretos.
A correção:
## Bons Nomes de Função:
✅ calculateTotalPrice(items: CartItem[]): number
✅ validateUserEmail(email: string): boolean
✅ formatCurrencyForDisplay(amount: number, locale: string): string
## Maus Nomes de Função:
❌ calc(items): number
❌ check(str): boolean
❌ format(amount, loc): string
❌ doStuff(): void
Note:
- Bons nomes explicam O QUÊ sem ler implementação
- Maus nomes requerem contexto para entender
- Bons nomes incluem tipos para segurança
- Maus nomes escondem complexidade
Deixe-me mostrar skills em ação com uma transformação real de empresa.
O Problema
Uma startup de 12 pessoas estava lutando com Claude Code:
- Cada desenvolvedor usava Claude diferentemente
- Qualidade de código era inconsistente
- Novos desenvolvedores levavam semanas para aprender padrões
- Code reviews eram dolorosas (muitos debates de estilo)
- Claude cometia os mesmos erros repetidamente
Custo: 30% do tempo de desenvolvimento gasto em retrabalho e code review
A Solução de Skills
Semana 1: Auditoria de Padrões Atuais
Identificaram instruções repetidas em toda equipe:
- "Use TypeScript modo strict"
- "Adicione testes para todas novas features"
- "Siga nosso formato de mensagem de commit"
- "Não faça push diretamente para main"
- "Atualize docs ao adicionar features"
Estas apareceram em 75% de todas sessões Claude Code.
Semana 2: Criar Skills Core
Construíram 5 skills essenciais:
.claude/skills/
├── typescript-standards.md
├── test-driven-development.md
├── commit-conventions.md
├── git-workflow.md
└── documentation-practices.md
Semana 3: Deploy e Treinamento
- Fizeram commit de skills para git
- Todos devs puxaram latest
- Treinamento de 30 minutos: "Como skills funcionam"
- Cada dev testou skills em uma tarefa
Semana 4: Monitorar e Refinar
Coletaram feedback:
- "Skill de commit é muito rigorosa" → Relaxaram para correções pequenas
- "Skill de teste torna protótipos lentos" → Adicionaram skill rapid-prototyping
- "Skill de documentação aciona com muita frequência" → Refinaram condições de acionamento
Resultados
Após 1 Mês:
- Tempo de code review: ↓60% (de 2 horas → 45 minutos por PR)
- Score de consistência: ↑de 60% → 92%
- Tempo de onboarding: ↓de 2 semanas → 3 dias
- Instruções repetidas: ↓de 75% → 12% das sessões
Após 3 Meses:
- 10 skills em produção
- Cada desenvolvedor usando-as diariamente
- Novos desenvolvedores produtivos em dias, não semanas
- Citação do líder da equipe: "Skills codificaram o conhecimento da nossa desenvolvedora sênior. Quando ela saiu de licença maternidade, a equipe não perdeu o ritmo."
Após 6 Meses:
- Contribuindo skills de volta para open source
- Outras equipes na empresa adotando mesmos padrões
- Skills se tornaram parte do processo de entrevista (candidatos trabalham com skills para ver práticas da equipe)
Antes: Claude Code era um desenvolvedor júnior inteligente que você tinha que microgerenciar
Depois: Claude Code se tornou um desenvolvedor sênior que conhecia os padrões da sua equipe e os aplicava consistentemente
A diferença não foi a IA. Foram as skills.
Construindo Sua Prática de Skills
Você agora tem os padrões. Aqui está como construir maestria.
Semana 1: Descoberta
Dia 1: Explore skills integradas
Leia descrições. Entenda quando usar cada uma.
Dia 2-3: Use 3 skills deliberadamente
/systematic-debugging
/test-driven-development
/brainstorming
Observe como mudam o comportamento do Claude.
Dia 4-5: Rastreie instruções repetidas
Toda vez que você explica algo ao Claude, anote:
- "Execute testes primeiro"
- "Verifique git status antes de commitar"
- "Use tipos TypeScript"
Estas são candidatas a skills.
Semana 2: Crie Sua Primeira Skill
Dia 1: Escolha UMA instrução repetida
Comece simples. Não tente codificar tudo.
Dia 2-3: Escreva o arquivo da skill
Use o template. Inclua exemplos.
Dia 4: Teste a skill
Use em trabalho real. Refine baseado em resultados.
Dia 5: Documente e compartilhe
Adicione comentários explicando por que esta skill existe.
Semana 3: Expanda Sua Biblioteca de Skills
Dia 1-2: Crie 2-3 skills mais
Foque em suas instruções mais repetidas.
Dia 3-4: Teste todas skills juntas
Elas funcionam bem juntas? Algum conflito?
Dia 5: Meça o impacto
Quanto tempo está economizando? O que está melhorando?
Semana 4: Skills de Equipe
Dia 1-2: Identifique padrões da equipe
Que convenções sua equipe segue?
Dia 3: Crie arquivos de skill de equipe
Documente-os como skills, não apenas docs.
Dia 4: Obtenha feedback da equipe
As skills correspondem práticas reais?
Dia 5: Faça deploy para equipe
Commit para git. Faça equipe usá-las.
Mês 2: Padrões Avançados
- Skills que referenciam outras skills
- Invocação condicional de skill
- Skills para diferentes tipos de projeto
- Skills para code review
- Skills para onboarding
O Futuro de Skills
Skills estão evoluindo rapidamente. Aqui está para onde estão indo.
Três Previsões
1. Skills se tornam a forma padrão de customizar assistentes de codificação IA
Assim como linters e formatters customizam estilo de código, skills vão customizar comportamento de IA.
2. Marketplace de skills especializadas
Veremos:
- Skills específicas de indústria (fintech, healthcare, gaming)
- Skills específicas de framework (padrões React, padrões Django)
- Skills específicas de empresa (padrões da sua org)
3. Skills como documentação viva
Docs tradicionais serão substituídos por skills executáveis. Em vez de documentar "como fazemos X," você terá uma skill que faz X corretamente.
O Que Não Vai Mudar
Mesmo enquanto skills evoluem, princípios core permanecem:
- Condições claras de acionamento para invocação confiável
- Exemplos concretos para entendimento
- Passos acionáveis não material de referência
- Foco sobre abrangência para manutenibilidade
Estas não são melhores práticas temporárias. São padrões fundamentais para aumentar IA com conhecimento de domínio.
Conclusão: O Multiplicador Que Você Está Perdendo
Seis meses atrás, "Claude Code skills" soava como uma feature legal de ter.
Hoje, é o diferenciador entre desenvolvedores que usam IA como motor de busca e desenvolvedores que usam IA como colega de equipe treinado.
Mas maestria requer mais que descobrir que skills existem. Requer prática deliberada de padrões específicos:
- Descubra antes de construir - Use skills existentes primeiro
- Uma skill, um propósito - Focado bate abrangente
- Acionável sobre descritivo - Execução bate documentação
- Exemplos sobre abstrações - Mostre, não diga
- Skills de equipe para consistência - Conhecimento compartilhado escala
- Meça e refine - Rastreie impacto, melhore continuamente
Estes padrões não são sobre skills em si. São sobre codificar expertise para que seja automaticamente aplicada em vez de repetidamente explicada.
Os desenvolvedores que dominam isso terão uma vantagem injusta.
Os que não vão continuar se repetindo toda sessão.
A diferença são skills.
Comece a construir.
Artigos Relacionados
- AI: Padrões de Pair Programming com LLM - você tem um par de programação IA que nunca dorme, nunca cansa, e já viu milhões de padrões similares.
- AI: Code review - Revisão de Código com IA: Workflows Que Realmente Melhoram Qualidade
Referência Rápida
Comandos Essenciais de Skill
/help
/skill-name
mkdir -p .claude/skills
ls .claude/skills/
Template de Arquivo de Skill
---
name: skill-name
description: Quando usar esta skill (uma frase clara)
---
# Nome da Skill
Breve explicação de propósito.
## Quando Usar
Condições explícitas de acionamento.
## Workflow
1. Faça isso primeiro
2. Então isso
3. Finalmente isso
## Exemplos
### Bom
Mostre como é o sucesso.
### Ruim
Mostre o que evitar.
## Checklist
- [ ] Passo 1
- [ ] Passo 2
- [ ] Passo 3
Checklist de Segurança de Skill
Antes de usar uma skill:
Configuração de Skill de Equipe
mkdir -p .claude/skills
touch .claude/skills/team-standards.md
git add .claude/skills/
git commit -m "docs: adiciona skills Claude Code da equipe"
git pull
Sua vez. Escolha uma instrução que você repete toda sessão. Transforme-a em uma skill hoje.
O multiplicador de produtividade 10x não está no próximo modelo de IA.
Está nas skills que você constrói hoje.
