Como Criar Habilidades de Agente no Claude Code: Guia Completo para Startups

Você está em uma fase de crescimento acelerado como founder, certo? Então você sabe bem como o tempo é precioso. Cada minuto gasto em tarefas repetitivas é um minuto que poderia estar sendo investido em estratégia, produto ou crescimento.

O Claude Code oferece uma solução elegante para esse problema: as Habilidades de Agente. Elas permitem que você automatize processos específicos da sua equipe de desenvolvimento, desde revisões de código até geração de mensagens de commit. A melhor parte? Claude aprende automaticamente quando usar essas Habilidades, sem que você precise digitar comandos especiais.

O que São Habilidades e Por Que Importam para Seu Negócio

Uma Habilidade é basicamente um arquivo markdown que ensina Claude a fazer algo específico. Pode ser revisar pull requests seguindo os padrões da sua equipe, gerar mensagens de commit no formato que você gosta, ou até consultar o esquema do seu banco de dados.

Quando você faz uma pergunta a Claude que corresponde ao propósito de uma Habilidade, Claude a aplica automaticamente. Nenhuma configuração adicional necessária. Nenhuma invocação manual. Apenas inteligência contextual em ação.

Para uma startup, isso significa velocidade. Significa menos tempo com bricolagem de processos e mais tempo construindo o que realmente importa. Significa que sua equipe pode se concentrar em inovação, não em tarefas mecânicas.

Como as Habilidades Funcionam na Prática

Entender o funcionamento das Habilidades é fundamental para aproveitá-las bem. Vamos descomplicar:

O Fluxo Automático de Invocação

As Habilidades são invocadas pelo modelo — ou seja, Claude decide quais Habilidades usar com base no que você pediu. Você não precisa chamar explicitamente uma Habilidade. Se sua solicitação corresponder à descrição dela, Claude a usa automaticamente.

Quando você envia um pedido, Claude segue estes passos:

1. Analisa sua solicitação para entender o contexto e intenção
2. Verifica as Habilidades disponíveis consultando suas descrições
3. Identifica quais Habilidades são relevantes para sua tarefa
4. Aplica as Habilidades apropriadas automaticamente

Isso cria uma experiência fluida onde Claude se torna progressivamente mais inteligente e alinhado com os processos específicos da sua startup.

Onde as Habilidades Vivem e Quem as Acessa

A localização de uma Habilidade determina seu alcance e quem pode usá-la. Isso é importante para organizar conforme sua equipe cresce:

Habilidades Empresariais residem nas configurações gerenciadas e aplicam-se a todos os usuários da sua organização. Use isso quando você quer padronizar processos em toda a equipe.

Habilidades Pessoais ficam em ~/.claude/skills/ no seu computador e você as usa em todos os projetos. Perfeito para seus padrões e preferências individuais.

Habilidades de Projeto residem em .claude/skills/ no seu repositório. Qualquer pessoa trabalhando nesse repositório as herda automaticamente. Ideal para padrões específicos de um projeto.

Habilidades de Plugin vêm empacotadas com plugins e estão disponíveis para qualquer pessoa com o plugin instalado. Ótimo para compartilhar soluções entre múltiplos projetos.

Quando duas Habilidades têm o mesmo nome, há uma hierarquia clara: gerenciada substitui pessoal, pessoal substitui projeto, e projeto substitui plugin. Isso garante que você sempre tenha controle granular.

Habilidades Versus Outras Ferramentas de Personalização

Claude Code oferece várias maneiras de personalizar comportamento. A distinção crucial é que Habilidades são acionadas automaticamente quando relevantes, enquanto outras ferramentas exigem ação manual ou têm propósitos diferentes.

Slash Commands exigem que você digite /command explicitamente. Use quando você quer prompts reutilizáveis que você invoca manualmente, como /deploy staging.

CLAUDE.md define instruções para todo o projeto. Use para configurações globais, como "usar modo estrito TypeScript".

Subagentes delegam tarefas para um contexto separado com suas próprias ferramentas. Use quando você precisa isolamento ou acesso a ferramentas diferentes.

Hooks executam scripts em eventos específicos, como lint ao salvar arquivo. Use para automação baseada em eventos.

MCP Servers conectam Claude a ferramentas e fontes de dados externas. Use para integração com sistemas existentes.

