Cansou de escrever prompts na mão? Este recurso do Claude Code triplicou minha eficiência

Uma história real

Em outubro do ano passado, eu tinha um projeto React para refatorar: uma classe Deus com mais de 2.000 linhas, daquelas que dão dor de cabeça só de abrir. Toda vez que eu pedia ao Claude Code para otimizar o código, precisava repetir a mesma lista:

• “lembre-se de usar TypeScript em modo estrito”
• “chamadas de API precisam ter tratamento de erro”
• “componentes devem seguir o princípio da responsabilidade única”

Só copiar e colar esses requisitos já tomava dois ou três minutos. O pior era que, depois de umas dez rodadas de conversa, o Claude Code frequentemente “esquecia” o que eu tinha pedido no começo e voltava a gerar código fora do padrão.

Até que encontrei o recurso Skill na documentação.

Depois de uma semana testando, empacotei aqueles requisitos repetidos em alguns arquivos de skill. Hoje basta escrever @skill react-refactor e o Claude Code já entende o caminho. Aquela classe de 2.000 linhas, que eu achava que levaria três dias para refatorar, ficou pronta em duas tardes.

O que é uma Skill, afinal?

Resumindo, Skill é como instalar um pacote de habilidades no Claude Code.

Você cria um arquivo Markdown dentro de .claude/skills/ e coloca nele prompts frequentes, fluxos de trabalho e regras de código. Quando precisar, chama com @skill nome-da-skill. É como equipar um personagem em um jogo: quando precisa causar dano, usa uma skill ofensiva; quando precisa proteger, equipa uma defensiva.

Veja um exemplo bem simples:

---

title: "Especialista em revisão de código React"
description: "Revisa qualidade, desempenho e boas práticas em código React"

---

# Fluxo de revisão de código React
Você é uma pessoa especialista em revisão de código React, com bastante experiência. Revise o código seguindo os critérios abaixo:
## Pontos de revisão
1. **Design de componentes**
   - Princípio da responsabilidade única
   - Completude das definições de tipos em Props
   - Coerência na divisão de componentes
2. **Otimização de desempenho**
   - Re-renderizações desnecessárias
   - Uso de useMemo/useCallback
   - Valores de key em renderização de listas
3. **Qualidade do código**
   - Segurança de tipos em TypeScript
   - Tratamento de error boundaries
   - Acessibilidade (a11y)
## Formato de saída
- Lista de problemas, ordenada por severidade
- Sugestões concretas de código
- Prioridade marcada como P0/P1/P2

Salve esse arquivo como .claude/skills/react-review.md. Depois, quando for revisar código React, basta chamar @skill react-review. O Claude Code seguirá exatamente os critérios que você definiu.

Por que prompts escritos à mão não sustentam mais o fluxo?

Eu também já fui “engenheiro de prompts”: tinha dezenas de modelos cuidadosamente refinados no Notion. Depois de alguns meses, ficou claro que esse método tinha limites duros.

Trabalho repetitivo demais

Toda vez era preciso copiar algo do Notion e, às vezes, ajustar alguns termos para o projeto atual. No fim do dia, só copiar e colar prompts consumia quase meia hora.

Versionamento bagunçado

O prompt de hoje não era igual ao da semana passada, então o resultado também variava. Quer voltar para “aquela versão que funcionou bem da outra vez”? Desculpe, ninguém sabe onde está.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Colaboração em equipe vira um caos

Tenho um prompt bom e um colega quer usar? Envio manualmente pelo WeChat. O colega melhora o prompt? Precisa me mandar de volta também na mão. Em termos de eficiência, isso parece idade da pedra.

A IA esquece

Em conversas longas, o Claude Code esquece facilmente os requisitos iniciais. Na vigésima rodada, você percebe que ele voltou a cometer exatamente o erro que você já tinha pedido para evitar.

Skill resolve esses problemas de uma vez:

• Versionamento: gerencie com Git e volte para qualquer versão
• Compartilhamento: a equipe puxa o repositório e todo mundo sincroniza
• Efeito constante: não perde validade só porque a conversa ficou longa

"O valor central de uma Skill está em reutilização e consistência: transformar engenharia de prompts em um ativo de projeto que pode ser mantido e compartilhado."

Minha primeira Skill: gerador de interfaces de API

Naquele projeto de e-commerce, o backend me entregou uma documentação Swagger com mais de 100 endpoints. Se eu integrasse tudo manualmente, cada endpoint exigiria:

1. definições de tipos TypeScript
2. função de requisição com axios
3. lógica de tratamento de erro
4. gerenciamento de estado de loading

Fazendo a conta, 100 endpoints dariam quase 30 horas de trabalho.

