Skills Claude Code Modulares

🎯 Skills Modulares no Claude Code: O Guia Completo

Sou o Diogo Köpke, CEO da KopkAI, e há dois anos que trabalho com IA para automatizar processos em pequenas e médias empresas em Portugal. Vejo todos os dias donos de negócio a criar skills no Claude Code que parecem boas à primeira vista, mas que se tornam num pesadelo de manutenção em duas semanas. O problema? Metem o processo todo dentro de um único ficheiro gigante. Isso custa-te dinheiro em tokens, tempo em edição e precisão nos resultados.

Neste guia vais aprender a construir skills modulares: pequenas, específicas e reutilizáveis. Vais perceber porque é que uma skill de 800 linhas te está a custar 40€ por mês a mais em tokens, como dividir tarefas complexas em mini-skills que consegues editar em 3 minutos, e como criar uma skill pai que coordena tudo sem precisar de saber os detalhes técnicos de cada tarefa. No final, vais ter um sistema que pagas menos para usar, editas mais rápido e produz outputs mais precisos. Zero teoria, só implementação prática com números reais.

💸 O Problema (e o que te está a custar)

Imagina que criaste uma skill para processar encomendas. Ela extrai dados de emails, valida a informação, formata para o teu sistema de gestão, calcula portes e envia confirmação ao cliente. São cinco tarefas diferentes, mas meteste tudo num ficheiro único de 650 linhas. Sempre que carregas essa skill, o Claude lê as 650 linhas completas. Se usas o plano Pro (20€/mês) e processas 200 encomendas por mês, estás a consumir tokens para carregar contexto que não precisas 80% das vezes. Cada carregamento gasta cerca de 8.000 tokens. Em 200 execuções, são 1.600.000 tokens. Com o preço médio de 0,025€ por 1.000 tokens, pagas 40€ só para o Claude ler código que não muda.

Depois há o tempo de edição. Quando queres mudar a regra de cálculo de portes, tens de navegar por 650 linhas, encontrar a secção certa (geralmente entre linha 380 e 420), mudar o código sem partir nada à volta, testar tudo outra vez. Isso demora 45 minutos em média. Se fazes duas alterações por mês, são 90 minutos. A 30€ por hora (custo conservador de tempo de gestão em Portugal), são 45€ por mês só em tempo de edição. Soma aos 40€ de tokens desperdiçados: 85€ por mês, 1.020€ por ano, porque não dividiste a skill em módulos.

O pior é quando algo corre mal. Como tudo está misturado, um erro numa secção contamina as outras. Mudaste a validação de emails e de repente o cálculo de portes dá resultados errados. Passas 2 horas a descobrir que mexeste numa variável que era usada em três sítios diferentes. O código monolítico esconde dependências e torna o debugging numa caça ao tesouro. Para não falar que quando queres reutilizar só uma parte (por exemplo, a validação de emails noutra skill), tens de copiar 150 linhas e rezar para não copiar dependências escondidas.

🚀 A Solução: Skills Modulares

Skills modulares são pequenas unidades de código, cada uma com uma responsabilidade específica. Em vez de uma skill gigante que faz tudo, tens cinco mini-skills: extract_order_data.md (extrai dados de emails), validate_order.md (valida informação), format_for_system.md (formata para o teu sistema), calculate_shipping.md (calcula portes) e send_confirmation.md (envia email de confirmação). Cada uma tem 80 a 150 linhas. Depois tens uma skill pai, process_order.md, que apenas chama as outras na ordem certa. Quando carregas o processo, o Claude só lê a skill pai (40 linhas) e a mini-skill que precisa naquele momento. Resultado: gastas 2.000 tokens por execução em vez de 8.000.

