📜 Padrão agentskills.io
Skills no Hermes seguem o padrão aberto agentskills.io: uma pasta autocontida com um arquivo SKILL.md na raiz. Esse padrão também é usado por Claude Code, Codex e outros runtimes — escrever uma skill bem feita significa portabilidade real entre agentes.
💡 Por que um padrão aberto importa
- •Portabilidade: mesma pasta roda em Hermes, Claude Code, Codex sem alteração.
- •Descoberta: marketplaces e busca semântica funcionam por description padronizada.
- •Sem lock-in: trocar de runtime não exige reescrever conhecimento.
Spec oficial: agentskills.io · Docs Hermes: hermes-agent.nousresearch.com/docs/user-guide/features/skills
📊 Tamanho típico no ecossistema
- ~120 linhas - tamanho mediano do SKILL.md de uma skill bem feita
- 1-3 arquivos auxiliares - scripts, templates ou referências
- < 8KB - tamanho de carga no contexto quando a skill é ativada
- 2-5 segundos - tempo de install típico via git clone
📂 Estrutura de uma skill
A estrutura mínima é uma pasta com o nome da skill contendo SKILL.md na raiz. Arquivos auxiliares (scripts, templates) ficam ao lado e são referenciados por path relativo.
# Estrutura típica
~/.hermes/skills/
└── deploy-helper/
├── SKILL.md # manifest + instruções (obrigatório)
├── README.md # docs humanas (opcional)
├── scripts/
│ ├── precheck.sh # asset executável
│ └── rollback.sh
├── templates/
│ └── deploy.yaml.j2 # template Jinja
└── evals.yaml # casos de teste# Criar esqueleto rapidamente
$ hermes skill new deploy-helper
✓ Criado ~/.hermes/skills/deploy-helper/SKILL.md
✓ Criado ~/.hermes/skills/deploy-helper/evals.yaml
→ Edite SKILL.md e rode: hermes skill eval deploy-helper💡 Dica: use hermes skill new
O scaffolder gera SKILL.md com frontmatter válido e evals.yaml vazio. Evita 90% dos erros de sintaxe e te dá um ponto de partida com as seções certas.
✍️ SKILL.md anatomy
O SKILL.md tem duas partes: frontmatter YAML (metadados que o roteador usa) e corpo markdown (instruções operacionais que entram no contexto quando a skill é ativada).
---
name: deploy-helper
description: Deploy de aplicações para staging e produção com checagens de
pré-deploy, blue-green switch e rollback automático. Use quando o usuário
pedir "fazer deploy", "subir para prod", "release nova versão" ou mencionar
ambientes staging/production.
version: 1.2.0
author: nei
license: MIT
tags: [devops, deploy, ci-cd]
---
# Deploy Helper
Você é o assistente de deploy. Siga este processo SEMPRE:
## 1. Pré-checagem
Rode `./scripts/precheck.sh` antes de qualquer deploy. Se falhar, ABORTE
e mostre o erro ao usuário. Nunca prossiga com warnings não resolvidos.
## 2. Confirmação humana (apenas produção)
Para ambiente `production`, peça confirmação explícita: "Confirma deploy
da v{X.Y.Z} para PRODUÇÃO? (sim/não)". Só prossiga com "sim".
## 3. Deploy blue-green
- Renderize o template `templates/deploy.yaml.j2` com a versão
- Aplique no slot inativo
- Aguarde health checks (max 120s)
- Faça switch de tráfego
- Mantenha slot antigo por 10min para rollback rápido
## 4. Rollback
Se health check falhar, rode `./scripts/rollback.sh` IMEDIATAMENTE
e notifique o canal #deploys.
## Exemplos
**Usuário:** "deploy v2.3.1 para staging"
**Ação:** precheck → deploy direto (sem confirmação em staging)
**Usuário:** "subir para produção"
**Ação:** peça versão → precheck → confirmação → blue-green✓ Description que FUNCIONA
- ✓Diz o que faz em 1 frase
- ✓Lista gatilhos naturais ("Use quando...")
- ✓Inclui sinônimos e variações de pedido
- ✓Menciona domínio (deploy, devops, etc)
✗ Description que NÃO funciona
- ✗"Helper para deploy" (vago demais)
- ✗Lista apenas funções técnicas internas
- ✗Em outro idioma do que o user fala
- ✗500+ palavras (vira parede ignorada)
⚠️ Atenção: skills com side-effects
Skills que tocam filesystem, fazem chamadas de rede ou executam comandos shell devem deixar isso EXPLÍCITO no SKILL.md ("Esta skill executa scripts locais", "Esta skill faz POST em API externa"). O usuário precisa saber o blast radius antes de instalar.
🧪 Testando skills
Sem eval, você não sabe se sua skill é chamada nem se a saída faz sentido. Hermes embute um runner de eval que mede trigger rate (a skill carrega quando deveria?) e acerto (a saída bate com o esperado?).
# evals.yaml
cases:
- name: trigger_deploy_staging
prompt: "faz deploy da v1.0.0 pro staging"
expect_skill: deploy-helper # deve ativar
expect_contains: ["precheck", "staging"]
- name: trigger_deploy_prod
prompt: "subir versão nova pra produção"
expect_skill: deploy-helper
expect_contains: ["confirma", "PRODUÇÃO"]
- name: negative_listar_arquivos
prompt: "lista os arquivos do diretório"
expect_skill: null # NÃO deve ativar
- name: negative_explicar_kubernetes
prompt: "o que é kubernetes?"
expect_skill: null$ hermes skill eval deploy-helper
Running 4 cases against deploy-helper...
✓ trigger_deploy_staging (skill loaded, contains OK)
✓ trigger_deploy_prod (skill loaded, contains OK)
✓ negative_listar_arquivos (skill not loaded, as expected)
✗ negative_explicar_kubernetes (skill loaded — false positive!)
3/4 passed. Trigger rate: 100% (target). False positives: 1.
→ Aperte a description para excluir perguntas conceituais.💡 Dica: rode eval a cada upgrade de modelo
Modelos novos podem mudar como interpretam descriptions. Uma skill com 100% trigger rate no Hermes-3-70B pode cair para 60% no Hermes-4. Inclua hermes skill eval --all no seu CI pós-upgrade.
📦 Publicando
Skill publicada = skill em repositório git público + (opcional) registro em marketplace. A partir daí qualquer um instala em 2 segundos.
Ideia
Identifique tarefa repetitiva
"Toda vez que faço deploy preciso lembrar 7 passos." Isso é uma skill esperando para nascer.
SKILL.md
Escreva as instruções
Frontmatter + corpo. Foque em description acionável e processo passo-a-passo.
Eval
Teste trigger e saída
Mínimo 4 casos (2 positivos + 2 negativos). 100% pass rate antes de publicar.
Install local
Use você mesmo por uma semana
Nenhuma skill sobrevive sem dogfooding. Use, sofra, ajuste.
Publicar
Push para GitHub com LICENSE
README com screenshot, MIT license, tag semântica v1.0.0.
Iterar
Issues viram patches
Bump versão, atualize evals, anuncie no Discord da Nous.
# Install de skill publicada
$ hermes skill install https://github.com/nei/deploy-helper
Cloning... done.
Validating SKILL.md... ok
Installed deploy-helper@1.2.0 in ~/.hermes/skills/
$ hermes skill list
NAME VERSION SOURCE
deploy-helper 1.2.0 github.com/nei/deploy-helper
db-migrator 0.4.1 github.com/nei/db-migrator
morning-briefing 2.0.0 (local)🔄 Skills auto-geradas
Hermes observa seu histórico de interações e, quando detecta um padrão repetido N vezes, sugere consolidar como nova skill. O SKILL.md inicial é gerado automaticamente e fica em modo "draft" até você revisar.
🤖 Como funciona
- •Detecção: mesma sequência de tools/perguntas em 3+ sessões diferentes.
- •Síntese: Hermes gera SKILL.md draft a partir do log + parafraseia em description acionável.
- •Revisão humana: você aprova/edita antes de virar skill ativa — nada é instalado automaticamente.
- •Iteração: a cada N usos, Hermes sugere refinamentos baseados no que funcionou vs falhou.
⚠️ Governance importa
Skills auto-geradas podem capturar workflows ruins que você só repetia por hábito. Trate o draft como ponto de partida, não verdade. Revise: faz sentido? Tem side-effects perigosos? Description está clara? Só depois aprove.
✅ Resumo do Módulo
Próximo módulo:
6.2 — 🔌 MCP, Tool Gateway, canais e Cron: integrar MCP servers, criar tools customizadas em Python, adicionar canais novos e agendar jobs.