A diferença fundamental entre Habilidades e Subagentes merece atenção especial: Habilidades adicionam conhecimento à conversa atual, enquanto Subagentes rodam em um contexto completamente separado com suas próprias ferramentas. Use Habilidades para orientação e padrões; use Subagentes quando você precisar de isolamento ou acesso a ferramentas diferentes.

Da mesma forma, Habilidades dizem a Claude como usar ferramentas (metodologia e padrões), enquanto MCP ** fornece** as ferramentas em si. Por exemplo, um servidor MCP conecta Claude ao seu banco de dados específico, enquanto uma Habilidade ensina a Claude seu modelo de dados e padrões de consulta preferidos.

Configurando e Estruturando Suas Habilidades

Agora que você entende como elas funcionam, vamos falar sobre como criá-las e organizá-las adequadamente.

A Estrutura Essencial: SKILL.md

Toda Habilidade começa com um arquivo SKILL.md. Tecnicamente, é o único arquivo obrigatório. Ele tem duas partes principais: metadados YAML no topo (entre os marcadores ---) e instruções Markdown que ensinam Claude como usar a Habilidade.

A estrutura básica é simples:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

Os campos YAML disponíveis são:

name (obrigatório): Nome da Habilidade usando apenas letras minúsculas, números e hífens (máximo 64 caracteres). Deve corresponder ao nome do diretório.

description (obrigatório): O que a Habilidade faz e quando usá-la (máximo 1024 caracteres). Claude usa isso para decidir quando aplicar a Habilidade — torne-a específica e relevante.

allowed-tools (opcional): Ferramentas que Claude pode usar sem pedir permissão quando esta Habilidade está ativa. Use para segurança — por exemplo, uma Habilidade de leitura de arquivos poderia permitir apenas Read, Grep e Glob, bloqueando operações de escrita.

model (opcional): Modelo específico a ser usado quando esta Habilidade estiver ativa, como claude-sonnet-4-20250514. Por padrão usa o modelo da conversa.

context (opcional): Defina como fork para executar a Habilidade em um contexto de subagente isolado com seu próprio histórico. Útil para operações complexas.

agent (opcional): Qual tipo de agente usar quando context: fork está definido — Explore, Plan, general-purpose, ou um nome personalizado.

hooks (opcional): Define hooks para o ciclo de vida da Habilidade, com suporte a PreToolUse, PostToolUse e Stop.

user-invocable (opcional): Controla se a Habilidade aparece no menu de comandos. Padrão é true. Mesmo quando false, Claude ainda pode invocá-la automaticamente.

Uma descrição bem escrita é crucial. Responda duas perguntas: (1) O que esta Habilidade faz? Liste capacidades específicas. (2) Quando Claude deve usá-la? Inclua termos de gatilho que os usuários mencionariam.

Exemplo de descrição ruim: "Ajuda com documentos"

Exemplo de descrição melhor: "Extrai texto e tabelas de arquivos PDF, preenche formulários, mescla documentos. Use ao trabalhar com arquivos PDF ou quando mencionar PDFs, formulários ou extração de documentos."

Organização de Projetos: Divulgação Progressiva

Para Habilidades complexas, use um padrão chamado divulgação progressiva. Coloque informações essenciais em SKILL.md e material de referência detalhado em arquivos separados que Claude lê apenas quando necessário.

Essa abordagem mantém o contexto focado e eficiente. Claude não carrega toda a documentação antecipadamente — apenas o necessário para a tarefa em mãos.

Uma estrutura típica poderia ser:

my-skill/
├── SKILL.md (visão geral obrigatória e navegação)
├── reference.md (documentação detalhada da API)
├── examples.md (exemplos de uso)
└── scripts/
    └── helper.py (scripts utilitários)

O arquivo SKILL.md referencia os arquivos de suporte para que Claude saiba que existem:

## Visão Geral

[Instruções essenciais aqui]

## Recursos Adicionais

- Para detalhes completos da API, consulte [reference.md](reference.md)
- Para exemplos de uso, consulte [examples.md](examples.md)

## Scripts de Utilidade

Para validar arquivos de entrada, execute o script auxiliar:
python scripts/helper.py input.txt

Os scripts no diretório da sua Habilidade podem ser executados sem carregar seu conteúdo para o contexto. Claude executa o script e apenas a saída consome tokens. Isso é especialmente valioso para lógica de validação complexa, processamento de dados confiável ou operações que exigem consistência.

Controlando Acesso a Ferramentas com allowed-tools

Use o campo allowed-tools para limitar quais ferramentas Claude pode usar quando uma Habilidade está ativa. Isso é crítico para segurança e controle em startups em crescimento.