A vantagem real aparece na edição. Queres mudar o cálculo de portes? Abres calculate_shipping.md, mudas a fórmula, guardas. Demora 5 minutos. Não tocas em mais nada. As outras skills continuam a funcionar exactamente igual. Queres reutilizar a validação de emails noutra skill? Copias validate_order.md e chamas-lhe validate_supplier_email.md. Mudas duas linhas de configuração e está pronto. Zero risco de copiar código extra ou criar dependências escondidas. O sistema torna-se manutenível, previsível e barato de operar.

🛠️ Pré-requisitos

Para implementar skills modulares precisas de acesso ao Claude Code e de uma forma de organizar os ficheiros. Vou listar tudo o que é necessário, com custos reais e onde arranjar. Nada disto é complicado, mas tens de ter as ferramentas certas antes de começar. Dificuldade: baixa. Tempo de setup: 20 minutos. Custo total mensal: entre 0€ (plano free) e 20€ (plano Pro se quiseres maior volume de uso).

• Claude.ai (https://claude.ai) — 0€/mês no plano free, 20€/mês no Pro. O plano free dá para começar e testar a abordagem modular. O Pro é útil se processas mais de 50 tarefas por dia ou precisas de respostas prioritárias.
• Claude Code (https://claude.ai/code) — incluído em qualquer plano Claude. É a interface onde vais criar e gerir as skills. Não pagas extra.
• Editor de texto simples — usar o Notepad++ (https://notepad-plus-plus.org) no Windows ou TextEdit no Mac. Se preferires algo mais robusto, Visual Studio Code (https://code.visualstudio.com) é grátis e tem syntax highlighting para Markdown.
• Pasta de organização local — cria uma pasta no teu computador chamada claude_skills com subpastas por projecto. Vais guardar aí todas as skills antes de fazer upload. Organização é metade do sucesso.
• Documentação oficial Anthropic (https://docs.anthropic.com/claude/docs/intro-to-claude) — lê pelo menos a secção sobre como funcionam as instruções de sistema e context window. Perceber isso ajuda a escrever skills mais eficientes.

Opcional mas útil: se trabalhas em equipa, usa um repositório Git (GitHub, https://github.com, grátis para repositórios privados) para versionar as skills. Assim toda a gente usa sempre a versão mais recente e tens histórico de mudanças. Não é obrigatório para começar, mas se vais usar isto a sério, compensa montar desde o início.

📋 Implementação Passo a Passo

Passo 1: Mapeia o teu processo em tarefas distintas

Pega no processo que queres automatizar e divide-o em tarefas que fazem uma coisa só. Por exemplo, se automatizas o processamento de candidaturas a emprego: receber CV, extrair informação relevante, comparar com requisitos da vaga, gerar resumo, enviar email de resposta. São cinco tarefas distintas. Cada uma merece uma skill. Escreve numa folha ou documento simples a lista completa. Não avances enquanto não tiveres isto claro. Se uma tarefa parece fazer duas coisas diferentes, divide em duas tarefas.

Resultado esperado: uma lista de 4 a 8 tarefas bem definidas, cada uma com um nome claro e uma responsabilidade única. Exemplo: 1) extract_cv_data, 2) validate_required_fields, 3) compare_requirements, 4) generate_summary, 5) send_response_email.

Passo 2: Cria a estrutura de pastas

No teu computador, cria uma pasta claude_skills e dentro dela uma subpasta com o nome do projecto, por exemplo recruitment_automation. Dentro dessa subpasta cria duas pastas: modules (onde vão as mini-skills) e main (onde vai a skill pai). Esta organização mantém tudo separado e fácil de encontrar. Quando tiveres cinco projectos diferentes, cada um tem a sua subpasta e não se misturam.

Resultado esperado: estrutura de pastas organizada e pronta para receber os ficheiros de skills. Exemplo: claude_skills/recruitment_automation/modules/ e claude_skills/recruitment_automation/main/.

Passo 3: Escreve a primeira mini-skill

