Como criar uma skill personalizada para o Hermes Agent

Uma skill é a menor unidade de comportamento que você consegue ensinar ao Hermes Agent sem mexer no código-fonte. É uma pasta, um arquivo markdown e um pequeno cabeçalho YAML. A documentação oficial da Nous Research descreve o formato como "portátil porque é simples", e criar uma skill personalizada leva menos de cinco minutos quando você já conhece o formato.

Este guia percorre esse formato de ponta a ponta. Você vai ver onde as skills ficam no disco, o que o cabeçalho do SKILL.md precisa conter, quais seções o agente realmente lê em execução, como injetar segredos via required_environment_variables e como verificar que a skill carregou corretamente. O resultado é uma skill que você pode jogar dentro de ~/.hermes/skills/ e usar no mesmo dia.

Onde as skills vivem e como o Hermes as encontra

O Hermes guarda as skills como pastas dentro de ~/.hermes/skills/. As skills nativas são copiadas para lá durante a instalação, e qualquer skill personalizada que você adicionar é registrada imediatamente no próximo reinício. A organização é plana:

~/.hermes/skills/
├── backup-check/
│   └── SKILL.md
├── invoice-followup/
│   └── SKILL.md
└── stripe-mrr-digest/
    ├── SKILL.md
    └── helper.py

O nome da pasta é o id da skill. O Hermes descobre cada pasta automaticamente ao iniciar e lê o SKILL.md correspondente. O campo description do frontmatter YAML é o que o agente compara com a sua mensagem em tempo de execução, então escreva pensando no agente, não em um leitor humano. Se a descrição não deixar clara a condição de gatilho, a skill não será disparada quando você espera.

Uma skill pode incluir arquivos extras na pasta: um helper em Python, um template SQL, uma checklist em texto. O Hermes não executa nada disso sozinho. Eles ficam lá para que o agente os leia ou os execute quando o procedimento mandar.

Diagrama de três pastas de skills dentro de ~/.hermes/skills/, cada uma com um SKILL.md, com setas apontando para o processo do Hermes Agent em execução

O formato do arquivo SKILL.md

Toda skill é um único arquivo markdown. O cabeçalho YAML no topo é o bloco de metadados, e o corpo em markdown é o conjunto de instruções. Aqui está um esqueleto mínimo que você pode copiar:

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 0.1.0
author: [email protected]
required_environment_variables: []
required_credential_files: []
---

Os campos que importam no primeiro dia:

name - igual ao nome da pasta. Em kebab-case, sem espaços.
description - uma única frase que o Hermes usa para decidir quando carregar a skill. Seja específico sobre o gatilho ("quando o usuário perguntar sobre X", "antes de executar Y").
version - é livre, mas trate como semver para conseguir incrementar conforme o conteúdo evolui.
required_environment_variables - um array com os nomes dos segredos que precisam estar definidos antes de a skill rodar. O agente pede os valores na primeira ativação e escreve em .env.
required_credential_files - caminhos para tokens OAuth ou arquivos JSON de service account que precisam ser montados dentro do sandbox.

Campos opcionais que vale conhecer: platforms (array com macos, linux, windows se a skill só funciona em alguns), requires_toolsets para mostrar a skill apenas quando determinados toolsets estão carregados, e fallback_for_toolsets para o oposto. A configuração no nível de skill vive em metadata.hermes.config e termina em skills.config no seu config.yaml para preferências não secretas como caminhos ou domínios.

As cinco seções que o agente realmente lê

Abaixo do frontmatter, o corpo em markdown é prosa. O Hermes não exige nenhuma seção específica, mas uma estrutura em cinco partes se consolidou a partir do guia oficial "Working with Skills" e de artigos de autores no dev.to e no glukhov.org. O agente aproveita essa estrutura porque cada parte responde a uma pergunta diferente em execução.

Quando usar

Um parágrafo curto que distingue esta skill de outras que o agente poderia escolher. Se você tem uma skill invoice-followup e outra client-update, "quando usar" é o que impede o agente de disparar a errada.

Referência rápida

Uma lista com os comandos, caminhos ou constantes de que o procedimento depende. O agente lê antes do procedimento para carregar contexto. Coloque aqui os caminhos de arquivos, o nome do bucket S3, os nomes das variáveis de ambiente, o id do chat de Telegram de destino.

Procedimento

