Pare de Construir Agentes de IA — Comece a Construir Skills
Passei três meses no ano passado construindo um agente de IA personalizado do zero. Centenas de linhas de system prompts. Definições de ferramentas cuidadosamente ajustadas. Lógica de retry, tratamento de erros, regras de formatação de saída — a produção completa. Funcionava perfeitamente para um fluxo de trabalho específico. Então o cliente me pediu para adicionar um segundo fluxo de trabalho, e percebi que tinha construído uma obra-prima que não conseguia crescer.
O agente sabia fazer exatamente uma coisa muito bem. Adicionar uma segunda significava reescrever metade da arquitetura. Adicionar uma terceira significaria começar do zero.
Parece familiar? Se você construiu qualquer tipo de agente de IA no último ano, provavelmente bateu nessa parede. Seu agente é brilhante na tarefa original e completamente perdido no momento em que você o empurra para fora dessa faixa. Eu chamava isso de "armadilha do especialista brilhante" — e não consegui descobrir como contornar isso até assistir Barry e Mahes apresentarem algo que reformulou tudo que eu pensava saber sobre desenvolvimento de agentes.
Eles não construíram um agente melhor. Eles construíram uma forma melhor de ensinar agentes. E a diferença entre essas duas ideias é o abismo entre onde a maioria dos desenvolvedores está presa e para onde todo esse campo está caminhando.
Por Que Seu Agente Brilhante Na Verdade É Meio Burro
Aqui vai um experimento mental que mudou a forma como eu abordo arquitetura de agentes.
Pegue a pessoa mais inteligente que você conhece. Dê a ela uma tarefa que nunca encontrou antes — digamos, preencher uma declaração de imposto corporativo na Alemanha, ou realizar um tratamento de canal. A inteligência bruta continua lá. A capacidade de raciocínio não mudou. Mas ela vai falhar espetacularmente porque inteligência sem conhecimento procedimental é apenas energia potencial sem direção.
É exatamente isso que está acontecendo com agentes de IA agora. Claude, GPT-4, Gemini — esses modelos são raciocinadores extraordinariamente capazes. Mas quando você os implanta como agentes, está essencialmente jogando um gênio em um trabalho desconhecido e dizendo "se vira." Às vezes eles conseguem. Muitas vezes não. E mesmo quando acertam, a qualidade é inconsistente porque estão raciocinando a partir de princípios fundamentais toda vez, em vez de aplicar procedimentos aprendidos.
O desenvolvimento tradicional de agentes tenta resolver isso enfiando tudo no system prompt. Você escreve parágrafo após parágrafo de instruções: "Quando o usuário perguntar sobre X, primeiro verifique Y, depois formate a saída como Z, e se houver um erro, faça W." Já escrevi system prompts que eram literalmente mais longos que o código que controlavam.
O problema não é que essa abordagem não funcione. Funciona — para um agente fazendo uma coisa. O problema é que nada desse conhecimento é transferível. Construa um segundo agente para uma tarefa diferente e você começa do zero. Cada instrução, cada caso extremo, cada insight duramente conquistado sobre como lidar com falhas — trancado dentro de um único arquivo de prompt, invisível para todo o resto do seu sistema.
Barry e Mahes articularam o que eu vinha sentindo mas não conseguia nomear: agentes têm inteligência e capacidades, mas carecem de expertise organizada. São generalistas brilhantes que conseguem raciocinar sobre qualquer coisa, mas não dominaram nada. E a solução não é construir agentes mais inteligentes — é dar aos agentes uma forma de adquirir, armazenar e compartilhar expertise.
Essa solução são as skills. E a arquitetura por trás delas é mais engenhosa do que parece à primeira vista.
O Que Skills de Agentes Realmente São (E Por Que Não São Apenas Prompts Enfeitados)
Quando ouvi "agent skills" pela primeira vez, presumi que era uma reembalagem de templates de prompt. Não é. A diferença é estrutural, e isso importa.
Uma skill é uma pasta. É isso no nível mais básico — um diretório contendo arquivos que codificam conhecimento procedimental. Mas a composição específica desses arquivos é onde o design fica interessante:
Scripts (ferramentas): Código executável que dá ao agente novas capacidades. Uma skill para web scraping pode incluir um script Python que lida com autenticação, paginação e rate limiting. O agente não precisa descobrir como fazer scraping — ele chama o script.
Instruções em Markdown: Conhecimento procedimental escrito em linguagem natural. Quando usar a skill, em que ordem executar os passos, quais casos extremos observar, como formatar as saídas. É aqui que a expertise de domínio mora.
Assets: Arquivos de configuração, templates, dados de referência, exemplos de saída — qualquer coisa que a skill precise para fazer seu trabalho de forma consistente.
Aqui está a escolha de design que faz essa arquitetura funcionar: progressive disclosure. Quando o Claude Code carrega suas skills, ele não despeja todas na janela de contexto de uma vez. Ele vê apenas os metadados — o nome da skill, uma breve descrição e condições de ativação. O conteúdo completo da skill é carregado somente quando o agente realmente precisa.
Por que isso importa? O gerenciamento da janela de contexto é a maior restrição em sistemas de agentes. Cada token gasto em instruções que você não está usando no momento é um token roubado do raciocínio sobre a tarefa em questão. O progressive disclosure significa que você pode ter cinquenta skills instaladas sem pagar o custo de contexto de todas as cinquenta simultaneamente. O agente vê um menu de capacidades e puxa a receita relevante somente quando começa a cozinhar.
Testei isso com minha própria configuração. Tenho skills para front-end design, auditoria de SEO, geração de conteúdo, análise de segurança e automação de deploy. O Claude Code me mostra a lista quando pergunto quais skills estão disponíveis. Mas quando digo "redesenhe esta página," apenas o conteúdo completo da skill de front-end design é carregado. Minha skill de SEO fica quietinha em segundo plano, pronta mas sem consumir tokens.
Compare isso com a abordagem de system prompt monolítico. Com tudo em um único prompt, você paga o custo de contexto para cada capacidade, usando-a ou não. É como carregar todas as ferramentas da loja de materiais nos bolsos em vez de ir até o corredor certo quando precisar de algo.
Mas a estrutura baseada em pastas desbloqueia algo ainda mais importante que eficiência de contexto — e essa é a parte que a maioria das pessoas ainda não percebeu.
A Verdadeira Jogada de Mestre: Skills São Software, Não Prompts
Porque skills são apenas pastas com arquivos, elas herdam todas as propriedades de software que já sabemos gerenciar.
Controle de versão. Coloque sua pasta de skills em um repositório Git e você tem histórico completo. Quem mudou o quê, quando, por quê. Reverta uma skill para a versão de terça passada porque a nova introduziu um bug. Crie um branch de uma skill para testar modificações sem afetar a versão principal. Isso é fundamental para software, mas revolucionário para engenharia de prompts, que tradicionalmente era "edite o prompt, torça para funcionar, reze para lembrar o que mudou."
Compartilhamento e colaboração. Compacte uma pasta de skill, envie para um colega, e ele tem sua capacidade exata. Nada de "copie este prompt e ajuste para o seu setup." Nada de "certifique-se de mudar também a config do modelo." A skill é autocontida. Tudo que ela precisa está na pasta.
Composabilidade. Essa é a grande sacada. Múltiplas skills podem coexistir e se complementar. Minha skill de front-end design cuida das mudanças visuais. Minha skill de SEO cuida da otimização. Quando peço ao Claude para "redesenhar esta página e corrigir o SEO," ambas as skills são ativadas. Elas não entram em conflito porque cada uma opera em seu próprio domínio com suas próprias instruções.
Tenho tratado skills como microsserviços para conhecimento de agentes. Cada skill tem uma única responsabilidade, uma interface limpa e nenhuma dependência oculta de outras skills. Quando preciso de uma nova capacidade, não modifico uma skill existente — crio uma nova. Quando uma skill fica obsoleta, deleto a pasta. Sem necessidade de refatoração.
Essa analogia com microsserviços vai mais fundo do que eu esperava. Em software tradicional, microsserviços se comunicam por APIs. Na arquitetura de skills, as skills se comunicam através do raciocínio do agente — o modelo age como a camada de orquestração, decidindo quais skills invocar e como combinar suas saídas. É uma inversão elegante do padrão usual.
E o ecossistema crescendo em torno desse conceito está se movendo mais rápido do que eu antecipei. Deixe-me mostrar o que realmente existe por aí.
As Três Camadas do Ecossistema de Skills
Cinco semanas após o lançamento, milhares de skills já existem. Elas se dividem em três categorias que revelam muito sobre para onde essa tecnologia está caminhando.
Camada 1: Skills fundamentais. São capacidades de propósito geral que tornam agentes melhores em tarefas comuns. Edição de documentos, síntese de pesquisa científica, análise de dados, code review. Pense nelas como a biblioteca padrão — as skills que a maioria dos agentes provavelmente deveria ter instaladas. A skill de front-end design que uso tem mais de 100.000 instalações. A skill de auditoria de SEO tem cerca de 19.000. Esses números dizem algo sobre a demanda.
Camada 2: Skills de terceiros. É aqui que as coisas ficam interessantes. Empresas estão construindo skills para seus próprios produtos. A Browserbase criou uma skill de automação web que permite ao Claude navegar e interagir com páginas web através de sua infraestrutura. A Notion construiu uma skill de integração com workspace. Essas não são genéricas — são construídas sob medida pelas equipes que melhor conhecem suas ferramentas.
O que acho mais atraente nas skills de terceiros é o alinhamento de incentivos. A Browserbase quer que desenvolvedores usem sua plataforma. Construir uma skill do Claude Code que torna sua plataforma fácil de usar é uma distribuição brilhante. A skill se torna a interface do usuário, e o Claude se torna o usuário. Espero que toda grande ferramenta de desenvolvedor lance uma skill do Claude Code nos próximos doze meses.
Camada 3: Skills empresariais. Essa é a camada que ninguém comenta publicamente, mas é onde o dinheiro real está. Empresas da Fortune 100 estão construindo skills internas que codificam seus fluxos de trabalho específicos, melhores práticas, requisitos de conformidade e conhecimento institucional.
Imagine uma empresa de serviços financeiros que constrói uma skill codificando seus procedimentos específicos de avaliação de risco. Todo analista usando o Claude Code tem acesso ao mesmo conhecimento procedimental — os mesmos checklists, as mesmas referências regulatórias, os mesmos requisitos de formatação. Novos funcionários se adaptam mais rápido porque a skill carrega a expertise que antes existia apenas na cabeça dos funcionários seniores.
Comecei a fazer isso para meus próprios clientes. Quando entrego um projeto, incluo uma pasta de skill que codifica os procedimentos de manutenção do projeto. Como fazer deploy. Como rodar testes. Quais são as convenções de nomenclatura. Onde ficam os arquivos de configuração. A equipe do cliente não precisa memorizar minha documentação — eles perguntam ao Claude, e a skill fornece a resposta com os comandos exatos para executar.
Isso é gestão de conhecimento procedimental em sua forma mais pura. E resolve um problema que vi organizações enfrentarem durante toda minha carreira: como preservar o conhecimento institucional quando as pessoas saem?
Construindo Sua Primeira Skill: O Guia Prático
Chega de teoria. Aqui está como realmente construir uma skill. Vou mostrar a criação de uma que construí mês passado — uma skill de verificação de deploy que checa se um deploy foi bem-sucedido e reporta quaisquer problemas.
Passo 1: Crie a estrutura de pastas.
deployment-check/
├── skill.md
├── tools/
│ └── verify-deployment.sh
└── examples/
└── sample-output.md
O arquivo skill.md é o cérebro. Ele contém as condições de ativação, instruções e contexto:
# Deployment Verification Skill
## Trigger
Activate when the user asks to verify, check, or validate
a deployment, or after any deploy command completes.
## Instructions
1. Run the verify-deployment.sh script with the target URL
2. Check HTTP status codes for all critical endpoints
3. Verify SSL certificate validity
4. Compare response times against baseline
5. Check for error patterns in response bodies
6. Generate a summary report with pass/fail status
## Edge Cases
- If the site returns 503, wait 30 seconds and retry once
- If SSL check fails, note whether the cert is expired
or misconfigured
- If response times exceed 2x baseline, flag as warning
not failure
Passo 2: Escreva o script da ferramenta.
#!/bin/bash
# verify-deployment.sh
# Checks critical health indicators for a deployed site
TARGET_URL=$1
echo "## Deployment Verification Report"
echo "Target: $TARGET_URL"
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""
# Check HTTP status
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$TARGET_URL")
echo "### HTTP Status: $STATUS"
# Check SSL
SSL_EXPIRY=$(echo | openssl s_client -connect \
"${TARGET_URL#https://}:443" 2>/dev/null | \
openssl x509 -noout -enddate 2>/dev/null)
echo "### SSL: $SSL_EXPIRY"
# Check response time
RESPONSE_TIME=$(curl -s -o /dev/null \
-w "%{time_total}" "$TARGET_URL")
echo "### Response Time: ${RESPONSE_TIME}s"
Passo 3: Teste.
Instale a skill no seu ambiente Claude Code e execute:
Verify the deployment at https://mysite.com
O Claude detecta o gatilho da skill, carrega as instruções completas, executa o script de verificação e formata a saída de acordo com as instruções da skill. Na primeira vez que rodei, ele pegou um certificado SSL que ia expirar em três dias — algo que eu teria perdido até os usuários começarem a ver avisos no navegador.
Dica profissional: Comece suas skills simples. Minha primeira versão dessa skill era apenas as instruções em markdown sem script — o Claude executava os comandos curl ele mesmo com base nas instruções procedimentais. Adicionei o script depois quando quis uma formatação de saída mais consistente. Você não precisa engenheirar demais as skills no primeiro dia. Deixe-as evoluir com base no uso real.
A Arquitetura Por Trás dos Bastidores: Skills + MCP
Uma peça desse quebra-cabeça que eu não entendia inicialmente era como skills se relacionam com servidores MCP. Pareciam redundantes — ambos estendem o que o Claude pode fazer, então qual é a diferença?
Depois de trabalhar extensivamente com ambos, aqui está o modelo mental que fez sentido para mim.
Servidores MCP (Model Context Protocol) cuidam da conectividade. São o encanamento que permite ao Claude conversar com sistemas externos — bancos de dados, APIs, sistemas de arquivos, serviços de terceiros. Um servidor MCP para GitHub permite ao Claude ler repositórios, criar issues e abrir pull requests. Um servidor MCP para Slack permite ao Claude enviar mensagens e ler canais.
Skills cuidam da expertise. São o conhecimento que diz ao Claude o que fazer com essas conexões e como fazer bem.
Pense nisso como uma cozinha. Servidores MCP são os eletrodomésticos — o fogão, o forno, a batedeira. Skills são as receitas. Ter um fogão não faz de você um chef. Ter uma receita não cozinha a comida. Você precisa dos dois.
Na prática, isso significa que skills frequentemente dependem de servidores MCP. Minha skill de verificação de deploy usa comandos curl que rodam através do acesso shell do Claude. Uma versão mais sofisticada poderia usar um servidor MCP para infraestrutura em nuvem para verificar a saúde dos containers, validar configurações de load balancer e consultar APIs de monitoramento. A skill fornece o conhecimento procedimental ("verifique estas cinco coisas nesta ordem"), e os servidores MCP fornecem as conexões ("aqui está como acessar a API do load balancer").
Essa arquitetura combinada já está rodando em produção em empresas de serviços financeiros e ciências da vida. As skills codificam procedimentos de conformidade e fluxos de análise. Os servidores MCP conectam a bancos de dados internos, APIs regulatórias e ferramentas de relatório. O agente orquestra tudo com base nas instruções da skill.
Acredito que essa é a arquitetura que vai definir a próxima geração de implantações empresariais de IA. Não agentes monolíticos com tudo embutido, mas agentes enxutos com bibliotecas ricas de skills e conectividade MCP ampla.
O Que a Maioria das Pessoas Está Errando Sobre Essa Mudança
Deixe-me questionar algumas coisas que continuo vendo em discussões sobre agent skills.
"Skills são apenas engenharia de prompt com passos extras." Não. Engenharia de prompt é escrever instruções. Skills são empacotar expertise em uma unidade reutilizável, versionável, compartilhável e componível. Esse empacotamento é o ponto central. A diferença entre uma receita solta rabiscada num guardanapo e um livro de receitas publicado não é o conteúdo — é o formato, a descobribilidade e a confiabilidade. Mesmo princípio aqui.
"Não preciso de skills porque meu agente funciona bem." Seu agente funciona bem para o que ele faz atualmente. Skills são sobre o que vem a seguir. Quando seu chefe pedir para seu agente lidar com um novo fluxo de trabalho, você vai reescrever o system prompt? Vai criar um segundo agente? Vai construir um roteador para despachar entre agentes? Skills permitem que você simplesmente adicione uma pasta. A simplicidade operacional é a funcionalidade.
"Pessoas não-técnicas não conseguem construir skills." Essa está sendo refutada em tempo real. O formato de instruções baseado em markdown significa que qualquer pessoa que consiga escrever procedimentos claros pode criar uma skill. Vi uma coordenadora de recrutamento — zero experiência com código — construir uma skill que padronizou como o Claude filtra currículos para os critérios específicos da empresa. Os scripts de "ferramentas" são opcionais para skills que não precisam de automação. Muitas skills são puro conhecimento procedimental em markdown, e funcionam surpreendentemente bem.
A única crítica com a qual concordo: testes e avaliação para skills ainda são imaturos. Quando você escreve código, tem suítes de teste, linters, verificadores de tipos. Quando escreve uma skill, como verifica se ela funciona corretamente? Como mede se a versão 2 é melhor que a versão 1? A equipe por trás das skills reconheceu essa lacuna e a listou como prioridade para desenvolvimento futuro. Até que essas ferramentas existam, testo minhas skills à moda antiga — experimentando em tarefas reais e iterando com base nos resultados.
O Que Acontece Quando Agentes Constroem Suas Próprias Skills
Aqui é onde meu pensamento fica especulativo — mas ancorado no que já estou vendo.
O Claude Code pode criar skills de forma autônoma. Quando você está trabalhando com o Claude e ele descobre um procedimento útil, ele pode anotar esse procedimento como uma skill para uso futuro. Vi isso acontecer acidentalmente. Eu estava debugando um problema de deploy, guiando o Claude pelo meu processo de troubleshooting passo a passo. Depois que corrigimos, o Claude perguntou se eu queria que ele salvasse o procedimento de troubleshooting como uma skill. Eu disse sim. Agora, toda vez que encontro um problema similar, o Claude já sabe os passos de diagnóstico.
Isso é aprendizado transferível tornado tangível. O agente vivenciou uma situação, extraiu o conhecimento procedimental e o armazenou em um formato que persiste além da sessão atual. Conversas futuras — até versões futuras do Claude — podem acessar esse conhecimento instantaneamente.
A analogia com a história da computação é impressionante e não acho que seja acidental. Modelos são processadores — poder computacional bruto. Runtimes de agentes são sistemas operacionais — gerenciando recursos e processos ao redor do processador. Skills são aplicações — o software que resolve problemas reais e codifica expertise real.
Estamos essencialmente assistindo à camada de aplicação da IA se desenvolver em tempo real. E assim como o desenvolvimento de software se democratizou ao longo de décadas — de linguagem assembly a construtores no-code — a criação de skills já está nessa trajetória. Hoje requer entender estruturas de pastas e sintaxe markdown. Amanhã provavelmente não vai exigir nada mais do que mostrar a um agente como fazer algo e dizer "lembre-se disso."
Suas Próximas Doze Horas
Aqui está o que quero que você faça antes de amanhã. Escolha um fluxo de trabalho que você faz repetidamente — pode ser verificações de deploy, code reviews, formatação de dados, procedimentos de onboarding de clientes, qualquer coisa que você faça mais de duas vezes por mês.
Escreva como uma skill. Crie uma pasta com um arquivo skill.md. Descreva a condição de ativação. Liste os passos. Anote os casos extremos. Você não precisa de scripts de ferramentas para sua primeira skill. Apenas o conhecimento procedimental em markdown.
Instale e experimente.
Garanto que duas coisas vão acontecer. Primeiro, você vai se surpreender com o quão bem o Claude segue o procedimento — melhor do que a maioria dos humanos segue documentação escrita, honestamente. Segundo, você vai imediatamente pensar em mais cinco fluxos de trabalho que quer converter em skills.
Essa segunda reação é a importante. Significa que você parou de pensar em agentes de IA como produtos que você constrói e começou a pensar neles como plataformas que você estende. E essa mudança de mentalidade — de construir agentes para construir skills — é a diferença entre lutar contra o teto de complexidade e atravessá-lo.
O agente que passei três meses construindo no ano passado? Reconstruí como sete skills. Cada uma levou menos de um dia. Juntas, fazem tudo que o agente original fazia, mais três coisas que ele não conseguia. E quando o cliente pedir uma nova capacidade mês que vem, vou adicionar uma oitava skill em vez de começar do zero.
Isso não é melhoria incremental. É uma forma fundamentalmente diferente de construir.
Vamos Trabalhar Juntos
Quer construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tech? Adoraria ajudar.
- Fiverr (builds personalizados e integrações): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (soluções empresariais): ramlit.com
- ColorPark (design e branding): colorpark.io
- xCyberSecurity (serviços de segurança): xcybersecurity.io