Você pode especificar como uma string separada por vírgulas ou como lista YAML:

---
name: reading-files-safely
description: Lê arquivos sem fazer alterações. Use para acesso somente leitura.
allowed-tools: Read, Grep, Glob
---

Quando esta Habilidade está ativa, Claude só pode usar Read, Grep e Glob. Nenhuma outra ferramenta está disponível, prevenindo mudanças acidentais.

Isso é especialmente útil para:

• Habilidades somente leitura que não devem modificar arquivos
• Habilidades com escopo limitado como análise de dados sem gravação
• Fluxos de trabalho sensíveis à segurança onde você quer restrições rigorosas

Execução em Contexto Bifurcado

Para Habilidades que realizam operações complexas de várias etapas, use context: fork para executá-las em um contexto de subagente isolado com seu próprio histórico de conversa.

---
name: code-analysis
description: Analyze code quality and generate detailed reports
context: fork
---

Isso evita que informações intermediárias consumam sua janela de contexto principal, mantendo a conversa organizada e focada.

Adicionando Hooks para Automação

Habilidades podem definir hooks que executam durante seu ciclo de vida. Use o campo hooks para especificar manipuladores:

---
name: secure-operations
description: Perform operations with additional security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

A opção once: true executa o hook apenas uma vez por sessão. Depois da primeira execução bem-sucedida, o hook é removido.

Controlando Visibilidade e Invocação

As Habilidades podem ser invocadas de três maneiras: manualmente (você digita /skill-name), programaticamente (Claude usa a ferramenta Skill), ou automaticamente (Claude descobre quando relevante).

O campo user-invocable controla apenas a invocação manual no menu de barra. Quando definido como false, a Habilidade fica oculta do menu, mas Claude ainda pode usá-la programaticamente ou descobrir automaticamente.

Exemplos Práticos para Sua Startup

Vamos ver padrões reais que você pode implementar imediatamente.

Seu Primeiro Projeto: Uma Habilidade Simples de Arquivo Único

Para começar, você não precisa de estrutura complexa. Uma Habilidade mínima precisa apenas de um arquivo SKILL.md.

Este exemplo ajuda Claude a gerar mensagens de commit examinando as alterações em staging:

commit-helper/
└── SKILL.md

---
name: generating-commit-messages
description: Gera mensagens de commit claras a partir de diferenças do git. Use ao escrever mensagens de commit ou revisar alterações em staging.
---

# Gerando Mensagens de Commit

## Instruções

1. Execute `git diff --staged` para ver as alterações
2. Vou sugerir uma mensagem de commit com:
   - Resumo com menos de 50 caracteres
   - Descrição detalhada
   - Componentes afetados

## Melhores práticas

- Use o tempo presente ("Add feature", não "Added feature")
- Explique o quê e porquê, não como
- Separe resumo e descrição com linha em branco

Essa Habilidade é perfeita para onboarding. É simples, imediatamente útil, e demonstra o conceito de forma clara.

Escalando com Múltiplos Arquivos

Conforme sua equipe cresce, você querrá Habilidades mais sofisticadas. Aqui está uma Skill de processamento de PDF que inclui documentos de referência, scripts utilitários, e usa allowed-tools para segurança:

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md:

---
name: pdf-processing
description: Extrai texto, preenche formulários, mescla PDFs. Use ao trabalhar com arquivos PDF, formulários ou extração de documentos.
allowed-tools: Read, Bash(python:*)
---

# Processamento de PDF

## Início rápido

Extrair texto:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Para preenchimento de formulários, veja FORMS.md.
Para referência detalhada da API, consulte REFERENCE.md.

Requisitos

pip install pypdf pdfplumber

Essa estrutura permite que você mantenha documentação abrangente sem sobrecarregar o contexto. Claude carrega detalhes apenas quando necessários.

## Otimizando e Resolvendo Problemas

Mesmo com o melhor design, às vezes as Habilidades não funcionam como esperado. Aqui estão as soluções para os problemas mais comuns que você encontrará.

### Quando Sua Habilidade Não É Acionada

O motivo mais comum: descrição vaga ou genérica. Claude não consegue detectar quando usar a Habilidade se a descrição não é específica o suficiente.

Descrições ruins não definem termos de gatilho claros. "Ajuda com documentos" é vaga demais. Claude não sabe quando essa Habilidade é relevante.

Descrições melhores são específicas sobre capacidades e incluem palavras-chave que os usuários mencionariam:

