Como organizar as habilidades do Hermes Agent para ele não escolher a ferramenta errada

Fala aí, beleza? Tem um jeito bem específico de um agente falhar que ninguém avisa no começo: ele não trava, não dá erro, ele só escolhe a skill errada com toda a confiança do mundo

E quase sempre a causa não é falta de habilidade, é habilidade DEMAIS

O Hermes Agent é um agente de IA open source mantido pela Nous Research, escrito em Python e sob licença MIT, no repositório NousResearch/hermes-agent (que hoje está em 222,6 mil estrelas e 42,7 mil forks, então não é projetinho de fim de semana)

O detalhe é que ele já nasce completão: são 79 skills embutidas distribuídas em 14 categorias, mais um catálogo opcional de 114 skills que vem no repositório desligado por padrão

Aí você instala mais três da comunidade, cria duas suas, e do nada o agente tem uma prateleira enorme pra escolher toda vez que você pede qualquer coisa

Se você ainda tá mapeando o terreno, tem um post aqui sobre casos de uso do Hermes Agent que ajuda a decidir o que faz sentido manter ligado

Bora organizar essa bagunça?

O que você precisa saber antes de mexer nas skills

Antes de sair movendo pasta, vale entender onde essa coisa toda vive

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Onde as skills ficam no disco:

As habilidades do Hermes Agent ficam numa pasta fixa: ~/.hermes/skills/

As skills embutidas são copiadas pra lá na instalação, ou seja, não é mágica escondida em algum lugar do pacote, tá tudo em arquivo que você consegue abrir e ler

Também dá pra usar uma pasta skills/ na raiz do projeto, quando a habilidade só faz sentido naquele repositório específico

O que é uma skill, na prática:

Uma skill é uma pasta

Dentro dela, o único arquivo obrigatório é o SKILL.md

Subpastas como scripts/, references/ e templates/ são opcionais, entram só quando a skill precisa

Se você conhece a ideia de um README que o time inteiro segue, é bem por aí: o SKILL.md é o documento que ensina o agente a fazer aquilo

~/.hermes/skills/
└── minha-skill/
    ├── SKILL.md        (obrigatório)
    ├── scripts/        (opcional)
    ├── references/     (opcional)
    └── templates/      (opcional)

Como o Hermes acha a skill certa?

Aqui tem uma coisa que confunde muita gente, então vou separar antes de seguir: existem DOIS caminhos pra uma skill entrar em cena

O caminho manual é você chamar pelo nome: toda skill instalada vira automaticamente um slash command /nome-da-skill dentro do Hermes

O caminho automático é o agente decidir sozinho: ele faz auto-descoberta na inicialização e ativa a skill com base no campo description do frontmatter YAML

Os dois convivem, e um não substitui o outro: no manual quem escolhe é você, no automático quem escolhe é o modelo lendo a descrição

Se liga nisso, porque é o ponto onde quase todo mundo se ferra: no caminho automático, a decisão de usar ou não usar uma habilidade sai daquela linha de descrição, não do corpo caprichado que você escreveu embaixo

Description vaga = agente chutando

E é justamente desse caminho automático que este post inteiro fala, porque é nele que o agente erra sem você pedir nada errado

Divulgação progressiva em três níveis:

O formato foi desenhado pra economizar token, e funciona em camadas:

• Nível 0: o índice de skills
• Nível 1: o SKILL.md, carregado quando a skill é acionada
• Nível 2: o docs.md, puxado só quando realmente precisa

Ou seja, o corpo pesado da skill só entra na conversa quando ela é chamada

Mas o nível 0 é diferente: o índice de skills entra no system prompt como um bloco chamado <available_skills>, e ele costuma ser o maior bloco isolado quando você tem muitas skills instaladas

Esse é o custo que você paga ANTES de digitar qualquer coisa, em toda conversa, sempre

Como organizar as habilidades do Hermes Agent passo a passo

A sequência abaixo é medir, agrupar, desambiguar e só depois cortar

Nessa ordem mesmo, porque cortar antes de medir é chute

1. Meça o custo fixo do seu prompt

Existe um comando oficial que quebra esse custo por componente:

hermes prompt-size

Ele roda offline, sem chamada de API e sem credenciais, e separa system prompt total, índice de skills, memória e perfil, e schemas de ferramentas

