Documentação oficial desta página · v0.20.6
Trabalhar com Skills
Skills são documentos de conhecimento sob demanda que ensinam o Hermes a lidar com tarefas específicas — de gerar ASCII art a cuidar de PRs no GitHub. Este guia mostra como usá-las no dia a dia.
Para a referência técnica completa, veja Sistema de Skills.
Encontrar skills
Toda instalação do Hermes já vem com skills embutidas. Para ver o que existe:
# Em qualquer sessão de conversa:
/skills
# Ou pela CLI:
hermes skills list
Isso mostra uma lista compacta com nomes e descrições:
ascii-art Generate ASCII art using pyfiglet, cowsay, boxes...
arxiv Search and retrieve academic papers from arXiv...
github-pr-workflow Full PR lifecycle — create branches, commit...
plan Plan mode — inspect context, write a markdown...
excalidraw Create hand-drawn style diagrams using Excalidraw...
Buscar uma skill
# Busque por palavra-chave
/skills search docker
/skills search music
O hub de skills
As skills opcionais oficiais (skills mais pesadas ou de nicho, que não ficam ativas por padrão) estão disponíveis pelo hub:
# Navegue pelas skills opcionais oficiais
/skills browse
# Busque no hub
/skills search blockchain
Usar uma skill
Toda skill instalada é automaticamente um comando de barra. Basta digitar o nome dela:
# Carregue uma skill e dê uma tarefa a ela
/ascii-art Faça um banner escrito "HELLO WORLD"
/plan Projete uma API REST para um aplicativo de tarefas
/github-pr-workflow Crie um PR para a refatoração da autenticação
# Só o nome da skill (sem tarefa) carrega a skill e deixa você descrever o que precisa
/excalidraw
Você também pode acionar skills numa conversa normal — peça ao Hermes para usar uma skill específica e ele a carrega pela ferramenta skill_view.
Revelação progressiva
As skills usam um padrão de carregamento econômico em tokens. O agente não carrega tudo de uma vez:
skills_list()— lista compacta de todas as skills (cerca de 3 mil tokens). Carregada no início da sessão.skill_view(name)— o conteúdo completo do SKILL.md de uma skill. Carregado quando o agente decide que precisa daquela skill.skill_view(name, file_path)— um arquivo de referência específico dentro da skill. Só é carregado se for necessário.
Ou seja: skills não custam tokens até serem realmente usadas.
Instalar do hub
As skills opcionais oficiais vêm com o Hermes, mas não ficam ativas por padrão. Instale-as explicitamente:
# Instale uma skill opcional oficial
hermes skills install official/research/arxiv
# Instale do hub, numa sessão de conversa
/skills install official/creative/songwriting-and-ai-music
# Instale o SKILL.md e os arquivos de apoio que ele referencia, a partir de uma URL HTTP(S)
hermes skills install https://sharethis.chat/SKILL.md
/skills install https://example.com/SKILL.md --name minha-skill
O que acontece:
- O diretório da skill é copiado para
~/.hermes/skills/ - Ela aparece na saída do
skills_list - Ela passa a existir como comando de barra
Skills instaladas passam a valer em sessões novas. Se você quer usá-la na sessão atual, rode /reset para começar do zero, ou acrescente --now para invalidar o cache do prompt na hora (isso custa mais tokens no turno seguinte).
Conferir a instalação
# Confirme que ela está lá
hermes skills list | grep arxiv
# Ou na conversa
/skills search arxiv
Skills vindas de plugins
Plugins podem trazer as próprias skills, com nomes em espaço de nomes (plugin:skill). Isso evita colisão de nome com as skills embutidas.
# Carregue uma skill de plugin pelo nome qualificado
skill_view("superpowers:writing-plans")
# A skill embutida de mesmo nome-base não é afetada
skill_view("writing-plans")
Skills de plugin não são listadas no prompt do sistema e não aparecem no skills_list. Elas são opcionais por escolha — carregue-as explicitamente quando você souber que um plugin oferece uma. Ao carregar uma delas, o agente vê um aviso listando as skills irmãs do mesmo plugin.
Para saber como distribuir skills no seu próprio plugin, veja Criar um Plugin do Hermes → Distribuir skills.
Configurar os ajustes de uma skill
Algumas skills declaram no frontmatter a configuração de que precisam:
metadata:
hermes:
config:
- key: tenor.api_key
description: "Chave de API do Tenor para busca de GIFs"
prompt: "Digite sua chave de API do Tenor"
url: "https://developers.google.com/tenor/guides/quickstart"
Quando uma skill com configuração é carregada pela primeira vez, o Hermes pede os valores a você. Eles ficam guardados no config.yaml, em skills.config.*.
Para gerenciar a configuração de skills pela CLI:
# Configuração interativa de uma skill específica
hermes skills config gif-search
# Veja toda a configuração de skills
hermes config get skills.config --json
Criar a sua própria skill
Skills são apenas arquivos markdown com frontmatter YAML. Criar uma leva menos de cinco minutos.
1. Crie o diretório
mkdir -p ~/.hermes/skills/minha-categoria/minha-skill
2. Escreva o SKILL.md
---
name: minha-skill
description: Descrição breve do que esta skill faz
version: 1.0.0
metadata:
hermes:
tags: [minha-tag, automacao]
category: minha-categoria
---
# Minha Skill
## Quando usar
Use esta skill quando o usuário perguntar sobre [assunto específico] ou precisar de [tarefa específica].
## Procedimento
1. Primeiro, confira se [pré-requisito] está disponível
2. Rode `command --with-flags`
3. Interprete a saída e apresente os resultados
## Armadilhas
- Falha comum: [descrição]. Correção: [solução]
- Fique atento a [caso extremo]
## Verificação
Rode `check-command` para confirmar que o resultado está correto.
3. Acrescente arquivos de referência (opcional)
Skills podem incluir arquivos de apoio que o agente carrega sob demanda:
minha-skill/
├── SKILL.md # Documento principal da skill
├── references/
│ ├── api-docs.md # Referência de API que o agente pode consultar
│ └── examples.md # Exemplos de entrada e saída
├── templates/
│ └── config.yaml # Arquivos de modelo que o agente pode usar
└── scripts/
└── setup.sh # Scripts que o agente pode executar
Referencie esses arquivos no seu SKILL.md:
Para detalhes da API, carregue a referência: `skill_view("minha-skill", "references/api-docs.md")`
4. Teste
Comece uma sessão nova e experimente a sua skill:
hermes chat -q "/minha-skill me ajude com aquilo"
A skill aparece automaticamente — não precisa registrar nada. Coloque-a em ~/.hermes/skills/ e ela já está no ar.
O agente também pode criar e atualizar skills por conta própria, com o skill_manage. Depois de resolver um problema complicado, o Hermes pode oferecer para salvar a abordagem como skill, para a próxima vez.
Gerenciar skills por plataforma
Para controlar quais skills ficam disponíveis em quais plataformas:
hermes skills
Isso abre uma TUI interativa em que você habilita ou desabilita skills por plataforma (CLI, Telegram, Discord etc.). Útil quando você quer certas skills apenas em contextos específicos — por exemplo, manter as skills de desenvolvimento fora do Telegram.
Skills ou memória
As duas coisas persistem entre sessões, mas servem a propósitos diferentes:
| Skills | Memória | |
|---|---|---|
| O quê | Conhecimento procedural — como fazer as coisas | Conhecimento factual — o que as coisas são |
| Quando | Carregada sob demanda, só quando é relevante | Injetada automaticamente em toda sessão |
| Tamanho | Pode ser grande (centenas de linhas) | Deve ser compacta (só os fatos essenciais) |
| Custo | Zero tokens até ser carregada | Custo de tokens pequeno, mas constante |
| Exemplos | "Como implantar no Kubernetes" | "O usuário prefere modo escuro, mora no fuso PST" |
| Quem cria | Você, o agente, ou vem instalada do hub | O agente, a partir das conversas |
Regra de bolso: se você colocaria numa documentação de referência, é skill. Se você colocaria num post-it, é memória.
Dicas
Mantenha as skills focadas. Uma skill que tenta cobrir "todo o DevOps" vai ficar longa e vaga demais. Uma skill que cobre "implantar um app Python no Fly.io" é específica o bastante para ser realmente útil.
Deixe o agente criar skills. Depois de uma tarefa complicada de vários passos, o Hermes costuma oferecer para salvar a abordagem como skill. Aceite — essas skills escritas pelo agente registram o fluxo exato, inclusive as armadilhas descobertas no caminho.
Use categorias. Organize as skills em subdiretórios (~/.hermes/skills/devops/, ~/.hermes/skills/research/ etc.). Isso mantém a lista administrável e ajuda o agente a achar mais rápido as skills relevantes.
Atualize as skills quando envelhecerem. Se você usar uma skill e bater em problemas que ela não cobre, peça ao Hermes para atualizá-la com o que você aprendeu. Skills sem manutenção viram um passivo.
Para a referência completa de skills — campos de frontmatter, ativação condicional, diretórios externos e mais — veja Sistema de Skills.