Skills de agentes

Agent Skills são pacotes reutilizáveis de instruções que dão capacidades especializadas aos seus agentes de IA. Baseados no formato aberto Agent Skills, skills permitem capturar expertise de domínio, workflows e boas práticas que os agentes podem carregar sob demanda.

Como as skills funcionam

Skills usam divulgação progressiva para manter o contexto do agente enxuto:

1. Descoberta — Só nomes e descrições das skills entram no system prompt do agente (~50–100 tokens cada)
2. Ativação — Quando o agente decide que uma skill é relevante, chama a ferramenta load_skill para carregar as instruções completas no contexto
3. Execução — O agente segue as instruções carregadas para concluir a tarefa

Criando skills

Skills ficam na página Integrations: clique em Integrations na barra lateral do workspace e mude para a aba Skills. Ela lista todas as skills do workspace, pesquisáveis por nome.

Clique em + Add to Zoen para abrir o diálogo Add Skill. A aba Create pede três campos:

Importando skills

A aba Import traz uma skill existente no formato aberto SKILL.md, de três formas:

• Upload a file — um arquivo .md com frontmatter YAML, ou um .zip contendo um SKILL.md.
• Import from GitHub — cole uma URL do GitHub para um SKILL.md e clique em Fetch.
• Paste content — cole o SKILL.md diretamente. O frontmatter carrega o name e a description; o corpo markdown é o conteúdo.

Páginas de integração sugerem skills curadas para o serviço — abra uma (HubSpot, por exemplo) e adicione uma skill sugerida com um clique.

Escrevendo um bom conteúdo de skill

O conteúdo da skill segue as mesmas convenções dos arquivos SKILL.md:

# SQL Expert

## When to use this skill
Use when the user asks you to write, optimize, or debug SQL queries.

## Instructions
1. Always ask which database engine (PostgreSQL, MySQL, SQLite)
2. Use CTEs over subqueries for readability
3. Add index recommendations when relevant
4. Explain query plans for optimization requests

## Common Patterns
...

Estrutura recomendada:

• When to use — Gatilhos e cenários específicos
• Instructions — Orientação passo a passo com listas numeradas
• Examples — Amostras de entrada/saída mostrando o comportamento esperado
• Common Patterns — Abordagens reutilizáveis para tarefas frequentes
• Edge Cases — Armadilhas e considerações especiais

Mantenha as skills focadas e com menos de 500 linhas. Se uma skill crescer demais, divida-a em várias skills especializadas.

Adicionando skills a um agente

Abra qualquer bloco Agent e encontre o dropdown Skills abaixo da seção de tools. Selecione as skills que o agente deve ter acesso.

As skills selecionadas aparecem como cards que você pode clicar para editar ou remover.

O que acontece em runtime

Quando o workflow roda:

1. O system prompt do agente inclui uma seção <available_skills> listando o nome e a descrição de cada skill
2. Uma ferramenta load_skill é adicionada automaticamente às tools disponíveis do agente
3. Quando o agente determina que uma skill é relevante para a tarefa atual, chama load_skill com o nome da skill
4. O conteúdo completo da skill é retornado como resposta da tool, dando ao agente instruções detalhadas

Isso funciona em todos os provedores de LLM suportados — a ferramenta load_skill usa tool-calling padrão, então nenhuma configuração específica do provedor é necessária.

Casos de uso comuns

Skills são mais valiosas quando os agentes precisam de conhecimento especializado ou workflows em vários passos:

Expertise de domínio

• api-integration-expert — Boas práticas para chamar APIs específicas (autenticação, rate limiting, tratamento de erros)
• data-transformation — Padrões de ETL, limpeza de dados e regras de validação
• code-reviewer — Diretrizes de code review específicas dos padrões do seu time

Templates de workflow

• bug-investigation — Metodologia de debugging passo a passo (reproduzir → isolar → testar → corrigir)
• feature-implementation — Workflow de desenvolvimento dos requisitos ao deploy
• document-generator — Templates e regras de formatação para documentação técnica

Conhecimento específico da empresa

• our-architecture — Diagramas de arquitetura, dependências de serviços e processos de deploy
• style-guide — Diretrizes de marca, tom de escrita, padrões de UI/UX
• customer-onboarding — Procedimentos padrão e perguntas comuns de clientes

Quando usar skills vs. instruções do agente:

• Use skills para conhecimento que se aplica a vários workflows ou muda com frequência
• Use instruções do agente para contexto específico da tarefa, único de um único agente

Boas práticas

Escrevendo descrições eficazes

• Seja específico e rico em palavras-chave — Em vez de "Helps with SQL", escreva "Write optimized SQL queries for PostgreSQL, MySQL, and SQLite, including index recommendations and query plan analysis"
• Inclua gatilhos de ativação — Mencione palavras ou frases específicas que devem acionar a skill (ex.: "Use when the user mentions PDFs, forms, or document extraction")
• Mantenha abaixo de 200 palavras — Agentes varrem descrições rápido; faça cada palavra contar

Escopo e organização da skill

• Uma skill por domínio — Uma skill focada sql-expert funciona melhor que uma ampla database-everything
• Limite a 5–10 skills por agente — Mais skills = mais overhead de decisão; comece pequeno e adicione conforme precisar
• Divida skills grandes — Se uma skill passar de 500 linhas, quebre em sub-skills focadas

Estrutura do conteúdo

• Use formatação markdown — Cabeçalhos, listas e blocos de código ajudam os agentes a parsear e seguir instruções
• Forneça exemplos — Mostre pares de entrada/saída para os agentes entenderem o comportamento esperado
• Seja explícito sobre edge cases — Não assuma que os agentes vão inferir tratamentos especiais

Teste e iteração

• Teste a ativação — Rode o workflow e verifique se o agente carrega a skill quando esperado
• Cheque falsos positivos — Garanta que skills não ativam quando não deveriam
• Refine as descrições — Se uma skill não carrega quando precisa, adicione mais palavras-chave à descrição

Saiba mais

• Especificação Agent Skills — O formato aberto para skills portáteis de agentes
• Exemplos de skills — Explore exemplos da comunidade
• Boas práticas — Escrevendo skills eficazes