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

O Hermes Agent trata habilidades (skills) como o método padrão para ensinar fluxos de trabalho repetíveis. A documentação oficial as descreve como documentos de conhecimento sob demanda, alinhados com o formato aberto agentskills.io, carregados através de divulgação progressiva, de modo que o modelo vê primeiro um índice pequeno e só busca instruções completas quando uma tarefa realmente precisa delas.

A criação está menos relacionada a redação esperta do que a empacotamento—você está informando ao runtime quando carregar um procedimento, qual sequência de passos conta como “concluído” e como distinguir sucesso de uma falha silenciosa. Este artigo se concentra na estrutura do SKILL.md, pastas de apoio, regras de visibilidade e a divisão entre configurações secretas e não secretas—os detalhes que determinam se uma habilidade aparece em comandos /slash, sobrevive a uma instalação no hub ou desaparece silenciosamente em CI.

O Hermes está dentro do cluster mais amplo Sistemas IA: Assistentes Auto-Hospedados, RAG e Infraestrutura Local, onde 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. Caminhos de instalação, configuração de provedores, comportamento do gateway e o layout de ~/.hermes estão todos detalhados no guia Assistente IA Hermes - Instalação, Configuração, Fluxo de Trabalho e Solução de Problemas; a ergonomia diária do shell—hermes skills, perfis, gateway, memória—é mais fácil de consultar na Folha de Referência da CLI do Agente Hermes — comandos, flags e atalhos slash. Em implantações reais, habilidades herdam isolamento de perfis (configuração separada, segredos, memórias e árvores de habilidades). Habilidades do Assistente IA Hermes para Configurações de Produção Reais argumenta para tratar esses perfis—não arquivos markdown individuais—como a unidade de propriedade; tenha isso em mente ao nomear habilidades e decidir o que pertence em external_dirs compartilhados versus um único perfil.

Habilidade ou ferramenta?

A orientação oficial é direta. Use uma habilidade quando a capacidade for principalmente instruções em prosa mais comandos shell e ferramentas que o Hermes já expõe—envolvendo um CLI, operando git, chamando curl ou usando web_extract para buscas estruturadas. Use uma ferramenta quando precisar de integração apertada 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 toda vez.

Essa fronteira importa na prática porque habilidades são distribuídas sem alterar o código do agente, enquanto ferramentas carregam sobrecarga de revisão e lançamento. A maioria das equipes se beneficia de começar com uma habilidade, promovendo apenas o núcleo frágil para uma ferramenta depois que os modos de falha ficam óbvios (loops de renovação de autenticação, parsers binários, idempotência estrita). Para a questão arquitetural mais ampla de quando usar uma Habilidade de Agente versus um servidor MCP—especialmente em torno de credenciais, estado em tempo real e escritas transacionais—veja nosso framework de decisão Habilidades de Agente vs Servidores MCP.

Procedimentos versus memória curada

Habilidades respondem como executar um fluxo de trabalho; a memória principal limitada do Hermes responde o que já foi acordado sobre o usuário e o projeto. Uma habilidade é carregada quando a tarefa corresponde à sua descrição; MEMORY.md e USER.md permanecem no prompt como uma camada pequena e curada de fatos. Os dois mecanismos se empilham em vez de competir, e o quadro completo de snapshots, limites e provedores externos está detalhado em Sistema de Memória do Agente Hermes: Como a Memória IA Persistente Realmente Funciona.

Anatomia de um diretório de habilidade

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

Esse layout espelha como a divulgaçã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 orçamentos de tokens.

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

Frontmatter SKILL.md que sobrevive à revisão

O corpo de SKILL.md é Markdown; o bloco inicial deve ser YAML válido entre delimitadores ---. Habilidades reais acumulam exemplos longos cercados, então os pequenos hábitos do Blocos de Código Markdown: Guia Completo com Sintaxe, Linguagens & Exemplos—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 escanear.

Campos obrigatórios são name e description. O name se torna a rota slash e chave de í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 em nível zero, então deve ler como um resultado de busca ou string de roteador (“quando backups parecem obsoletos, verifique o último arquivo e checksum”), não o primeiro parágrafo de um post de blog.

Chaves opcionais de nível superior como version, author e license ajudam no empacotamento do hub e auditorias. A lista platforms (macos, linux, windows) é mais afiada do que parece—quando definida, o Hermes omite a habilidade inteiramente em hosts não correspondentes, razão pela qual uma habilidade que “funciona no meu Mac” pode desaparecer em CI Linux sem mensagem de erro além de uma lista menor de habilidades.

Botões específicos do Hermes vivem 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 tokens OAuth e outras 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.

Docs oficiais enfatizam disciplina de tamanho por uma razão. Reduza a description ao seu orçamento, carregue primeiro o procedimento e empurre notas históricas ou matrizes gigantes de opções para references/ para que uma 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: Verificar se os arquivos de backup noturno existem, não estão vazios e passam por uma verificação rápida de checksum no arquivo mais recente.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Caminho absoluto para o diretório que contém arquivos de backup
        default: "/var/backups"
        prompt: Diretório de arquivos de backup (caminho absoluto)
---

# Verificação rápida de arquivo de backup

## Quando usar

Use quando o usuário pedir para confirmar se backups foram executados, auditar o último arquivo em disco ou detectar arquivos de backup vazios ou obsoletos antes de um teste de restauração.

