Skills de agente

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

Como as skills funcionam

As skills usam revelação progressiva para manter o contexto do agente enxuto:

1. Descoberta — apenas os nomes e as descrições das skills entram no prompt de sistema do agente (cerca de 50 a 100 tokens cada)
2. Ativação — quando o agente decide que uma skill é relevante, ele 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

As skills ficam na página Integrations: clique em Integrations na barra lateral do workspace e vá para a aba Skills. Ela lista todas as skills do workspace, com busca por nome. Clique em uma skill para abrir sua página de detalhes, onde você a edita, compartilha e exclui.

Clique em + Add to Studio para abrir a página de criação de skill, que tem três campos:

Importando skills

Traga uma skill existente no formato aberto SKILL.md de duas maneiras:

• Import — a ação Import na página de criação aceita um arquivo .md com frontmatter YAML ou um .zip contendo um SKILL.md.
• Colar o conteúdo — cole o SKILL.md direto em Content. O frontmatter traz o name e a description; o corpo em markdown é o conteúdo.

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

Escrevendo um bom conteúdo de skill

O conteúdo de uma 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 — exemplos de entrada e saída mostrando o comportamento esperado
• Common Patterns — abordagens reutilizáveis para tarefas frequentes
• Edge Cases — pegadinhas e casos especiais

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

Editores de skill

Todo mundo no workspace vê e usa todas as skills — inclusive quem entra depois. Ninguém precisa ser adicionado a uma skill para usá-la.

Cada skill tem uma lista explícita de editors. Os editores podem editar a skill, excluí-la e gerenciar a lista de editores. Os admins do workspace também podem fazer isso a qualquer momento — eles são editores de todas as skills automaticamente e não podem ser removidos da lista. Quem cria uma skill se torna editor dela.

Abra uma skill na aba Skills para gerenciá-la. A página de detalhes tem os campos editáveis, uma ação Share para adicionar editores entre os membros do workspace e a lista Skill Editors no rodapé.

Usando skills no Chat

As skills também funcionam no Chat. Digite / na caixa de mensagem para abrir o menu de skills e escolha uma — ou continue digitando para filtrar por nome. A skill aparece na sua mensagem como uma tag, por exemplo /format-markdown.

Marcar uma skill carrega as instruções completas dela na conversa, então o Studio as segue naquela solicitação — sem esperar que o Studio decida por conta própria que a skill é relevante.

Adicionando skills a um agente

Abra qualquer block Agent e localize o dropdown Skills, abaixo da seção de ferramentas. Selecione as skills às quais você quer dar acesso ao agente.

As skills selecionadas aparecem como cards, nos quais você pode clicar para editar ou remover.

O que acontece na execução

Quando o workflow executa:

1. O prompt de sistema 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 ferramentas disponíveis do agente
3. Quando o agente concluir que uma skill é relevante para a tarefa atual, ele chama load_skill com o nome da skill
4. O conteúdo completo da skill volta como resposta da ferramenta, 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 não é preciso nenhuma configuração específica por provedor.

Casos de uso comuns

As skills são mais valiosas quando os agentes precisam de conhecimento especializado ou de procedimentos de vários passos:

Expertise de domínio

• api-integration-expert — boas práticas para chamar APIs específicas (autenticação, limites de taxa, tratamento de erros)
• data-transformation — padrões de ETL, limpeza de dados e regras de validação
• code-reviewer — diretrizes de revisão de código específicas dos padrões do seu time

Modelos de procedimento

• bug-investigation — metodologia de depuração passo a passo (reproduzir → isolar → testar → corrigir)
• feature-implementation — fluxo de desenvolvimento, dos requisitos ao deploy
• document-generator — modelos e regras de formatação para documentação técnica

Conhecimento específico da empresa

• our-architecture — diagramas de arquitetura do sistema, dependências entre 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 dúvidas frequentes de clientes

Quando usar skills e quando usar instruções do agente:

• Use skills para conhecimento que vale para vários workflows ou que muda com frequência
• Use instruções do agente para contexto de tarefa que é exclusivo de um único agente

Boas práticas

Escrevendo descrições eficazes

• Seja específico e rico em palavras-chave — em vez de "Ajuda com SQL", escreva "Escreve queries SQL otimizadas para PostgreSQL, MySQL e SQLite, incluindo recomendações de índices e análise de planos de execução"
• Inclua gatilhos de ativação — cite palavras ou expressões específicas que devem acionar a skill (por exemplo, "Use quando a pessoa mencionar PDFs, formulários ou extração de documentos")
• Fique abaixo de 200 palavras — os agentes leem descrições rapidamente; faça cada palavra contar

Escopo e organização das skills

• Uma skill por domínio — uma skill focada como sql-expert funciona melhor do que uma skill ampla como database-everything
• Limite-se a 5 a 10 skills por agente — mais skills significam mais custo de decisão; comece pequeno e adicione conforme a necessidade
• Divida skills grandes — se uma skill passar de 500 linhas, quebre-a em sub-skills focadas

Estrutura do conteúdo

• Use formatação markdown — títulos, listas e blocos de código ajudam os agentes a interpretar e seguir as instruções
• Dê exemplos — mostre pares de entrada e saída para que os agentes entendam o comportamento esperado
• Seja explícito sobre casos extremos — não presuma que os agentes vão inferir tratamentos especiais

Testes e iteração

• Teste a ativação — execute seu workflow e confirme que o agente carrega a skill quando esperado
• Verifique falsos positivos — garanta que as skills não estão ativando quando não deveriam
• Refine as descrições — se uma skill não é carregada quando deveria, adicione mais palavras-chave à descrição

Saiba mais

• Especificação Agent Skills — o formato aberto para skills de agente portáveis
• Exemplos de skills — veja exemplos de skills da comunidade
• Boas práticas — como escrever skills eficazes