Eu gastei 1 hora escrevendo uma skill api-generator:

---

title: "Gerador de código para interfaces de API"
description: "Gera definições de tipos TS e wrappers axios a partir da documentação da API"
version: "1.3.0"

---

# Especialista em geração de código de API
Você é uma pessoa engenheira full-stack, com experiência em integração entre frontend e backend. Sua tarefa é gerar código TypeScript de alta qualidade com base na documentação da API.
## Conteúdo a gerar
### 1. Definições de tipos TypeScript
```typescript
// Tipo dos parâmetros da requisição
interface GetUserRequest {
  userId: string;
  includeDetails?: boolean;
}
// Tipo dos dados da resposta
interface GetUserResponse {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

2. Função de requisição Axios

import request from '@/utils/request';
export const getUserAPI = async (
  params: GetUserRequest
): Promise<GetUserResponse> => {
  try {
    const response = await request.get<GetUserResponse>('/api/user', { params });
    return response.data;
  } catch (error) {
    console.error('Falha ao buscar informações do usuário:', error);
    throw error;
  }
};

3. Wrapper React Hook (opcional)

export const useGetUser = (userId: string) => {
  const [data, setData] = useState<GetUserResponse | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  useEffect(() => {
    const fetchData = async () => {
      setLoading(true);
      try {
        const result = await getUserAPI({ userId });
        setData(result);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [userId]);
  return { data, loading, error };
};

Regras de código

• A nomenclatura deve seguir camelCase
• Funções de API devem terminar com API
• Funções Hook devem começar com use
• Todas as funções assíncronas precisam ter tratamento de erro
• Tipos e funções exportados devem incluir comentários JSDoc

Formato de saída

1. Primeiro, gere as definições de tipos
2. Depois, gere a função de API
3. Se for um endpoint usado com frequência, gere também o wrapper Hook
4. Por fim, forneça um exemplo de uso

Com essa skill, integrar um endpoint caiu de 30 minutos para 5 minutos. Para 100 endpoints, concluí tudo em dois dias. Mais importante: pessoas novas na equipe passaram a gerar código com a mesma regra, e o estilo do projeto ficou muito mais consistente.

## Uso avançado: fazer Skills trabalharem juntas

Depois que peguei prática, percebi que uma skill isolada nem sempre basta. Cenários reais de desenvolvimento costumam exigir várias skills trabalhando em sequência.

Por exemplo, meu fluxo padrão para refatorar código legado:

```bash
# Etapa 1: analisar problemas no código
@skill code-analyzer src/legacy/UserService.ts
# Etapa 2: definir um plano de refatoração
@skill refactor-planner
# Etapa 3: gerar casos de teste; antes de refatorar, testes são a rede de proteção
@skill test-generator
# Etapa 4: executar a refatoração
# refatoração manual ou com ajuda do Claude Code
# Etapa 5: revisão final do código
@skill code-reviewer

Essas quatro skills, chamadas em ordem, formam um fluxo completo de refatoração. Cheguei a escrever um shell script para automatizar esse processo:

#!/bin/bash
# refactor-workflow.sh
echo "🔍 Etapa 1/4: analisando problemas no código..."
claude-code @skill code-analyzer $1
read -p "Pressione Enter para continuar..."
echo "📋 Etapa 2/4: definindo o plano de refatoração..."
claude-code @skill refactor-planner
read -p "Pressione Enter para continuar..."
echo "🧪 Etapa 3/4: gerando casos de teste..."
claude-code @skill test-generator
read -p "Execute os testes e, depois de confirmar que passaram, pressione Enter para continuar..."
echo "✅ Etapa 4/4: revisão final do código..."
claude-code @skill code-reviewer

Usei esse script para refatorar uma classe Deus de 2.000 linhas e dividi-la em 7 classes pequenas, cada uma com responsabilidade clara. A cobertura de testes subiu de 40% para 85%, e o processo inteiro foi muito mais tranquilo do que eu esperava.

Compartilhamento em equipe: tratar Skill como infraestrutura

Hoje nossa equipe gerencia skills como infraestrutura. Criamos um repositório Git só para armazenar team-skills:

team-skills/
├── frontend/
│   ├── react-review.md          # Revisão de código React
│   ├── vue-component-gen.md     # Geração de componente Vue
│   └── css-optimizer.md         # Otimização de desempenho em CSS
├── backend/
│   ├── api-design.md            # Regras de design de API
│   ├── database-review.md       # Revisão de banco de dados
│   └── security-audit.md        # Auditoria de segurança
└── common/
    ├── code-cleaner.md          # Limpeza de código
    ├── test-generator.md        # Geração de testes
    └── commit-msg.md            # Geração de mensagem de commit Git