## Referência rápida

- O diretório do último arquivo é configurado sob `skills.config.backup_check.archive_dir` (defina via `hermes config migrate` se declarado em metadata).
- A verificação padrão usa `ls` por mtime e `test -s` para arquivos não vazios.

## Procedimento

1. Resolva o diretório de arquivo a partir da configuração da habilidade ou pergunte ao usuário uma vez se não definido.
2. Liste o arquivo mais recentemente modificado que corresponde ao padrão esperado (por exemplo `*.tar.zst`).
3. Confirme que o arquivo existe, não está vazio e registre seu caminho e tamanho para a resposta.
4. Se um arquivo de checksum existir ao lado do arquivo, verifique-o com a ferramenta documentada (por exemplo `sha256sum -c`).

## Armadilhas

- Arquivos vazios ainda podem ter mtime recente se um trabalho falhou tocou o caminho; sempre verifique o tamanho.
- Caminhos relativos quebram quando o cwd do terminal não é o host de backup; use caminhos absolutos na configuração.

## Verificação

O usuário deve ver o caminho do último arquivo, tamanho em bytes e ou uma linha de checksum OK ou uma nota explícita de que nenhum sidecar `.sha256` foi encontrado.

Divulgação progressiva na prática

A divulgação progressiva é a diferença entre uma biblioteca de habilidades que parece ágil e uma que queima milhares de tokens antes da primeira mensagem do usuário. O Hermes percorre três etapas 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 arquivo de referência via caminhos skill_view. Assuma que nível zero é tudo que o modelo lerá até explicitamente comprometer-se; cada frase na description e a primeira tela de texto do corpo devem ajudar no roteamento, não em narrativa.

Um esboço prático que sobrevive a cargas parciais é Quando usar (gatilhos em linguagem simples), Referência rápida (comandos, variáveis de ambiente, caminhos de arquivo), Procedimento (passos ordenados que o agente não deve improvisar), Armadilhas (modos de falha conhecidos) e Verificação (como “verde” parece). História narrativa, despejos de changelog de fornecedor e tabelas de opções de vinte linhas pertencem em references/ com cabeçalhos estáveis para que o agente possa puxar uma única seção.

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

Ativação condicional e higiene do prompt

Habilidades podem mostrar ou esconder baseado em quais toolsets ou ferramentas existem na sessão atual. requires_toolsets / requires_tools bloqueiam uma habilidade 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 web 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 habilidade de iniciantes que ainda não terminaram a configuração 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 habilidades respira do jeito esperado.

Segredos, configuração e arquivos de credenciais

Segredos devem ser declarados em required_environment_variables. O Hermes pode solicitar quando uma habilidade é carregada na CLI local, persistir valores em .env e passá-los para sandboxes terminal e execute_code sem transmitir o segredo bruto de volta para a transcrição do modelo. Superfícies de chat remoto se recusam a coletar chaves inline e em vez disso apontam pessoas para hermes setup ou edições manuais de .env—autorize seu texto de habilidade para que corresponda a esse comportamento (informe aos usuários que uma chave é necessária, não *para colar no Telegram).

Preferências não secretas—caminhos padrão, nomes de organização, alternadores de recurso—pertencem em metadata.hermes.config. Valores se resolvem para skills.config dentro de config.yaml, aparecem em hermes config show e chegam à mensagem da habilidade como fatos resolvidos para que o modelo não precise abrir seu arquivo de configuração 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 bind-mountá-los em Docker ou sincronizá-los em jobs Modal; declará-los antecipadamente evita o clássico “script funciona localmente, morre na sandbox”.

Scripts e dependências de apoio

O guia upstream empurra autores para dependências chatas: stdlib Python, curl e as próprias ferramentas do Hermes (web_extract, read_file, terminal). Isso é menos sobre pureza do que sobre reprodutibilidade—cada pip install extra é outra falha silenciosa quando o agente executa em um container limpo.

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

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

Habilidades da comunidade se movem através do Skills Hub e dos outros caminhos de descoberta listados no guia do usuário—habilidades opcionais oficiais, slugs GitHub, entradas skills.sh, índices .well-known e URLs brutas de SKILL.md. Instalações são varridas para exfiltração óbvia, injeção e padrões destrutivos; níveis de confiança vão de builtin através de community, e alguns achados só limpam 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. Habilidades Claude e SKILL.md para Desenvolvedores: VS Code, JetBrains, Cursor é uma leitura de contraste útil—disciplina de frontmatter e “carregar apenas quando relevante” se transferem, mesmo quando o instalador e a fiação de comandos slash diferem.

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

Solução de problemas e otimização

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

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

Um loop de regressão apertado supera reler o arquivo inteiro: hermes chat --toolsets skills -q "Use o fluxo <skill> para <tarefa concreta>" deve mostrar o agente puxando o nível de divulgação certo antes de improvisar. Se ele nunca invocar skill_view, seu texto Quando usar ou description provavelmente não corresponde a como as pessoas formulam pedidos.

Referências oficiais permanecem autoritativas para mudanças de comportamento—o guia do usuário Sistema de Habilidades para semânticas de runtime, Criando Habilidades para regras voltadas a autores, o Catálogo de Habilidades Bundled para exemplos de copiar e colar e a especificação agentskills.io para o formato de arquivo compartilhado com o qual o Hermes se alinha.