"Extrai texto, tabelas e metadados de PDFs, preenche formulários interativos, mescla múltiplos documentos. Use ao trabalhar com arquivos PDF, quando mencionar PDFs, formulários, extração de documentos, ou automação de documentos."

Essa descrição funciona porque nomeia ações específicas (extrair, preencher, mesclar) e inclui palavras-chave que acionam a Habilidade (PDF, formulários, extração).

### Carregamento Falhando

Verifique o caminho do arquivo e a sintaxe YAML primeiro:

As Habilidades devem estar no diretório correto com o nome de arquivo exato `SKILL.md` (sensível a maiúsculas):

- Pessoal: `~/.claude/skills/my-skill/SKILL.md`
- Projeto: `.claude/skills/my-skill/SKILL.md`

YAML inválido no frontmatter impede carregamento. O frontmatter deve começar com `---` na linha 1 (nenhuma linha em branco antes), terminar com `---` antes do conteúdo Markdown, e usar **espaços** para indentação (nunca tabulações).

Use `claude --debug` para ver erros de carregamento detalhados.

### Erros Durante Execução

**Se sua Habilidade usa pacotes externos**: Eles devem ser instalados no seu ambiente. `pip install pypdf pdfplumber` antes de usar.

**Scripts precisam de permissões**: Execute `chmod +x scripts/*.py` para tornar-os executáveis.

**Caminhos de arquivo**: Use barras estilo Unix em todos os caminhos. Escreva `scripts/helper.py`, não `scripts\helper.py`, mesmo em Windows.

### Múltiplas Habilidades em Conflito

Se Claude usa a Habilidade errada ou parece confuso entre Habilidades semelhantes, suas descrições são provavelmente muito parecidas.

Torne cada descrição distinta usando termos de gatilho específicos. Em vez de duas Habilidades de "análise de dados", diferencie-as: uma para "dados de vendas em Excel e exportações de CRM" e outra para "logs de servidor e métricas de sistema".

Quanto mais específicos seus termos de gatilho, mais fácil para Claude corresponder à Habilidade certa.

### Habilidades de Plugin Não Aparecem

Se você instalou um plugin mas suas Habilidades não aparecem:

1. Limpe o cache do plugin: `rm -rf ~/.claude/plugins/cache`
2. Reinstale o plugin: `/plugin install plugin-name@marketplace-name`

Isso força o Claude Code a baixar novamente e registrar as Habilidades.

Verifique que a estrutura de diretórios está correta — Habilidades devem estar em um diretório `skills/` na raiz do plugin:

my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── my-skill/
└── SKILL.md

## Compartilhando Habilidades Através de Sua Organização

Conforme sua startup cresce, você querrá padronizar e compartilhar Habilidades entre equipes.

**Habilidades de Projeto** são comitadas ao controle de versão em `.claude/skills/`. Qualquer pessoa que clonar o repositório as herda automaticamente.

**Plugins** permitem compartilhar Habilidades entre múltiplos repositórios. Crie um diretório `skills/` dentro do seu plugin com pastas de Habilidade contendo `SKILL.md`. Distribua através de marketplaces de plugins.

**Habilidades Gerenciadas** são implantadas por administradores através de configurações gerenciadas. Elas aplicam-se a toda a organização, padronizando processos em toda a empresa.

## Próximos Passos Para Sua Equipe

Você agora tem um mapa claro para implementar Habilidades. Comece pequeno: crie uma Habilidade simples de arquivo único que resolva um problema imediato da sua equipe. Pode ser geração de mensagens de commit, formatação de documentação, ou revisão de código.

Veja como funciona por uma semana. Observe onde Claude a usa e onde poderia ser melhor. Refine com base em feedback real da sua equipe.

Depois de dominar o padrão básico, expanda para Habilidades mais complexas com múltiplos arquivos, divulgação progressiva, e scripts utilitários. À medida que sua equipe cresce, use Habilidades Gerenciadas para padronizar processos em toda a organização.

A automação inteligente não é um luxo para startups — é um diferencial competitivo. Equipes que usam bem ferramentas como Habilidades conseguem escalar com menos frustração, mantêm padrões de qualidade mais altos, e deixam seus desenvolvedores focarem no que realmente importa: construir produtos incríveis que seus usuários adoram.

Comece hoje. Sua equipe futura agradecerá a você.

---

> Original source: [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
>
> powered by [osmu.app](https://osmu.app)