O que são AI Skills & Tools

🔧 O que é um Skill?

No contexto de agentes de IA, um skill (também chamado de tool or function) é uma capacidade empacotada e reutilizável que um LLM pode invocar para interagir com o mundo fora da sua janela de contexto. Skills preenchem a lacuna entre o entendimento de linguagem e a ação no mundo real.

Todo skill tem quatro componentes:

• Name — um identificador único que o modelo usa para referenciar o skill (por exemplo, web_search)
• Description — texto em linguagem natural explicando o que o skill faz e quando usá-lo; o LLM lê isso para decidir quando chamar o skill
• Esquema de entrada — uma definição estruturada dos argumentos (JSON Schema); o modelo preenche esses campos com base na tarefa
• Implementation — o código real que é executado: uma chamada API, consulta ao banco de dados, comando shell ou qualquer outra operação

Exemplo: A get_weather skill tem a descrição "Busca o clima atual para uma cidade", aceita { "city": "string" } como entrada, e chama uma API de clima. O LLM nunca vê a chave da API ou a chamada HTTP — ele apenas recebe o resultado de volta como texto.

⚙️ Como o Chamamento de Ferramentas Funciona

Quando um agente tem acesso a skills, o LLM não os chama diretamente — ele requests uma chamada gerando uma saída estruturada. O runtime (seu código de aplicação) executa a chamada real e retorna o resultado. Aqui está o ciclo completo:

1. Registro da ferramenta — Seu código envia ao modelo uma lista de skills disponíveis com suas descrições e schemas
2. Raciocínio do modelo — O LLM lê a tarefa e as ferramentas disponíveis, decide qual ferramenta chamar e com quais argumentos
3. Requisição de chamada de ferramenta — O modelo produz uma mensagem estruturada de "tool call" (por exemplo, { "tool": "web_search", "args": { "query": "current Gemini models" } })
4. Execution — Seu código em runtime chama a função, API ou serviço real
5. Injeção de resultado — O resultado é adicionado de volta ao contexto da conversa
6. Raciocínio contínuo — O modelo lê o resultado e ou chama outra ferramenta, faz uma pergunta de seguimento ou gera a resposta final

Este loop pode repetir muitas vezes em uma única interação. Uma tarefa agenteica complexa pode chamar 10–20 ferramentas em sequência antes de produzir uma resposta final.

📊 Skills vs Plugins vs MCP Servers

A terminologia evoluiu rapidamente. Veja como os conceitos se relacionam historicamente:

Distinção chave: O uso tradicional de ferramentas é definido inline no seu código de aplicação. MCP servers são processos independentes que expõem ferramentas através de um protocolo padronizado — tornando-os reutilizáveis entre diferentes clientes de IA (Claude Desktop, Cursor, VS Code, agentes customizados). Leia mais: O que é MCP.

🗂️ Categorias de Ferramentas & Níveis de Risco

Nem todas as ferramentas apresentam o mesmo risco. Agrupar por nível de risco ajuda a definir o espaço de ação e onde adicionar checkpoints humanos no loop:

🏗️ Anatomia de um Bom Skill

A decisão de design mais importante para um skill é sua description. O LLM lê as descrições para decidir qual ferramenta chamar — uma descrição mal escrita leva à seleção errada da ferramenta, chamadas perdidas ou argumentos ambíguos.

O que torna uma descrição eficaz

• Seja explícito sobre quando usá-lo — "Use esta ferramenta quando o usuário pergunta sobre dados em tempo real ou eventos atuais" é melhor que "Busca na web"
• Declare o que NÃO faz — "Não retorna dados históricos com mais de 30 dias"
• Descreva o formato de saída — "Retorna um array JSON de resultados de busca com campos title, url e snippet"
• Mantenha abaixo de 200 palavras — descrições com mais de ~200 tokens podem sobrecarregar a atenção do modelo quando muitas ferramentas estão registradas

Princípios de design de schema

• Obrigatório vs opcional — Marque campos como obrigatórios somente se realmente necessário; campos opcionais com defaults reduzem erros do modelo
• Use enums para valores restritos — "format": {"enum": ["json", "markdown", "text"]} previne valores alucinatórios
• Prefira ferramentas idempotentes — Ferramentas que podem ser repetidas com segurança (leituras, consultas) são mais seguras do que ações únicas (envios, exclusões)
• Retorne dados estruturados — Respostas JSON são mais fáceis para o modelo raciocinar do que blobs de texto não estruturado

💡 Exemplos do Mundo Real

✅ Boas Práticas

Permissões mínimas

Conceda a cada agente apenas as ferramentas que ele precisa para sua tarefa específica. Um agente que responde FAQ não precisa de write_file or send_email. Quanto menor o espaço de ações, menor o raio de dano se o agente for manipulado. Veja: Agência Excessiva.

Auditar todas as chamadas de ferramenta

Registre toda chamada de ferramenta com seus argumentos e resultado. Isso possibilita depuração, atribuição de custo e detecção de comportamento anômalo (por exemplo, um agente lendo ~/.ssh/ quando deveria somente acessar o diretório do projeto). Plataformas AgentOps como LangSmith tornam isso fácil.

Humano-no-loop para ações irreversíveis

Qualquer ação que seja difícil ou impossível de desfazer — enviar mensagens, excluir dados, fazer compras — deve exigir confirmação humana explícita antes da execução. Construa checkpoints HITL no tempo de execução do agente, não apenas no prompt. Prompts podem ser sobrescritos; código não pode ser.

Cuidado com envenenamento de ferramenta

Se você permite que agentes instalem ou descubram MCP servers dinamicamente, um servidor malicioso pode registrar uma ferramenta com uma descrição que contém instruções ocultas. Sempre revise as descrições de ferramentas antes de adicioná-las ao registro do agente. Veja: Envenenamento de Ferramenta.

Escreva retornos de erro claros

Quando uma ferramenta falha, retorne um erro estruturado com contexto suficiente para o modelo se recuperar ou escalar — não uma stack trace de exceção bruta. Exemplo: { "error": "rate_limited", "retry_after": 5 }. Um erro bem descrito permite que o agente tente novamente, use uma ferramenta alternativa ou informe o usuário com elegância.