Criação de Habilidades do Agente Hermes — Estrutura e Melhores Práticas do SKILL.md

O Hermes Agent trata skills (habilidades) como a forma padrão de ensinar fluxos de trabalho repetíveis. A documentação oficial descreve-os como documentos de conhecimento sob demanda, alinhados com a especificação aberta agentskills.io, carregados através de revelação progressiva para que o modelo veja primeiro um índice pequeno e só carregue as instruções completas quando uma tarefa realmente precisar delas.

A criação de habilidades tem menos a ver com redação engenhosa e mais com empacotamento — você está dizendo ao runtime quando carregar um procedimento, qual ordem de passos conta como “concluído” e como distinguir sucesso de uma falha silenciosa. Este artigo foca na estrutura de SKILL.md, pastas de suporte, regras de visibilidade e a divisão entre configurações secretas e não secretas — os detalhes que decidem se uma skill aparece nos comandos /slash, sobrevive a uma instalação do hub ou desaparece silenciosamente no CI.

O Hermes está inserido no cluster mais amplo AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure, onde os assistentes são tratados como sistemas construídos a partir de inferência, recuperação, memória e ferramentas, em vez de uma única superfície de chat. Os caminhos de instalação, conexão de provedores, comportamento do gateway e o layout de ~/.hermes são detalhados no guia Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting; a ergonomia diária do shell — hermes skills, perfis, gateway, memória — é mais fácil de consultar na Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts. Em implantações reais, as skills herdam isolamento de perfis (configuração, segredos, memórias e árvores de skills separadas). Hermes AI Assistant Skills for Real Production Setups argumenta para tratar esses perfis — e não arquivos markdown individuais — como a unidade de propriedade; tenha isso em mente ao nomear skills e decidir o que pertence a external_dirs compartilhados versus um único perfil.

Skill ou ferramenta?

A orientação oficial é direta. Use uma skill quando a capacidade for principalmente instruções em prosa mais comandos de shell e ferramentas que o Hermes já expõe — envolvendo um CLI, gerenciando git, chamando curl ou usando web_extract para buscas estruturadas. Use uma ferramenta quando você precisar de integração rigorosa para chaves de API e fluxos de autenticação, manipulação determinística de binários, streaming ou Python que deve executar da mesma maneira sempre.

Esse limite importa na prática porque as skills são distribuídas sem alterar o código do agente, enquanto as ferramentas acarretam sobrecarga de revisão e lançamento. A maioria das equipes se beneficia de começar com uma skill, promovendo apenas o núcleo frágil para uma ferramenta depois que os modos de falha estiverem óbvios (loops de atualização de autenticação, parsers binários, idempotência estrita).

Procedimentos versus memória curada

As skills respondem como executar um fluxo de trabalho; a memória central limitada do Hermes responde o que já foi acordado sobre o usuário e o projeto. Uma skill é carregada quando a tarefa corresponde à sua descrição; MEMORY.md e USER.md permanecem no prompt como uma pequena camada de fatos curados. Os dois mecanismos se complementam em vez de competir, e o panorama completo de snapshots, limites e provedores externos é detalhado em Hermes Agent Memory System: How Persistent AI Memory Actually Works.

Anatomia de um diretório de skill

No disco, cada skill é uma pasta sob ~/.hermes/skills/, frequentemente aninhada sob uma categoria como devops/ ou research/. O Hermes espera SKILL.md na folha; tudo o mais é estrutura opcional que você adiciona quando as instruções, caso contrário, se espalhariam demais. O padrão usual é references/ para tabelas longas ou documentos de fornecedores, templates/ para esqueletos de saída, scripts/ para helpers determinísticos e assets/ para arquivos estáticos que o agente não deve rebuscar.

Esse layout espelha como a revelação progressiva funciona na prática: o agente pode permanecer no arquivo principal até realmente precisar de um apêndice profundo. Manter a prosa do “caminho feliz” em SKILL.md e empurrar detalhes raramente usados para references/ é uma das formas mais baratas de proteger os orçamentos de tokens.

O Hermes também pode mesclar diretórios de skills externos via skills.external_dirs em config.yaml. Esses caminhos são varridos para descoberta, mas o agente ainda escreve através de skill_manage para a árvore principal ~/.hermes/skills/. Nomes locais obscurecem os externos, então se você “corrigir” uma skill compartilhada em seu diretório home, colegas que puxarem o mesmo repositório externo não verão sua edição até que removam ou renomeiem a cópia local — uma fonte comum de confusão do tipo “funciona na minha máquina”.

Frontmatter de SKILL.md que sobrevive à revisão

O corpo de SKILL.md é Markdown; o bloco inicial deve ser YAML válido entre delimitadores ---. Skills reais acumulam exemplos longos e cercados, então os pequenos hábitos de Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples — tags de linguagem consistentes, trechos legíveis, cercas apertadas — mantêm arquivos grandes manuteníveis para humanos e ligeiramente mais fáceis para o modelo varrer.