Se você quiser jogar isso pra outro lugar ou olhar por plataforma:

hermes prompt-size --json
hermes prompt-size --platform telegram

O erro comum deste passo: pular ele e ir direto desinstalar skill no chute, sem saber qual pedaço estava pesando de verdade

2. Agrupe por objetivo, não por origem

Dá pra organizar as skills em subdiretórios por categoria dentro da pasta de skills

Os exemplos da própria documentação são estes:

~/.hermes/skills/devops/
~/.hermes/skills/research/

E a justificativa oficial é bem direta: isso mantém a lista gerenciável e ajuda o agente a achar a skill relevante mais rápido

Repara que o critério é OBJETIVO (o que eu quero conseguir), não ferramenta nem quem escreveu

O erro comum deste passo: criar dez categorias com uma skill cada, o que é a mesma bagunça só que com mais pastas 😀

3. Reescreva a description em formato de gatilho

Uma skill invocada pelo modelo paga o custo da própria description em todo turno

Por isso a doc manda manter a description focada no gatilho, neste formato:

---
description: "Use when <trigger>. <one-line behavior>."
---

Detalhe, exemplo e exceção vão pro corpo da skill ou pra referências linkadas, nunca pra description

É o mesmo exercício de escrever o prompt de um subagente: quanto mais específico o disparo, menos o modelo precisa adivinhar sua intenção

O erro comum deste passo: usar a description como resumo bonito da skill, tipo "ferramenta poderosa para automação de deploys", que não diz QUANDO acionar

4. Crie a seção de quando usar, com contra-gatilhos

A documentação de autoria recomenda uma seção chamada "When to Use" (um título de nível 2 dentro do SKILL.md) com os gatilhos em bullets e, junto dela, uma lista Don't use for:

A lista negativa é o que desambigua skills parecidas, e ela é a parte que o pessoal esquece

When to Use

- quando o pedido envolve X
- quando o pedido envolve Y

Don't use for:
- Z (use a skill de Z)

O erro comum deste passo: listar só os gatilhos positivos e deixar duas skills vizinhas brigando pela mesma tarefa pra sempre

5. Ordene o corpo do SKILL.md por frequência de uso

A boa prática oficial de escrita é colocar o fluxo mais comum primeiro e empurrar casos de borda e uso avançado pro fim do arquivo

O motivo é custo de token nas tarefas comuns, que são justamente as que você repete todo dia

O erro comum deste passo: começar o arquivo com três parágrafos de contexto filosófico antes de dizer o que fazer

6. Corte dos dois lados, depois de medir

A recomendação oficial pra reduzir o prompt fixo tem duas frentes: desabilitar toolsets que você não usa e desinstalar skills desnecessárias

hermes tools
hermes skills

E tem um truque bom no frontmatter: a skill pode declarar dependência de toolset, e assim ela não ocupa o prompt quando aquele toolset está desligado

---
requires_toolsets:
  - web
---

O erro comum deste passo: mexer só nas skills e esquecer dos schemas de ferramentas, que aparecem separados na saída do hermes prompt-size justamente porque também pesam

7. Instale só o que faltou

Depois de limpar, dá pra navegar e trazer coisa nova sem inflar tudo de novo:

hermes skills browse
hermes skills install owner/repo/skills/minha-workflow

O browse mostra os slugs exatos pra instalar, e o install pega uma skill isolada de qualquer repositório público do GitHub, sem adicionar o repo inteiro

Esse "sem adicionar o repo inteiro" é o ponto: é a diferença entre ganhar uma habilidade e ganhar quarenta

O erro comum deste passo: instalar um pacote gigante pra usar uma única skill dele

O agente escolheu a ferramenta errada: o que causa e como corrigir

Três sintomas clássicos, e o que fazer em cada um

Sintoma: duas skills parecidas disputando a mesma tarefa

Causa: descriptions genéricas demais

Como a ativação automática sai do campo description, duas descrições vagas viram dois candidatos igualmente plausíveis, e o modelo escolhe uma

Por isso chamar pelo slash command não resolve o problema de fundo: ali você já sabia qual queria, e o buraco é justamente quando quem decide é o agente

