Como criar uma skill de IA que roda automaticamente na sua empresa

Uma skill é um arquivo de texto com três coisas: quando a IA deve rodar, o que ela faz passo a passo, e como entrega o resultado. Você cria uma vez. Depois é só chamar — ou nem chamar, se configurar um gatilho automático.

O que é uma skill e por que simplifica sua vida?

Skill no Claude Code é um arquivo Markdown que funciona como instrução permanente para um comportamento específico. Você não precisa repetir “toda segunda-feira faça X, depois Y, depois Z” toda vez que abre o chat. Você escreveu isso uma vez no arquivo, e a IA segue.

O conceito é simples: todo processo repetível que você explica pra IA pode virar skill. A diferença entre “prompt solto” e skill é que o prompt você perde no histórico da conversa. A skill fica versionada, testada e disponível pra sua equipe inteira.

Segundo benchmarks internos de times que usam o Claude Code com skills documentadas, o tempo médio de execução de tarefas recorrentes cai 60-70% porque a IA não precisa de contexto adicional — ela já tem tudo no arquivo.

Como identificar uma tarefa que vira skill?

Pergunta simples: você explicou o mesmo processo pra IA mais de duas vezes? Então é candidato.

Critérios objetivos para uma tarefa virar skill:

• Recorrência: acontece toda semana, todo mês, ou toda vez que um evento ocorre (cliente fecha, lead entra, reunião termina)
• Processo estável: os passos não mudam muito de execução pra execução
• Fonte de dados definida: a IA vai buscar informação de algum lugar específico (CRM, planilha, email, API)
• Output padronizado: o resultado tem sempre o mesmo formato (resumo executivo, email de follow-up, relatório)

Exemplos que viram skills boas: relatório semanal de vendas, triagem de email matinal, resumo de reunião, onboarding de cliente novo, reativação de lead parado.

O que não vira skill: decisões que dependem de julgamento humano em cima de informação nova, criação criativa que precisa variar muito, ou tarefas que você faz uma vez só.

Qual é a estrutura de um arquivo SKILL.md?

O arquivo tem quatro seções obrigatórias e uma opcional:

# Nome da skill (kebab-case, descritivo)

## Quando ativar
[gatilho: comando manual, horário automático, evento externo]

## O que fazer (passo a passo)
1. Passo 1
2. Passo 2
3. ...

## Formato do output
[como entregar o resultado: tabela, bullets, parágrafo, JSON, etc.]

## Contexto adicional (opcional)
[regras de negócio, exceções, definições específicas]

Isso é tudo. Não precisa ser um documento de 10 páginas. Skills boas têm entre 30 e 80 linhas. Se ficou maior que isso, provavelmente você está colocando duas skills num arquivo só — divide.

Um detalhe importante: o nome do arquivo e o nome interno da skill precisam ser consistentes. Se o arquivo se chama relatorio-semanal.md, a skill se chama relatorio-semanal. Quando você digita /relatorio-semanal no Claude Code, ele encontra e executa.

Como criar a skill de relatório semanal do zero?

Essa é a skill que a gente vai construir aqui: toda segunda às 9h, a IA puxa dados do Pipedrive, agrega métricas de vendas da semana anterior e gera um resumo executivo pronto pra você ler em dois minutos.

Passo 1: documente o processo em texto livre.

Antes de escrever o arquivo, escreva em linguagem natural o que você faz hoje. Exemplo:

“Toda segunda de manhã eu entro no Pipedrive, vejo quantos deals avançaram de etapa na semana passada, quanto entrou de receita nova, quais deals estão parados há mais de 7 dias e quais atividades vencem essa semana. Depois mando um resumo pro meu sócio.”

Passo 2: estruture em passos numerados.

Pega esse texto e transforma em ações concretas que a IA executa. Cada passo tem um verbo de ação e uma fonte de dado específica.

Passo 3: escreva o SKILL.md.

# relatorio-semanal

## Quando ativar
- Toda segunda-feira às 9h (automático via cron)
- Ou quando o usuário digitar `/relatorio-semanal`

## O que fazer

1. Usar `mcp__pipedrive__list_deals` com filtro `updated_after: 7 dias atrás`
2. Separar deals por etapa do pipeline Educacional (ID 6) e pipeline SaaS (ID 1)
3. Calcular: (a) total de deals avançados de etapa, (b) soma de valor dos deals fechados na semana, (c) deals sem atividade há mais de 7 dias
4. Buscar atividades com `mcp__pipedrive__list_activities` com `due_date: próximos 5 dias`
5. Montar o resumo executivo seguindo o formato abaixo

## Formato do output

**Semana de [data início] a [data fim]**