Os campos obrigatórios são name e description. O name torna-se a rota slash e a chave do índice; permanece em minúsculas com hífens e deve respeitar o limite de comprimento documentado. A description é a única prosa que muitas sessões pagam no nível zero, então deve parecer um resultado de busca ou string de roteamento (“quando backups parecem desatualizados, verifique o arquivo mais recente e o checksum”), não o primeiro parágrafo de um post de blog.

Chaves de nível opcional como version, author e license ajudam no empacotamento do hub e em auditorias. A lista platforms (macos, linux, windows) é mais afiada do que parece — quando definida, o Hermes omite a skill inteiramente em hosts não correspondentes, é por isso que uma skill que “funciona no meu Mac” pode desaparecer no CI Linux sem nenhuma mensagem de erro além de uma lista de skills mais curta.

Os controles específicos do Hermes ficam sob metadata.hermes: tags, related_skills e os campos de visibilidade condicional na próxima seção. required_environment_variables declara segredos que devem cair em .env e passar para sandboxes; required_credential_files cobre arquivos de token OAuth e outros credenciais em disco que devem montar em Docker ou Modal; metadata.hermes.config declara preferências não secretas armazenadas sob skills.config em config.yaml.

A documentação oficial enfatiza disciplina de tamanho por um motivo. Recorte a description para seu orçamento, priorize o procedimento e empurre notas históricas ou matrizes de opções gigantescas para references/ para que um skill_view parcial ainda dê ao agente algo acionável.

Abaixo está um SKILL.md mínimo que você pode colocar em ~/.hermes/skills/devops/backup-check/SKILL.md (ou qualquer pasta de categoria) e iterar a partir daí.

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Absolute path to the directory that holds backup archives
        default: "/var/backups"
        prompt: Backup archive directory (absolute path)
---

# Backup archive spot-check

## When to use

Use when the user asks to confirm backups ran, to audit the latest archive on disk, or to catch empty or stale backup files before a restore drill.

## Quick reference

- Latest archive directory is configured under `skills.config.backup_check.archive_dir` (set via `hermes config migrate` if declared in metadata).
- Default check uses `ls` by mtime and `test -s` for non-empty files.

## Procedure

1. Resolve the archive directory from skill config or ask the user once if unset.
2. List the most recently modified file matching the expected pattern (for example `*.tar.zst`).
3. Confirm the file exists, is non-empty, and record its path and size for the reply.
4. If a checksum file exists beside the archive, verify it with the documented tool (for example `sha256sum -c`).

## Pitfalls

- Empty files can still have a recent mtime if a failed job touched the path; always check size.
- Relative paths break when the terminal cwd is not the backup host; use absolute paths in config.

## Verification

The user should see the latest archive path, byte size, and either a checksum OK line or an explicit note that no `.sha256` sidecar was found.

Revelação progressiva na prática

A revelação progressiva é a diferença entre uma biblioteca de skills que parece rápida e uma que queima milhares de tokens antes da primeira mensagem do usuário. O Hermes percorre três passos conceituais: um catálogo compacto (nomes e descrições curtas), o SKILL.md completo quando a tarefa corresponde e — apenas se necessário — uma fatia de um arquivo de referência via caminhos skill_view. Assuma que o nível zero é tudo o que o modelo lerá até que ele se comprometa explicitamente; cada frase na description e na primeira tela de texto do corpo deve ajudar no roteamento, não na narrativa.

Um esboço prático que sobrevive a cargas parciais é When to use (gatilhos em linguagem simples), Quick reference (comandos, variáveis de ambiente, caminhos de arquivos), Procedure (passos ordenados que o agente não deve improvisar), Pitfalls (modos de falha conhecidos) e Verification (como o “verde” se parece). História narrativa, dumps de changelog de fornecedores e tabelas de opções com vinte linhas pertencem em references/ com cabeçalhos estáveis para que o agente possa puxar uma única seção.

Quando uma skill é ativada, o Hermes pode reescrever ${HERMES_SKILL_DIR} e ${HERMES_SESSION_ID} no corpo para que linhas de shell apontem para a pasta instalada sem caminhos construídos manualmente. Trechos inline shell (!cmd``) opcionais podem injetar contexto fresco (branch atual, espaço em disco livre), mas eles executam no host e permanecem desativados a menos que skills.inline_shell esteja ativo — trate esse sinalizador como uma fronteira de confiança para toda a fonte da skill, não como um interruptor de conveniência.

Ativação condicional e higiene do prompt

As skills podem mostrar ou ocultar com base em quais toolsets ou ferramentas existem na sessão atual. requires_toolsets / requires_tools colocam uma skill atrás de capacidades que devem estar presentes; fallback_for_toolsets / fallback_for_tools expõem um caminho mais barato ou local quando uma integração premium está ausente — o fallback DuckDuckGo quando uma API de busca paga não está configurada é o exemplo canônico.