Solução: description no formato de gatilho, mais a seção "When to Use" com bullets e a lista Don't use for: apontando explicitamente pra skill vizinha

Você não está "explicando melhor", você está separando fronteira

Sintoma: prompt fixo inchado, índice de skills dominando tudo

Causa: catálogo grande ativo

Lembra que são 79 skills embutidas em 14 categorias, e que ainda existe o catálogo opcional de 114 que pode ser ligado?

Quando muita coisa fica ativa, o bloco <available_skills> vira o maior bloco isolado do system prompt

Solução: medir com hermes prompt-size, desligar toolsets não usados, desinstalar o que não faz parte da sua rotina e declarar requires_toolsets nas skills que dependem de um toolset específico

Sintoma: skills antigas que ninguém usa continuam competindo

Causa: falta de poda

Skill que você criou pra um projeto de três meses atrás continua lá, no índice, disputando atenção com as que importam hoje

Solução: o Curator, que é o assunto da próxima seção

Como prevenir desde a instalação:

Dá pra começar limpo

A flag --no-skills na instalação cria um perfil sem nenhuma skill embutida, e esse perfil continua vazio entre atualizações (ele não repovoa sozinho depois)

E se você removeu algo e se arrependeu:

hermes skills reset <nome> --restore

Esse comando devolve uma skill embutida que sumiu do perfil

Tome cuidado com um efeito colateral que passa batido, e que é aquele caminho manual que citei lá no começo: toda skill instalada vira automaticamente um slash command /nome-da-skill

Ou seja, cada instalação não polui só o índice que o modelo lê sozinho, polui também a sua lista de comandos

Quando é hora de podar: como o Curator decide o que sai

O Hermes tem um recurso chamado Curator

É uma tarefa de fundo, com modelo auxiliar, que revisa periodicamente as skills criadas pelo agente: poda as obsoletas, consolida sobreposições e arquiva o que caiu em desuso

O porquê dele existir é a parte interessante: o agente tem um loop de auto-melhoria que gera skills, e sem alguém varrendo isso periodicamente esse monte cresce pra sempre

Ele já vem ligado:

O padrão é curator.enabled: true

A configuração fica no ~/.hermes/config.yaml, e pra desligar em um perfil você edita esse arquivo:

curator:
  enabled: false

Os prazos padrão:

E se ele podar algo que eu queria?

Aqui dá pra respirar aliviado: o Curator nunca apaga skills automaticamente

O pior desfecho é o arquivamento, e arquivamento é recuperável, os arquivos vão pra ~/.hermes/skills/.archive/

Tem também um piso de carência pra quem nunca foi usado: skill com use_count == 0 só é arquivada depois de ter pelo menos stale_after_days de idade

Faz sentido, né? Zero uso não prova que a skill é descartável, prova só que ela é nova

E existem skills que ele simplesmente pula na varredura: as pinadas e as referenciadas por qualquer cron job, incluindo jobs pausados ou desabilitados

Quanto isso custa?

A poda por idade e uso não gasta chamada ao modelo auxiliar, ela roda sempre que o Curator está ligado

Já a consolidação de skills sobrepostas, aquela que usa LLM pra perceber que duas skills fazem quase a mesma coisa, é opcional e vem DESLIGADA

Pra ligar de forma permanente:

curator:
  consolidate: true

Ou rodar sob demanda, quando você quiser:

hermes curator run --consolidate

Uma varredura completa costuma consumir de 50 a 100 chamadas de API, então é o tipo de coisa que faz sentido rodar de vez em quando, não toda hora

Conclusão

Organizar skill não é arrumação estética, não é deixar a pasta bonitinha pra tirar print

É decisão de custo de prompt (o índice entra em toda conversa, sempre) e de desambiguação (quando quem escolhe é o agente, ele escolhe pela description, não pela sua boa intenção)

O próximo passo é bem concreto e leva poucos minutos: roda hermes prompt-size hoje, anota o tamanho do índice de skills, agrupa o que você tem em duas ou três categorias por objetivo

E marca no calendário pra revisitar daqui 30 dias, que é justamente o prazo em que o Curator começa a marcar skill sem uso como obsoleta

Aí você compara os dois números e vê o estrago (ou o ganho) com dado na mão, não no achismo 🙂

até o próximo post!