**Negócios:**
- X deals avançaram de etapa
- R$ Y em negócios fechados
- Z deals parados (lista com nome + dias parado)

**Esta semana vence:**
- [lista de atividades com nome do deal, tipo, data]

**Atenção:**
- [deals em risco: parados + sem atividade futura agendada]

## Contexto adicional

- Pipelines ativos: Educacional (6) e SaaS (1)
- "Deal parado" = sem mudança de etapa e sem atividade registrada em 7+ dias
- Valores em R$ (BRL), sem casas decimais
- Se não houver dados pra alguma seção, escrever "Nenhum registro"

Passo 4: salve em ~/.claude/skills/relatorio-semanal.md (ou na pasta de skills do seu projeto se for compartilhado com equipe).

Como testar e ajustar a skill?

Regra: rode três vezes antes de confiar.

Primeira rodada: execute manualmente digitando /relatorio-semanal e leia o output palavra por palavra. Identifique o que está errado, incompleto ou que a IA interpretou diferente do que você queria.

Segunda rodada: ajuste o arquivo baseado nos erros. As correções mais comuns são: passo com verbo ambíguo (“verificar” vs “listar todos”), formato de output que não ficou como esperado, ou contexto adicional que faltou (ex: você esqueceu de dizer que deals perdidos não entram na conta).

Terceira rodada: se o output ficou bom, teste com dados de uma semana mais antiga pra ver se o comportamento é consistente quando há volume diferente de dados.

Dois erros clássicos: (1) escrever o passo a passo muito genérico, e a IA tomar decisões que você não previu; (2) escrever específico demais, e a skill quebrar quando um campo do CRM muda de nome. O equilíbrio é: específico nas fontes de dado e no formato de output, flexível nos passos intermediários.

Como distribuir a skill pra sua equipe?

Se você usa Git, a distribuição é trivial: skills ficam em ~/.claude/skills/ localmente, mas você pode versionar o diretório num repositório e distribuir com um script de instalação.

A Expert Integrado usa um repositório central chamado expertintegrado/skills com um marketplace.json. Qualquer colaborador instala todas as skills da empresa com dois comandos:

/plugin marketplace add expertintegrado/skills
/plugin install skills@expertintegrado

Se você não tem estrutura de plugin ainda, o fluxo mais simples é: repositório Git com a pasta skills/, README explicando como copiar os arquivos pra ~/.claude/skills/, e instrução no onboarding de colaborador novo.

O ponto crítico: skills são documentação viva. Quando o processo muda, o arquivo muda. Se você tem cinco pessoas usando a mesma skill e ninguém atualiza o arquivo quando o processo evolui, em três meses a skill está desatualizada e gera output errado. Atribua um dono pra cada skill — alguém responsável por manter o arquivo correto.

---

Perguntas frequentes

Preciso saber programar pra criar uma skill? Não. O arquivo é Markdown puro — basicamente um documento de texto com formatação simples. Você precisa saber descrever um processo em passos, o que qualquer gestor já faz naturalmente em SOPs e checklists. A parte técnica (como a IA acessa o Pipedrive, por exemplo) é responsabilidade dos MCPs já configurados, não do arquivo da skill.

Qual a diferença entre skill e prompt salvo? Prompt salvo é texto que você cola numa conversa. Skill é um comportamento que a IA conhece pelo nome e executa com contexto completo, incluindo passos, formato de output e regras de negócio. Skill também é versionável, testável e distribuível pra equipe. Prompt salvo vive no seu clipboard ou num Notion em algum lugar que você vai esquecer.

A skill funciona sem o Claude Code? Não da forma descrita aqui. Skills no formato SKILL.md são uma funcionalidade nativa do Claude Code. No Claude.ai web ou no app mobile você pode usar prompts salvo ou instruções de sistema, mas sem o mecanismo de gatilho automático e sem integração direta com MCPs locais.

Quantas skills é razoável ter? Sem número mágico, mas com balizamento prático: se você não consegue listar de cabeça o nome e o propósito de cada skill que tem, provavelmente tem mais do que consegue manter. Times que usam bem costumam ter 10-20 skills ativos e arquivam os outros. Qualidade e manutenção valem mais que quantidade.

Uma skill pode chamar outra skill? Sim. Você pode referenciar outra skill dentro dos passos de execução. Isso é útil quando você tem um processo composto — por exemplo, a skill de onboarding-cliente pode chamar a skill de criar-deal-pipedrive como um dos passos. Mantenha a dependência explícita no arquivo pra quem for manter depois entender o encadeamento.

---

Bora testar? Pega um processo que você repete toda semana, documenta em texto livre, e transforma num SKILL.md seguindo a estrutura acima. Três rodadas de teste e você tem algo que roda sozinho — sem precisar explicar de novo toda vez.