Esses predicados moldam diretamente o ruído do prompt. Uma regra requires_* excessivamente estrita esconde uma skill de novos usuários que ainda não terminaram a configuração de hermes tools; uma regra fallback_for_* excessivamente frouxa duplica metade da sua biblioteca sempre que alguém omite uma chave de API. O meio-termo útil é nomear pré-requisitos reais, testar com hermes chat --toolsets skills e alternar chaves ou toolsets propositalmente enquanto observa se a lista de skills respira da maneira que você espera.

Segredos, config e arquivos de credenciais

Segredos devem ser declarados em required_environment_variables. O Hermes pode solicitar quando uma skill carrega no CLI local, persistir valores em .env e passá-los para sandboxes terminal e execute_code sem streaming do segredo cru de volta para o transcript do modelo. Superfícies de chat remoto recusam coletar chaves inline e apontam as pessoas para hermes setup ou edições manuais de .env — autor seu texto de skill para que corresponda a esse comportamento (diga aos usuários que uma chave é necessária, não *para colá-la no Telegram).

Preferências não secretas — caminhos padrão, nomes de organizações, toggles de funcionalidade — pertencem em metadata.hermes.config. Os valores resolvem para skills.config dentro de config.yaml, aparecem em hermes config show e chegam à mensagem da skill como fatos resolvidos para que o modelo não precise abrir seu arquivo de config no meio da tarefa.

Credenciais em formato de arquivo (JSON de token OAuth, chaves de conta de serviço) mapeiam para required_credential_files. Quando esses arquivos existem, o Hermes pode montá-los em Docker ou sincronizá-los em jobs Modal; declará-los antecipadamente evita o clássico gap “script funciona localmente, falha na sandbox”.

Scripts de suporte e dependências

O guia upstream incentiva autores a usar dependências entediantes: stdlib Python, curl e as próprias ferramentas do Hermes (web_extract, read_file, terminal). Isso tem menos a ver com pureza e mais com reprodutibilidade — cada pip install extra é outra falha silenciosa quando o agente roda em um container limpo.

Quando o parsing de JSON ou XML é complicado, um script curto sob scripts/ mais um caminho ${HERMES_SKILL_DIR} vence pedir ao modelo para re-derivar parsers em cada execução. Se você realmente precisar de um pacote, declare o comando de instalação em Procedure, repita o sintoma de falha em Pitfalls e dê um comando de Verification que falhe alto quando a dependência estiver faltando.

Publicação, instalações do hub e confiança

Skills da comunidade passam pelo Skills Hub e pelos outros caminhos de descoberta listados no guia do usuário — skills oficiais opcionais, slugs do GitHub, entradas skills.sh, índices .well-known e URLs crus de SKILL.md. As instalações são varridas por exfiltração óbvia, injeção e padrões destrutivos; níveis de confiança variam de builtin até community, e algumas descobertas só são corrigidas com --force enquanto os piores casos permanecem bloqueados inteiramente.

A forma do arquivo SKILL.md não é específica do Hermes; assistentes centrados em IDE usam a mesma ideia de carregamento progressivo com descoberta e gatilhos diferentes. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor é uma leitura de contraste útil — disciplina de frontmatter e “carregar apenas quando relevante” se transferem, mesmo quando o instalador e o cabeamento de comandos slash diferem.

Implantações em toda a organização geralmente emparelham um tap privado ou repositório Git compartilhado com external_dirs para compartilhamento somente leitura, mantendo a cópia gravável pelo agente sob cada perfil quando skill_manage é permitido para mutar skills no local.

Solução de problemas e otimização

Quando uma skill se comporta mal, percorra esta lista de verificação antes de reescrever a prosa.

• Visibilidade — Confirme predicados de platforms, requires_* e fallback_for_*. Uma skill que “funciona no meu Mac” mas não no CI Linux é frequentemente um guardião de plataforma.
• Colisões de nome — Nomes duplicados entre diretórios locais e externos seguem precedência local. Renomeie ou namespaca agressivamente.
• Layout de descoberta — Um SKILL.md mal posicionado ou pasta de categoria errada pode fazer a skill cair inteiramente do índice.
• Carga de tokens — Se sessões parecerem lentas, encurte descrições de nível zero, mova profundidade para references/ e desdupliche tabelas gigantes.
• Edições do agente — O Hermes pode criar, patchear ou deletar skills via skill_manage. Trate skills valiosas como código: revise diffs, exporte snapshots e resete skills bundled deliberadamente quando atualizações divergem.

Um loop de regressão apertado vence reler o arquivo inteiro: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" deve mostrar o agente puxando o nível de revelação correto antes de improvisar. Se ele nunca invocar skill_view, seu texto When to use ou description provavelmente não corresponde a como as pessoas formulam pedidos.

As referências oficiais permanecem autoritativas para mudanças de comportamento — o guia do usuário Skills System para semânticas de runtime, Creating Skills para regras voltadas para autores, o Bundled Skills Catalog para exemplos de copiar e colar, e a agentskills.io specification para o formato de arquivo compartilhado com o qual o Hermes se alinha.