Cada pessoa desenvolvedora cria um link simbólico desse repositório para o projeto local:

# Configuração única
git clone [email protected]:your-team/team-skills.git ~/.team-skills
ln -s ~/.team-skills/* .claude/skills/

Os benefícios aparecem rápido:

• Amigável para quem está entrando: no primeiro dia, a pessoa já tem uma biblioteca completa de skills e consegue escrever código dentro do padrão
• Sincronização automática: quando a equipe atualiza uma skill, todo mundo roda git pull e recebe a versão mais recente
• Código consistente: não importa quem escreveu, o estilo fica altamente uniforme

No mês passado chegou uma pessoa estagiária. No segundo dia, ela já escrevia código dentro das regras da equipe. Antes, isso exigiria pelo menos uma semana de treinamento.

Skill e CLAUDE.md são uma dupla de ouro

O uso mais forte de Skill é junto com o CLAUDE.md na raiz do projeto.

No CLAUDE.md, defina as regras globais do projeto:

# Contexto do projeto
- Stack técnica: React 18 + TypeScript 5.0 + Vite 4
- Regras de código: Airbnb ESLint rules
- Convenção de commit: Conventional Commits
- Gerenciamento de estado: Zustand (Redux é proibido)
## Convenções importantes
- Todos os componentes devem ter definições completas de tipos TypeScript
- Chamadas de API devem usar o wrapper src/utils/request.ts
- Nomes de arquivos de componentes usam PascalCase, como UserProfile.tsx
- Nomes de arquivos de funções utilitárias usam camelCase, como formatDate.ts
## Estrutura de diretórios
src/
├── components/    # Componentes compartilhados
├── pages/         # Componentes de página
├── hooks/         # Hooks personalizados
├── utils/         # Funções utilitárias
├── services/      # Serviços de API
└── stores/        # Gerenciamento de estado com Zustand

Depois, referencie essas regras na skill:

---

title: "Gerador de componentes React"

---

# Instruções de geração de componentes
Gere componentes React seguindo estritamente a stack técnica, a estrutura de diretórios e as convenções de nomenclatura definidas em CLAUDE.md.
O componente gerado deve:
- Usar TypeScript
- Seguir as regras ESLint do projeto
- Ser colocado no diretório correto
- Usar a solução de gerenciamento de estado adotada pelo projeto

Assim a skill lê automaticamente a configuração do CLAUDE.md, e o código gerado fica totalmente alinhado ao padrão do projeto. Ao clonar um projeto novo, a skill também se adapta imediatamente.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Minhas 5 Skills essenciais

Depois de seis meses de uso, meu diretório skills acumulou mais de 20 skills. Estas são algumas das que mais uso.

1. Gerador de testes (test-gen.md)

Depois de escrever a funcionalidade, a parte mais chata costuma ser completar os testes. Essa skill analisa a lógica da função e gera testes unitários automaticamente, incluindo casos de borda e cenários de exceção.

Resultado: minha cobertura de testes subiu de 40% para 85%, e economizei pelo menos metade do tempo que gastava escrevendo testes.

2. Gerador de mensagens de commit Git (commit-msg.md)

Pensar em uma commit message a cada commit consome mais energia mental do que deveria. Essa skill analisa o conteúdo do git diff e gera uma mensagem de commit no padrão Conventional Commits.

Exemplo de saída:

feat(user-auth): adiciona login OAuth2.0
- Integra login de terceiros com Google e GitHub
- Adiciona mecanismo de refresh para JWT token
- Melhora o middleware de validação de permissões do usuário
Closes #123

Ela tem só 30 linhas, mas é uma das skills que uso todos os dias. O tempo acumulado que economizou já passa de várias horas.

3. Assistente de refatoração (refactor.md)

Quando o código legado precisa melhorar, mas não está claro por onde começar, essa skill ajuda a:

• identificar code smells
• ordenar prioridades de refatoração
• fornecer um plano step-by-step
• garantir que o comportamento antes e depois da refatoração continue igual

Aquela classe Deus de 2.000 linhas foi resolvida com ajuda dela.

4. Especialista em revisão de segurança (security-audit.md)

Focada em problemas de segurança no código:

• risco de SQL injection
• proteção contra XSS
• vazamento de informações sensíveis
• completude da validação de permissões

Uma vez, antes de publicar uma versão, passei essa skill no código e encontrei 3 vulnerabilidades potenciais. Foi um susto, mas melhor descobrir ali do que em produção.

5. Gerador de documentação (doc-gen.md)

A documentação do projeto sempre fica atrasada em relação ao código? Essa skill gera documentação de API automaticamente a partir do código, extrai comentários de funções para Markdown e ainda ajuda a manter o changelog.

O tempo de atualização da documentação caiu de 2 horas para 10 minutos, e acabou aquela situação de “o código mudou, mas a documentação não”.

5 dicas para escrever boas Skills

Depois de meio ano, estas são as lições mais úteis que aprendi escrevendo skills.

1. Leve o frontmatter a sério

Mesmo parecendo opcional, title e description aparecem na lista de skills:

---

title: "Especialista em revisão full-stack"
description: "Revisa código frontend e backend, com foco em segurança, desempenho e manutenibilidade"
version: "2.1.0"
tags: ["revisão de código", "segurança", "desempenho"]

---

O campo version facilita o versionamento, e tags ajudam na classificação.

2. Defina o papel com clareza

Aberturas como “você é uma pessoa especialista em…” funcionam bem porque ajudam o Claude Code a entrar no papel rapidamente:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Você é uma pessoa engenheira full-stack com 10 anos de experiência, especialista em revisão de código e auditoria de segurança.

Isso funciona muito melhor do que dizer apenas “revise o código”.

3. Use exemplos comparativos

Comparar código bom e ruim com ✅ e ❌ ajuda o Claude Code a entender melhor:

### Risco de SQL injection
❌ Forma perigosa:
```javascript
const query = `SELECT * FROM users WHERE id = ${userId}`;

✅ Forma segura:

const query = 'SELECT * FROM users WHERE id = ?';
db.query(query, [userId]);

### 4. Seja específico no formato de saída

Não diga apenas "dê sugestões". Diga "responda no formato abaixo":

```markdown
## Formato de saída
### 🔴 Problemas graves (correção obrigatória)
- [arquivo:linha] descrição do problema
- explicação do risco
- sugestão de correção com exemplo de código
### 🟡 Melhorias recomendadas
- [arquivo:linha] descrição do problema
- motivo da melhoria
- solução proposta

5. Inclua regras de tratamento de erro

Diga à IA o que fazer quando encontrar problemas:

## Tratamento de erros
Se encontrar uma das situações abaixo:
- Erro de sintaxe no código: indique primeiro a posição do erro e não continue a revisão
- Arquivo inacessível: peça para o usuário verificar o caminho
- Código grande demais (>5000 linhas): sugira revisar em lotes

Perguntas frequentes

Tem Skills demais e fica difícil lembrar os nomes?

Use uma boa convenção de nomenclatura:

• review-*: revisão de código
• gen-*: geração de código
• util-*: utilitários
• fix-*: correção de problemas

Minha convenção: review-frontend.md, gen-api.md, util-commit.md.

A saída da Skill fica longa demais?

Adicione um modo resumido dentro da própria skill:

Use modo detalhado por padrão. Se o usuário adicionar o parâmetro `--brief`, responda em versão resumida:
- lista de problemas, um por linha
- marcação de severidade
- recomendações principais de correção

A Skill se comporta de forma diferente em projetos diferentes?

Faça a skill pedir contexto ativamente:

## Passos antes da análise
Antes de começar:
1. Leia package.json para entender as versões das dependências
2. Verifique tsconfig.json para entender a configuração do TS
3. Veja .eslintrc para conhecer as regras de código
4. Consulte README.md para entender a arquitetura do projeto

Para fechar

Depois de seis meses usando o recurso de skill, minha eficiência de desenvolvimento subiu pelo menos 40%. Mais importante: muito trabalho mental repetitivo saiu da frente, e agora posso gastar tempo com arquitetura e lógica de negócio, que realmente exigem pensamento.

Se você ainda escreve prompts na mão, minha sugestão:

1. Comece hoje: escolha uma skill simples, como revisão de código ou geração de testes
2. Melhore aos poucos: depois de cada uso, pense no que poderia melhorar e atualize a versão
3. Compartilhe com a equipe: uma boa skill é como uma boa biblioteca de ferramentas, deve circular
4. Continue aprendendo: acompanhe a documentação oficial, porque recursos novos podem mudar a melhor forma de escrever

Uma última observação: o valor de uma Skill não está em ser complexa, mas em resolver um problema real. Meu gerador de commit message mais simples tem só 30 linhas, mas uso todos os dias, e ele já economizou várias horas acumuladas.

A partir de agora, experimente transformar os prompts que você digita todos os dias em skills. Daqui a três meses, você vai agradecer a decisão de hoje.

Recursos relacionados

• Documentação oficial do Claude Code
• Guia de melhores práticas de Skill
• Biblioteca de templates de Skill da comunidade