Começa pela tarefa mais simples. Geralmente é uma extracção de dados ou uma validação básica. Cria um ficheiro na pasta modules chamado extract_cv_data.md. Abre-o no editor de texto e escreve as instruções em português claro: 'Tu és um assistente que extrai informação de currículos. Recebe um texto de CV e devolve um JSON com nome, email, telefone, anos de experiência e competências principais. Se algum campo não existir, devolve null. Não inventes informação.' Guarda o ficheiro.

Porque importa: esta é a base de tudo. Se as instruções forem claras e específicas, a skill funciona. Se forem vagas, vais perder tempo a corrigir outputs. Escreve como se estivesses a explicar a um estagiário novo o que fazer. Quanto mais directo, melhor.

Resultado esperado: um ficheiro extract_cv_data.md com instruções claras, exemplos de input e output, e guardado na pasta modules.

Passo 4: Testa a mini-skill isoladamente

Vai ao Claude Code, faz upload da skill extract_cv_data.md e testa-a com um CV real. Copia o texto de um currículo (pode ser fictício mas realista) e pede ao Claude para processar. Verifica se o output está no formato que pediste e se os dados extraídos estão correctos. Se não estiver, ajusta as instruções na skill e testa outra vez. Não avances para a segunda skill enquanto esta não funcionar a 100%.

Porque importa: testar cada módulo isoladamente garante que sabes exactamente o que funciona e o que não funciona. Se testares tudo junto no fim, vais ter 5 skills com problemas e não sabes qual está a falhar. Corrige uma de cada vez, valida, passa à seguinte.

Resultado esperado: skill testada e validada, com output consistente e correcto. Ficheiro final ajustado e guardado.

Passo 5: Replica para as restantes mini-skills

Repete o passo 3 e 4 para cada uma das tarefas que mapeaste no passo 1. Cria validate_required_fields.md, compare_requirements.md, generate_summary.md e send_response_email.md. Cada uma com as suas instruções específicas, exemplos de input/output e testada isoladamente. Este é o trabalho braçal, mas é rápido: cada skill demora 10 a 15 minutos a escrever e testar. No fim tens 5 módulos que funcionam perfeitamente sozinhos.

Porque importa: nesta fase estás a construir os blocos fundamentais. Se cada bloco for sólido, o sistema final é sólido. Se fores rápido e não testares bem, vais gastar o dobro do tempo a corrigir depois. Vale a pena fazer bem à primeira.

Resultado esperado: 4 a 8 mini-skills criadas, testadas individualmente e guardadas na pasta modules. Cada uma com instruções claras e outputs validados.

Passo 6: Escreve a skill pai (routing skill)

Agora crias o coordenador. Na pasta main, cria um ficheiro process_application.md. Este ficheiro não faz trabalho pesado, só decide qual mini-skill chamar e em que ordem. Escreve as instruções assim: 'Tu és o coordenador do processo de candidaturas. Quando receberes um CV, chamas extract_cv_data. Com o resultado, chamas validate_required_fields. Se passar, chamas compare_requirements e depois generate_summary. No fim, chamas send_response_email com o summary criado. Se em qualquer passo houver erro, interrompes e reportas qual foi.' Guarda o ficheiro.

Porque importa: a skill pai é o cérebro que decide o fluxo. Ela não precisa saber como extrair dados ou como validar, só precisa saber que tarefa vem a seguir. Isto mantém a lógica de negócio separada da execução técnica. Se mudares a ordem das tarefas, mudas só aqui.

Resultado esperado: ficheiro process_application.md criado, com a lógica de routing clara, guardado na pasta main.

Passo 7: Testa o fluxo completo

Faz upload da skill pai e das mini-skills para o Claude Code. Executa o processo completo com um caso de teste real. Fornece um CV e deixa o Claude seguir o fluxo: extract, validate, compare, generate, send. Observa se cada etapa é chamada correctamente e se o output final está como esperado. Se houver falha em algum ponto, verifica se é problema da mini-skill (volta ao passo 4) ou da lógica de routing (corrige na skill pai).

