# Competências de agentes de IA: o que são e como criar uma que funciona > As competências de agentes de IA transformam instruções que repete em ficheiros que o agente carrega quando necessário. Veja como funciona o SKILL.md, exemplos reais e como criar uma. Last updated: 2026-09-28T10:00:00 Canonical URL: https://crevio.co/pt/blog/ai-agent-skills *Última atualização: setembro de 2026* **Se já explicou a sua política de reembolsos a um agente de IA mais de duas vezes, já criou uma competência de agente. Só continua a apagá-la.** As competências de agentes de IA são a solução: um ficheiro curto que contém um procedimento e que o agente lê apenas quando uma tarefa o exige. Escreva as regras uma vez e todas as conversas futuras partem delas. Este guia destina-se a proprietários e gestores de empresas que usam um agente de IA para trabalho real e estão cansados de explicar tudo novamente. Aborda o que é realmente uma competência, como os agentes decidem carregá-la, que tarefas justificam uma e inclui um exemplo completo que pode copiar. - **Uma competência é uma pasta com um ficheiro SKILL.md**: um nome, uma descrição curta e as instruções. Os scripts e ficheiros de referência são opcionais - **Os agentes só leem a descrição inicialmente** (cerca de 100 tokens por competência). O restante é carregado quando uma tarefa corresponde à competência, pelo que uma biblioteca grande continua a ser económica - **É um padrão aberto.** A mesma competência funciona no Claude, ChatGPT e Codex, Gemini CLI, Cursor, GitHub Copilot e dezenas de outros agentes - **A descrição é a parte mais importante.** Uma descrição vaga faz com que a competência nunca seja ativada ou seja ativada para a tarefa errada - **As competências de terceiros são código que está a instalar.** Uma auditoria de fevereiro de 2026 encontrou problemas críticos de segurança em 13,4% das competências públicas ## O que são competências de agentes de IA? **As competências de agentes de IA são pacotes reutilizáveis de instruções que ensinam um agente a executar uma tarefa específica à sua maneira.** Cada competência é uma pasta que contém um ficheiro `SKILL.md`. Esse ficheiro começa com um cabeçalho curto (um `name` e um `description`), seguido de instruções em linguagem simples: os passos, as regras, o formato de saída e os casos-limite. A ideia surgiu na Anthropic, que [apresentou as Agent Skills em outubro de 2025](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) e as descreveu como «pastas organizadas de instruções, scripts e recursos que os agentes podem descobrir e carregar dinamicamente». Em dezembro de 2025, publicou o formato como um padrão aberto em [agentskills.io](https://agentskills.io/home), e desde então a maioria dos principais agentes adotou-o. ![Publicação de engenharia da Anthropic que apresenta as Agent Skills, publicada a 16 de outubro de 2025](https://crevio.co/vite/assets/anthropic-agent-skills-announcement-fr3rjecj.png) O termo também é usado de forma abrangente para «as coisas que os agentes de IA conseguem fazer» ou para as competências humanas necessárias para gerir agentes. Esses são temas legítimos, mas quando as pessoas que criam ou compram agentes dizem «competências» em 2026, quase sempre querem dizer isto: um procedimento empacotado que o agente pode utilizar e deixar de utilizar conforme necessário. ### O que contém uma pasta de competências A [especificação Agent Skills](https://agentskills.io/specification) mantém a estrutura deliberadamente simples: | Parte | Obrigatória? | O que contém | |---|---|---| | `SKILL.md` | Sim | Cabeçalho com `name` e `description`, seguido das instruções | | `scripts/` | Não | Código que o agente pode executar, como um gerador de relatórios ou um validador | | `references/` | Não | Documentos mais extensos: a sua política completa, uma tabela de preços ou um guia de estilo | | `assets/` | Não | Modelos, ficheiros de exemplo e tabelas de consulta | O cabeçalho tem limites rigorosos. O `name` pode ter até 64 caracteres, em minúsculas, números e hífenes. O `description` pode ter até 1 024 caracteres e, segundo a especificação, «deve descrever o que a competência faz e quando deve ser utilizada». ![Página da especificação Agent Skills que mostra o ficheiro SKILL.md obrigatório e as pastas opcionais de scripts, referências e recursos](https://crevio.co/vite/assets/agentskills-specification-idwfflfk.png) ## Como os agentes carregam competências A parte mais inteligente do formato é o facto de um agente não ler todas as competências de uma só vez. Em vez disso, carrega-as em três níveis, algo a que a especificação chama **divulgação progressiva**. ![Diagrama dos três níveis carregados por um agente: nome e descrição sempre; instruções do SKILL.md quando uma tarefa corresponde à competência; e referências ou scripts apenas quando um passo precisa deles](https://crevio.co/vite/assets/how-agents-load-skills-g1wbt1jh.svg) 1. **Descoberta.** No início de cada sessão, o agente lê apenas o nome e a descrição de cada competência instalada, cerca de 100 tokens por competência 2. **Ativação.** Quando o seu pedido corresponde a uma descrição, o agente lê o `SKILL.md` completo dessa competência. A especificação recomenda mantê-lo abaixo de 5 000 tokens e 500 linhas 3. **Execução.** O agente segue as instruções e abre um ficheiro de referência ou executa um script apenas quando um passo remete para esse recurso É por isso que uma empresa pode manter dezenas de competências instaladas sem tornar o agente mais lento nem pagar pelo contexto que nunca utiliza. É também por isso que a descrição tem tanto peso: é a única parte que o agente vê antes de decidir. O [guia de criação da Anthropic](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) diz que o agente pode estar a escolher entre «mais de 100 Skills disponíveis» com base apenas nesse campo. ## Competências vs. prompts, ferramentas e memória As competências sobrepõem-se a vários recursos que talvez já utilize. A diferença está no que cada um contém e em que momento aparece. | | O que contém | Quando o agente o vê | Adequado para | |---|---|---|---| | **Prompt** | Um pedido | Apenas nesta conversa | Tarefas pontuais | | **Instruções personalizadas** | Preferências permanentes | Sempre, em todas as conversas | Tom, nome e fuso horário | | **Memória** | Factos que o agente reteve | Quando os recorda | «O nosso mês mais movimentado é novembro» | | **Ferramenta ou integração** | Acesso a um sistema | Quando precisa de agir | Ler encomendas e enviar e-mails | | **Competência** | Um procedimento | Apenas quando a tarefa corresponde | «Como tratamos os reembolsos» | A confusão mais comum é entre competências e ferramentas. **Uma ferramenta dá ao agente uma chave; uma competência diz-lhe o que fazer depois de entrar.** Uma competência que diga «verifique a encomenda na nossa loja» é inútil se o agente não tiver acesso à sua loja, e o acesso à sua loja é arriscado sem uma competência que defina o que o agente pode e não pode fazer. Normalmente, precisa dos dois. As competências e a memória também distinguem um agente que começa sempre do zero de um que melhora com a utilização. Foi essa a distinção que traçámos em [Funcionário de IA vs. agente de IA](/pt/blog/ai-employee-vs-ai-agent). ## Onde funcionam atualmente as competências de agentes de IA Como o formato é um padrão aberto, uma competência que crie não fica limitada a um único produto. A [lista de clientes do agentskills.io](https://agentskills.io/home) inclui Claude e [Claude Code](/pt/blog/claude-code), ChatGPT e Codex, Gemini CLI, Cursor, GitHub Copilot, VS Code, OpenCode, Goose, Databricks, Snowflake e mais de 30 outros. Surgiram também diretórios públicos. O [skills.sh](https://skills.sh/) apresenta competências da comunidade que pode instalar com um comando, desde competências de escrita e pesquisa até competências criadas para ferramentas específicas. ![skills.sh, um diretório público de competências de agentes da comunidade com um ranking de instalações](https://crevio.co/vite/assets/skills-sh-directory-f00n0in6.png) Grande parte dessa biblioteca é criada por programadores para agentes de programação. As competências importantes para gerir uma empresa raramente aparecem num ranking, porque codificam coisas que só você sabe: as suas políticas, a sua voz e os seus números. ## Exemplos de competências de agentes de IA para uma pequena empresa Eis o aspeto de uma biblioteca inicial de competências para uma empresa que vende produtos ou serviços digitais: | Competência | O que codifica | É ativada quando | |---|---|---| | `handling-refund-requests` | Política de reembolsos, regras de aprovação e tom das respostas | Um cliente pede o reembolso do dinheiro | | `writing-weekly-report` | Que números utilizar, qual a ordem e o que conta como «relevante» | Pergunta como correu a semana | | `writing-in-brand-voice` | Palavras que utiliza, palavras que nunca utiliza e exemplos de e-mails | É preciso criar um texto dirigido a clientes | | `launching-a-product` | A sua checklist de lançamento, sequência de e-mails e regras de preços | Diz «vamos lançar X» | | `qualifying-leads` | Quem se enquadra, o que perguntar e quando marcar uma chamada | Surge um novo potencial cliente | | `pricing-a-custom-quote` | Tabela de preços, valores mínimos e descontos permitidos | Um potencial cliente pergunta «quanto custa?» | Repare no que falta: «escrever uma publicação para o blogue» ou «resumir este PDF». O modelo já faz isso bem. Uma competência justifica o seu lugar ao guardar contexto que o agente não consegue adivinhar. ## O que merece uma competência (e o que não merece) Antes de escrever seja o que for, avalie a tarefa com duas perguntas: com que frequência se repete e o agente comete erros sem o seu contexto? ![Matriz 2x2: crie uma competência apenas para tarefas que se repetem frequentemente e que o agente executa mal sem o seu contexto](https://crevio.co/vite/assets/what-deserves-a-skill-bje0433g.svg) A PostHog, cujas equipas publicaram 226 competências numa loja interna, chega à mesma conclusão no [seu artigo sobre criação de competências](https://posthog.com/newsletter/writing-agent-skills): crie competências para trabalho que se repete, que os agentes têm dificuldade em executar por defeito ou que exige contexto pouco óbvio. Tudo o resto é sobrecarga que dificulta a escolha do agente. ## Como criar uma competência para um agente de IA Não precisa de programar. Uma competência útil é um documento de procedimento bem escrito, com um cabeçalho claro. ### Passo 1: execute primeiro a tarefa com o agente O próprio conselho da Anthropic é começar por uma conversa real, não por um ficheiro vazio. Execute a tarefa uma vez, corrija o agente à medida que avança e repare no que teve de explicar. Essas correções são a competência. ### Passo 2: escreva primeiro a descrição A descrição determina se a competência chega a ser carregada. Escreva na terceira pessoa, diga o que a competência faz e enumere as expressões que um pedido pode realmente conter: - **Fraca:** «Ajuda com clientes.» - **Forte:** «Trata pedidos de reembolso de produtos digitais. Utilize quando um cliente pedir um reembolso, disser que uma compra não funcionou ou mencionar um chargeback.» ### Passo 3: escreva o corpo como objetivos e regras, não como um guião Indique o objetivo, as regras obrigatórias, os passos, o formato de saída e os casos-limite. Seja preciso quanto às restrições e flexível quanto à redação. Vale a pena citar o aviso da PostHog: «A especificação excessiva transforma uma competência num fluxo de trabalho e elimina a inteligência pela qual está a pagar.» ### Passo 4: transfira o material extenso para referências Se a sua política completa tiver três páginas, coloque-a em `references/refund-policy.md` e diga ao agente exatamente quando deve abri-la. Mantenha as referências a um nível de profundidade: os ficheiros que remetem para outros ficheiros tendem a ser lidos apenas pela metade. ### Passo 5: teste-a com três pedidos reais Faça três pedidos realistas, incluindo um que *não* deva ativar a competência. Se for ativada para a tarefa errada ou não detetar uma situação óbvia, o problema está quase sempre na descrição. ### Um exemplo completo que pode copiar ``` --- name: handling-refund-requests description: Handles refund requests for digital products (courses, templates, downloads). Use when a customer asks for a refund, says a purchase did not work, disputes a charge, or mentions a chargeback. --- # Handling refund requests ## Goal Resolve the request in one reply and keep the customer where possible. Never refund outside policy without the owner's approval. ## Policy - Courses: full refund within 14 days if under 30% of lessons completed - Templates and downloads: no refund after download; offer a fix or an exchange - Duplicate purchases: always refund the duplicate ## Steps 1. Look up the order: product type, purchase date, usage 2. Compare against the policy above 3. Within policy: draft the refund and the reply, then ask for approval 4. Outside policy: draft a reply offering the fix or exchange. Do not promise a refund 5. Chargeback, lawyer, or angry repeat contact: stop and hand it to the owner ## Reply style Short and warm. Use their first name. Apologize once, not three times. Sign off as "The Studio Team". ## Edge cases - Bought the wrong course: offer a free swap before a refund - Payment failed but they were charged: treat as a duplicate ``` Tem menos de 250 palavras e substitui uma conversa que, de outra forma, teria todas as semanas. ## O que ninguém lhe diz sobre as competências de agentes O formato é simples. As surpresas surgem quando vive com uma biblioteca de competências durante alguns meses. **As competências entram em conflito à medida que a biblioteca cresce.** O artigo da PostHog cita uma descoberta da Databricks: «os agentes escolhem cada vez mais a competência errada à medida que são adicionadas novas competências». Duas competências com descrições sobrepostas («e-mails para clientes» e «respostas de suporte») vão alternar de forma imprevisível. Una-as ou faça com que cada descrição indique as situações que a outra não abrange. **As competências ficam desatualizadas silenciosamente.** O prazo de reembolso muda, os preços mudam, uma ferramenta muda de nome e a competência continua a aplicar com confiança as regras antigas. Coloque tudo o que é volátil num único ficheiro de referência que mantenha atualizado, tal como faria numa [base de conhecimento de um agente de IA](/pt/blog/ai-agent-knowledge-base), e reveja as competências sempre que a política subjacente mudar. **As competências de terceiros são software, não texto.** A Snyk analisou 3 984 competências públicas em fevereiro de 2026 e [encontrou falhas de segurança em 36,82% e problemas críticos em 13,4%](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/), incluindo 76 payloads maliciosos confirmados, criados para roubar credenciais, instalar backdoors ou exfiltrar dados. A recomendação da Anthropic é clara: instale competências apenas de fontes em que confia e leia primeiro todas as outras. Abordámos o mesmo risco na nossa análise de [alternativas ao OpenClaw](/pt/blog/openclaw-alternatives), onde as competências da comunidade foram uma das principais preocupações. **Uma competência não concede permissões.** Instruções que digam «emita o reembolso» não fazem nada sem acesso ao seu sistema de pagamentos, e o acesso sem limites é o perigo maior. Mantenha o dinheiro, os envios e as eliminações protegidos por uma etapa de aprovação, independentemente do que a competência diga. É a mesma regra que recomendamos para [entregar trabalho a agentes de IA numa pequena empresa](/pt/blog/ai-agents-for-small-business): tudo o que sai da empresa deve ser preparado, não enviado. ## Como a Crevio utiliza competências A [Crevio](https://crevio.co/) é uma plataforma de criação de empresas com IA: descreve o que quer vender e o seu agente cria a loja, trata dos pagamentos, escreve o marketing e continua a trabalhar consigo na empresa. É através das competências que esse agente transporta conhecimento entre conversas. ![Página inicial da Crevio: IA que cria a sua loja, processa os seus pagamentos, escreve o seu marketing e aumenta as suas vendas](https://crevio.co/vite/assets/crevio-homepage-nvib9pqi.png) Eis como isso funciona na prática: - **Inclui competências integradas.** O agente inclui competências para cold email, lead magnets, preços, [auditorias de SEO](/pt/blog/ai-agents-for-seo), criativos para anúncios, publicações nas redes sociais e trabalho com PDFs, folhas de cálculo, documentos e apresentações - **Pode instalar e carregar as suas próprias competências.** A página Skills nas definições inclui um marketplace de competências da comunidade e permite carregar uma competência como `.zip`, uma pasta ou um único `SKILL.md`. As competências carregadas permanecem privadas na sua conta - **Cria competências com base na experiência.** Depois de uma tarefa longa e complexa, a Crevio analisa o que aconteceu e guarda a parte duradoura como uma competência. Estas competências aparecem em «Aprendido pela sua IA», onde pode lê-las ou removê-las - **Pode ensinar através de demonstração.** A opção «Ensinar uma tarefa» grava aquilo que faz no computador do agente e a Crevio transforma a gravação numa competência reutilizável A ressalva honesta: uma competência criada pelo próprio agente só é tão boa quanto a conversa com base na qual aprendeu. Leia o que foi guardado, sobretudo tudo o que envolva dinheiro ou clientes. A Crevio tem um plano gratuito, pelo que pode experimentar a biblioteca de competências sem cartão. ## Perguntas frequentes ### As competências de agentes são iguais ao MCP? Não. O MCP (Model Context Protocol) é uma das várias formas de [ligar um agente às aplicações da sua empresa](/pt/blog/connect-ai-agents-to-business-apps), como o CRM ou a caixa de entrada. Uma competência é um procedimento escrito que diz ao agente como utilizar aquilo a que tem acesso. Funcionam em conjunto: o MCP fornece o acesso e a competência fornece o critério sobre quando e como o utilizar. ### Preciso de saber programar para criar uma competência de agente de IA? Não. A maioria das competências empresariais úteis é escrita em Markdown simples: um cabeçalho, um objetivo, regras e passos. Os scripts são opcionais e só vale a pena adicioná-los para passos que têm de ser executados exatamente da mesma forma todas as vezes, como gerar um relatório formatado ou verificar um cálculo. ### As competências do Claude são iguais às competências de agentes? Sim, na prática. A Anthropic criou o formato para o Claude e publicou-o posteriormente como o padrão aberto Agent Skills. Uma competência escrita para o Claude funciona geralmente em qualquer agente que suporte o padrão, desde que não dependa de uma ferramenta exclusiva de um produto. ### Quantas competências deve ter um agente? Quantas forem as suas tarefas distintas e repetidas, e não mais. O custo de carregamento é reduzido, mas descrições sobrepostas fazem com que o agente escolha a competência errada. Se duas competências puderem responder plausivelmente ao mesmo pedido, una-as. ## Em resumo As competências de agentes de IA são a diferença entre um agente que gere e um agente que treinou. Comece pelo procedimento que mais se cansa de explicar, escreva a descrição como se tudo dependesse dela e mantenha o resto curto. A melhor biblioteca de competências não é a maior. É aquela em que cada ficheiro corresponde a algo que já estava cansado de dizer. ## Artigos relacionados - [Funcionário de IA vs. agente de IA: a diferença que realmente importa](/pt/blog/ai-employee-vs-ai-agent) - [Agentes de IA para pequenas empresas: que tarefas delegar primeiro](/pt/blog/ai-agents-for-small-business) - [Melhores agentes de IA para o Slack em 2026 (11 ferramentas comparadas)](/pt/blog/best-ai-agents-for-slack)