Os passos numerados que o agente deve seguir. Escreva em imperativo ("execute X", "se a resposta contiver Y, faça Z"). O agente trata esta seção como uma receita e costuma citar ou parafrasear os passos enquanto executa.

Armadilhas

As ciladas que você já conhece. Limites de taxa, falhas silenciosas, bugs de fuso horário, aquele cliente cujos dados têm uma forma estranha. O agente lê isso como guarda-corpos e avisa ou recusa quando detecta essas condições.

Verificação

Como o agente confirma que fez a coisa certa. Um grep, um curl, um checksum, um "me mostre a última linha". A verificação é o que transforma uma skill em algo que você pode deixar rodando sozinho.

Conectando segredos e credenciais

Se a sua skill conversa com uma API, declare o segredo em required_environment_variables:

required_environment_variables:
  - STRIPE_RESTRICTED_KEY
  - SLACK_WEBHOOK_URL

Na primeira vez que a skill é ativada, o agente pede cada valor e os escreve no .env do projeto. Depois eles são passados automaticamente para os sandboxes (Docker, Modal, runners efêmeros). Nunca deixe uma chave dentro da prosa: o agente vai colar o valor durante a execução e ele acaba em algum log.

Para tokens OAuth ou arquivos JSON de service account, use required_credential_files:

required_credential_files:
  - ~/.config/gcloud/application_default_credentials.json

Eles são montados no sandbox como volumes somente leitura. O agente não os interpreta: só garante que estejam presentes antes de rodar o procedimento.

Como o Hermes extrai skills automaticamente das conversas

Você também pode deixar o Hermes escrever skills por você. Depois de uma tarefa complexa que envolveu cinco ou mais chamadas de ferramentas, a ferramenta skill_manage captura o padrão bem-sucedido e o escreve como uma skill reutilizável em ~/.hermes/skills/. O agente analisa a conversa, identifica o fluxo reutilizável e gera um SKILL.md com um procedimento que reflete o que foi feito de fato.

Este é o mesmo mecanismo que faz o Hermes parecer ficar mais afiado com o uso. A camada de memória persistente lembra do que vocês conversaram; as skills auto-extraídas lembram como ele resolveu um problema. As duas camadas são explicadas com mais profundidade no nosso post sobre memória e skills do Hermes Agent.

As primeiras skills auto-extraídas costumam ser 80 por cento do que você queria e 20 por cento ruído. Abra o SKILL.md, refine a descrição, remova os passos que o agente executou por acidente e suba a versão. Você passa a ter uma skill editada à mão que dispara de forma confiável.

Testando uma skill de ponta a ponta

Depois que o SKILL.md está no lugar, reinicie o Hermes (ou rode hermes skill reload se a sua build suportar). Em seguida, faça três verificações:

Peça ao Hermes para listar as skills. A nova deve aparecer com o nome e a descrição que você escreveu.
Envie uma mensagem que corresponda à condição de gatilho. O agente deveria anunciar que vai usar a skill antes de qualquer coisa.
Rode manualmente a etapa de verificação. Se a skill escreve um arquivo, confira o arquivo. Se publica em um webhook, confira o webhook.

Se a skill não carregar, o YAML costuma ser o culpado. Um tab perdido ou um dois pontos sem aspas quebra silenciosamente o parser do frontmatter. O Hermes registra o erro no stderr ao iniciar; cheque na primeira vez que recarregar.

Cena fotorrealista do terminal de um desenvolvedor mostrando uma sessão do Hermes Agent carregando uma skill personalizada, com prompt verde e iluminação ambiente suave

Pule a parte chata com o Hermes gerenciado

Uma skill personalizada é um arquivo markdown, mas rodar o Hermes em si não é. Você precisa de um host, uma chave de provedor de modelo, um bot do Telegram ou uma web UI, uma estratégia de backup para o diretório de skills e uma forma de testar mudanças sem quebrar o agente em produção.

O Hermify é hosting gerenciado de Hermes Agent que cuida de tudo isso. O seu diretório de skills persiste entre reinícios, as chaves de modelo vivem em armazenamento criptografado em repouso, e você pode combinar as skills personalizadas que escrever aqui com as integrações MCP que o Hermes já fala. Comece com o Hermify e a sua primeira skill personalizada pode estar rodando em um agente de verdade em menos de cinco minutos.