Porque importa: este é o teste de integração. Cada peça funciona sozinha, mas tens de garantir que funcionam juntas. Problemas comuns: formato de output de uma skill não é o input esperado pela seguinte, ou a skill pai não passa variáveis correctamente. Corrige até o fluxo correr sem intervenção.

Resultado esperado: fluxo completo a funcionar de ponta a ponta, sem erros, com outputs consistentes em vários testes.

Passo 8: Documenta o sistema

Cria um ficheiro README.md na raiz da pasta do projecto (recruitment_automation) e escreve uma explicação rápida: qual é o objectivo do sistema, quais são as mini-skills e o que cada uma faz, como executar o fluxo completo, e onde estão os casos de teste. Não precisa de ser longo, mas precisa de existir. Daqui a 3 meses quando voltares a olhar para isto, vais agradecer ter esta documentação.

Porque importa: sem documentação, o sistema modular perde metade do valor. Documentação simples permite que outra pessoa (ou tu daqui a uns meses) perceba rapidamente como tudo funciona e onde mudar cada coisa. Demora 10 minutos a escrever e poupa horas de confusão.

Resultado esperado: ficheiro README.md criado, com descrição do sistema, lista de skills, instruções de uso e localização dos testes.

🧰 Ferramentas e Recursos

💼 Caso Prático: Escritório de Contabilidade

Imagina uma firma de contabilidade com 7 pessoas que processa 180 declarações de IVA por trimestre. Antes, tinham uma skill monolítica de 720 linhas chamada process_vat_declaration.md que fazia tudo: extrair dados dos PDFs de facturas, validar NIF e valores, calcular o IVA total, preencher formulário, gerar declaração e enviar email ao cliente. Cada vez que executavam a skill, consumiam 9.200 tokens. Trimestre com 180 declarações: 1.656.000 tokens, cerca de 41€ em custos de API. Sempre que mudava alguma regra de cálculo (2 vezes por trimestre), o colaborador demorava 50 minutos a encontrar e corrigir o código, testava tudo outra vez. 100 minutos por trimestre a 30€/hora: 50€.

Implementaram skills modulares em 6 horas de trabalho: extract_invoice_data.md (80 linhas), validate_tax_ids.md (65 linhas), calculate_vat_totals.md (95 linhas), fill_declaration_form.md (110 linhas), generate_pdf.md (70 linhas) e send_client_email.md (55 linhas). Skill pai: process_vat.md com 45 linhas de routing. Agora cada execução consome 2.400 tokens (skill pai + só os módulos necessários). Trimestre com 180 declarações: 432.000 tokens, 10,80€. Poupança de 30,20€ por trimestre só em tokens. Mudanças de regras: abrir calculate_vat_totals.md, alterar fórmula, testar. 8 minutos. Duas vezes por trimestre: 16 minutos a 30€/hora: 8€. Poupança de 42€ por trimestre. Total anual: 168€ menos em custos directos. Tempo de implementação compensado em 3 meses.

⚠️ Erros Comuns e Como Evitar

Erro 1: Dividir demasiado e criar dependências complexas

Acontece quando crias 15 mini-skills para um processo simples de 4 tarefas. Cada skill chama 3 outras, que chamam mais 2 cada. O routing fica um labirinto e é pior que a skill monolítica. Como evitar: regra prática, 1 skill por cada tarefa que consegues descrever num parágrafo. Se precisas de dois parágrafos para explicar, são duas skills. Se precisas de meia frase, não justifica skill própria.

Erro 2: Não testar cada módulo isoladamente

Escreves as 5 mini-skills e a skill pai de uma vez, fazes upload de tudo e testas o fluxo completo. Dá erro. Não sabes qual módulo está a falhar. Passas 40 minutos a testar um por um à mesma. Como evitar: disciplina. Escreve uma skill, testa até funcionar, guarda. Só depois escreves a seguinte. Demora o mesmo tempo total, mas sabes sempre qual está validada e qual ainda não.

