📜 O que é uma skill
Skill é um arquivo SKILL.md com YAML front matter no topo e instruções estruturadas abaixo. É um procedimento reutilizável escrito em linguagem natural — o modelo lê e segue.
🆚Skill vs prompt vs código
- Prompt avulso: some no fim da sessão. Repete sempre.
- Skill: Markdown estruturado, persistido, descoberto pelo agente quando relevante.
- Código: determinístico mas inflexível. Não toma decisão por contexto.
📡Padrão aberto
Hermes adota o spec público agentskills.io/specification. Skill criada pra Hermes vale também em outros agentes que adotam o padrão. Discord do hub: discord.gg/MKPE9g8aUy.
📋 Anatomia do YAML front matter
O front matter é o cabeçalho YAML entre --- que descreve a skill. É lido a cada sessão pra montar a lista que o agente consulta. Description ruim = skill nunca chamada.
📝 Front matter completo
---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux] # Opcional — restringe a OS específicos
metadata:
hermes:
tags: [python, automation]
category: devops
fallback_for_toolsets: [web] # Opcional — ativação condicional
requires_toolsets: [terminal] # Opcional — ativação condicional
config: # Opcional — config.yaml
- key: my.setting
description: "What this controls"
default: "value"
prompt: "Prompt for setup"
---Campos obrigatórios
name— identificador únicodescription— o que faz, em uma linhaversion— semver
metadata.hermes (opcional)
tags— busca rápidacategory— agrupamentofallback_for_toolsets— ativa se outro falharrequires_toolsets— exige toolset disponívelconfig— prompts de setup
🧱 Estrutura padrão do corpo
Abaixo do front matter vem o conteúdo Markdown. O modelo espera quatro seções canônicas: When to Use, Procedure, Pitfalls, Verification. Pular qualquer uma degrada a qualidade da skill.
📝 Esqueleto canônico
# Skill Title
## When to Use
Trigger conditions for this skill.
## Procedure
1. Step one
2. Step two
## Pitfalls
- Known failure modes and fixes
## Verification
How to confirm it worked.When to Use
Gatilhos. Quando o agente deve invocar esta skill. Sem isso, ele ou nunca chama ou chama errado.
Procedure
Passos numerados, diretos. Um passo por linha. Idealmente verificável.
Pitfalls
O que já quebrou e como contornar. Coletado da experiência real, não imaginação.
Verification
Teste curto: "se rodar X, deve sair Y". Sem isso, o agente declara sucesso achando que deu certo.
🪜 Progressive Disclosure (3 níveis)
O grande truque de eficiência: o agente não carrega todas as skills no system prompt. Carrega só uma lista mínima e abre cada skill sob demanda. Padrão chamado Progressive Disclosure.
Level 0 — skills_list()
Retorna lista [{name, description, category}, ...] de TODAS as skills disponíveis.
Custo: ~3.000 tokens. Sempre carregado.
Level 1 — skill_view(name)
Retorna o SKILL.md completo da skill escolhida + metadados.
Custo: variável. Carregado só quando o agente decide usar a skill.
Level 2 — skill_view(name, path)
Retorna arquivo específico de references/, templates/, scripts/ ou assets/.
Custo: variável. Carregado só quando o procedimento exige aquele arquivo.
💡Por que isso importa
Permite ter centenas de skills sem estourar contexto. Description curta e poderosa importa MUITO — é o que entra no L0 e decide se a skill será descoberta. Skills com description vaga ficam órfãs.
📁 Estrutura de diretórios
Cada skill mora em ~/.hermes/skills/<categoria>/<skill-name>/. Dentro do diretório, SKILL.md é obrigatório; subpastas opcionais separam tipos de arquivo.
📂 Layout de uma skill
~/.hermes/skills/
├── mlops/
│ └── axolotl/
│ ├── SKILL.md # Instruções principais (obrigatório)
│ ├── references/ # Docs adicionais
│ ├── templates/ # Formatos de output
│ ├── scripts/ # Scripts auxiliares
│ └── assets/ # Arquivos suplementaresreferences/
Docs longas, especificações, exemplos extensos
templates/
Modelos de output (relatório, email, post)
scripts/
Bash/Python pra execução determinística
assets/
Imagens, dados, qualquer arquivo extra
📦Versionamento via git
Como tudo é Markdown e arquivos auxiliares, versionar uma skill (ou todo o conjunto ~/.hermes/skills/) num repositório git é trivial. Você ganha histórico de evolução e migração entre máquinas vira git clone.
🌐 Skills Hub (agentskills.io)
Hub público em agentskills.io agrega skills da comunidade. O Hermes aceita instalação a partir de cinco fontes diferentes, do bundled oficial até auto-discovery via well-known.
official (bundled)
Skills no repositório NousResearch/hermes-agent em optional-skills/. Ativadas explicitamente.
skills-sh (hub externo)
agentskills.io — registry independente, mais skills, mais experimentação da comunidade.
GitHub direto
Formato user/repo/path. Útil pra skills hospedadas no seu próprio repo ou de terceiros não publicados.
URL direta
https://example.com/SKILL.md — qualquer URL pública que serve um SKILL.md válido funciona.
well-known (auto-discovery)
Aponte o agente para um domínio e ele busca skills em /.well-known/agent-skills. Padrão pra empresas publicarem catálogo oficial.
⚠️Atenção a skills externas
Skill é instrução que o agente segue. Skill maliciosa pode pedir pra exfiltrar secret, deletar arquivo ou abrir conexão externa. Revise SKILL.md antes de instalar — especialmente Procedure e scripts/. Trate skill como dependência: vinda de fonte confiável e auditada.
🎯Resumo do módulo
Próximo módulo:
3.3 - 👻 Soul: identidade do agente