Erro 3: Skills pai com lógica de negócio

Metes cálculos ou validações dentro da skill pai. Ela deixa de ser só routing e passa a ter responsabilidades próprias. Quando algo falha, não sabes se é routing ou lógica. Como evitar: a skill pai só decide ordem e passa variáveis. Todo o trabalho real acontece nos módulos. Se a skill pai tem mais de 60 linhas, provavelmente está a fazer trabalho demais.

Erro 4: Nomes vagos nas skills

Chamas às skills process1.md, helper.md, task.md. Daqui a 2 semanas não sabes qual faz o quê. Como evitar: nomes descritivos com verbo e objecto. Exemplos: extract_invoice_data, validate_client_nif, calculate_total_vat. Lês o nome e sabes imediatamente o que faz.

Erro 5: Não documentar o fluxo

Tens 6 módulos e uma skill pai, funciona tudo bem, mas não escreveste em lado nenhum qual é a ordem de execução ou o que cada módulo espera receber. Quando tens de explicar a um colega, perdes 30 minutos a percorrer ficheiros. Como evitar: README.md obrigatório. Duas secções: lista de módulos com descrição curta, e fluxo de execução passo a passo. Demora 10 minutos a escrever.

Erro 6: Formatos de dados inconsistentes entre módulos

O módulo A devolve um objecto JSON, o módulo B espera receber uma lista. A skill pai tenta passar um para o outro e dá erro. Como evitar: define no início um formato padrão de dados (exemplo: sempre JSON com campos específicos) e todas as skills seguem esse formato. Documenta isso no README e valida nos testes.

Erro 7: Não versionar as skills

Mudas uma skill, guarda por cima do ficheiro antigo. Uma semana depois percebes que a versão antiga funcionava melhor e já não tens como voltar atrás. Como evitar: usa Git (mesmo que sejas só tu) ou pelo menos faz cópias com data no nome (extract_invoice_data_2025-01-15.md) antes de mudar. Permite voltar atrás sem perder trabalho.

✅ Checklist de Implementação

Fase 1: Setup (20 min)

• Criar conta no Claude.ai e activar Claude Code
• Instalar editor de texto (VS Code ou Notepad++)
• Criar estrutura de pastas: claude_skills/[projecto]/modules/ e /main/
• Criar pasta test_cases para guardar exemplos de teste
• Ler documentação básica do Anthropic sobre context window

Fase 2: Construção (2-4 horas)

• Mapear o processo em 4 a 8 tarefas distintas
• Escrever primeira mini-skill com instruções claras e exemplos
• Testar primeira mini-skill isoladamente até funcionar 100%
• Replicar para as restantes mini-skills, testando cada uma
• Escrever skill pai com lógica de routing
• Criar ficheiro README.md com documentação básica

Fase 3: Teste (1-2 horas)

• Fazer upload de todas as skills para Claude Code
• Executar fluxo completo com caso de teste simples
• Executar fluxo com caso de teste complexo (dados em falta ou erro)
• Executar fluxo com caso de teste edge case (formato estranho)
• Corrigir problemas de integração entre módulos
• Validar que outputs estão consistentes nos 3 testes

Fase 4: Lançamento (30 min)

• Fazer backup de todas as skills (Git ou cópia local com data)
• Actualizar README com versão e data de lançamento
• Executar 5 casos reais para validar em produção
• Documentar quaisquer ajustes necessários após primeiros usos
• Agendar revisão em 2 semanas para verificar se há melhorias

Preferes que isto seja feito por nós? Conhece o nosso serviço de inteligência artificial para empresas.

Guias relacionados

• Hooks Claude Code que Poupam Horas
• Agentes Autónomos: Quando Confiar e Quando Não
• Mapa de Ferramentas AI Para Negócios