Sistema de Skills

Skills são documentos de conhecimento sob demanda que o agente carrega quando precisa. Elas seguem um padrão de revelação progressiva para gastar o mínimo de tokens e são compatíveis com o padrão aberto agentskills.io.

Todas as skills ficam em ~/.hermes/skills/ — o diretório principal e a fonte da verdade. Numa instalação nova, as skills embutidas são copiadas do repositório. Skills instaladas pelo hub e skills criadas pelo agente também vão para lá. O agente pode alterar ou apagar qualquer skill.

Você também pode apontar o Hermes para diretórios externos de skills — pastas extras varridas junto com a local. Veja Diretórios externos de skills mais abaixo.

Veja também:

• Catálogo de skills embutidas
• Catálogo oficial de skills opcionais

Começar do zero

Por padrão, todo perfil já nasce com o catálogo de skills embutidas, e cada hermes update acrescenta as skills embutidas novas. Se você quer um perfil sem skills embutidas — e que continue vazio depois das atualizações — há dois caminhos:

Na hora de instalar (vale para o perfil padrão ~/.hermes):

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --no-skills

Na hora de criar o perfil (perfis nomeados):

hermes profile create research --no-skills

Num perfil já instalado (padrão ou nomeado), você liga e desliga em tempo de execução:

hermes skills opt-out            # para de semear no futuro — nada em disco é tocado
hermes skills opt-out --remove   # também apaga skills embutidas NÃO MODIFICADAS (pede confirmação)
hermes skills opt-in --sync      # desfaz: remove o marcador e semeia de novo agora

Os três caminhos escrevem um marcador .no-bundled-skills no diretório do perfil. Enquanto o marcador estiver lá, o instalador, o hermes update e qualquer sincronização de skills pulam a semeadura de skills embutidas nesse perfil. Apague o marcador (ou rode hermes skills opt-in) para reativar.

Seguro por padrão

hermes skills opt-out só interrompe a semeadura futura — nunca apaga o que já está em disco. A opção --remove apaga skills embutidas apenas quando elas estão intactas (idênticas byte a byte à versão que o Hermes instalou). Skills que você editou, skills instaladas pelo hub e skills que você mesmo escreveu são sempre preservadas.

Usar skills

Toda skill instalada vira automaticamente um comando de barra:

# Na CLI ou em qualquer plataforma de mensagem:
/gif-search gatos engraçados
/axolotl me ajude a fazer fine-tune do Llama 3 no meu dataset
/github-pr-workflow crie um PR para a refatoração de autenticação
/plan desenhe um plano de migração do nosso provedor de autenticação

# Só o nome da skill já carrega ela e deixa o agente perguntar o que você quer:
/excalidraw

Empilhar várias skills num comando só

Você pode invocar várias skills numa mesma mensagem encadeando comandos de barra no começo — todo token /skill inicial (até 5) é carregado, e o resto vira a sua instrução:

/github-pr-workflow /test-driven-development corrija a issue #123 e abra um PR

A leitura para no primeiro token que não é uma skill instalada, então argumentos que por acaso começam com / (como caminhos de arquivo) nunca são engolidos:

/ocr-and-documents /tmp/scan.pdf extraia as tabelas   # carrega uma skill; /tmp/scan.pdf é o argumento

Para combinações que você usa sempre, prefira um pacote de skills — mesmo efeito, sob um comando curto.

A skill embutida plan é um bom exemplo. Rodar /plan [pedido] carrega as instruções da skill, que mandam o Hermes inspecionar o contexto se precisar, escrever um plano de implementação em markdown em vez de executar a tarefa, e salvar o resultado em .hermes/plans/, relativo ao diretório de trabalho do espaço de trabalho/backend ativo.

Você também pode conversar sobre skills em linguagem natural:

hermes chat --toolsets skills -q "Quais skills você tem?"
hermes chat --toolsets skills -q "Me mostre a skill axolotl"

Aprender uma skill a partir de fontes (/learn)

/learn é o jeito rápido de transformar algo que você já sabe — ou uma pilha de material de referência — numa skill reaproveitável, sem escrever o SKILL.md à mão. Ele é aberto: aponte para qualquer coisa que você consiga descrever e o agente junta o material com as ferramentas que já tem, depois escreve uma skill que segue os padrões de autoria da casa (descrição de no máximo 60 caracteres, a ordem padrão das seções, enquadramento nas ferramentas do Hermes, nenhum comando inventado).

# Um SDK local ou um diretório de docs — lido com read_file / search_files
/learn o cliente REST em ~/projetos/acme-sdk, foco em auth + paginação

# Uma página de documentação online — buscada com web_extract
/learn https://docs.example.com/api/quickstart

# O fluxo que você acabou de percorrer com o agente nesta conversa
/learn como eu acabei de fazer o deploy do servidor de staging

# Anotações coladas / um procedimento descrito
/learn lançar uma despesa: abra o portal, Novo > Despesa, anexe o recibo, envie

# Um livro inteiro, uma pilha de artigos ou um corpus grande de docs — vira uma skill de base de conhecimento
/learn ~/livros/designing-data-intensive-applications.pdf

Fontes grandes viram skills de base de conhecimento

Quando a fonte é um livro, uma pilha de artigos, uma especificação ou uma pasta grande de documentação, o agente não enfia tudo num arquivo só nem reduz o material a um resumo com perdas. Em vez disso ele escreve uma skill expansiva de base de conhecimento: um SKILL.md enxuto com os modelos mentais centrais da fonte mais um índice, e um arquivo destilado por capítulo ou tópico dentro de references/ (além de um glossário ou uma cola, quando a fonte justifica). Os arquivos de referência não custam nada até que uma pergunta precise deles — o agente os carrega sob demanda com skill_view, então o custo da consulta fica proporcional à resposta, não à fonte. Rodar /learn de novo com material novo sobre o mesmo tema incorpora tudo à skill existente em vez de criar uma duplicata.

A destilação sintetiza estrutura — arcabouços, definições, regras de decisão, antipadrões — e nunca reproduz trechos do texto original.

Como quem faz a coleta é o próprio agente em execução, /learn funciona igual na CLI, no gateway de mensagens, na TUI e no painel — e em qualquer backend de terminal (local, Docker, remoto), já que não existe um motor de ingestão separado. No painel, a página Skills tem um botão Learn a skill que abre uma aba com um campo de diretório, um campo de URL e uma caixa de texto livre; ela monta um pedido /learn e roda no chat.

Não há pegada de ferramenta no modelo: /learn monta um prompt guiado pelos padrões e entrega ao agente como um turno normal. O agente salva o resultado com a ferramenta skill_manage, então a trava de aprovação de escrita vale se você a tiver ligada.

Revelação progressiva

As skills usam um padrão de carregamento econômico em tokens:

Nível 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Nível 1: skill_view(name)        → Conteúdo completo + metadados   (varia)
Nível 2: skill_view(name, path)  → Arquivo de referência específico (varia)

O agente só carrega o conteúdo completo da skill quando realmente precisa.

Formato do SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]     # Opcional — restringe a plataformas específicas
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]    # Opcional — ativação condicional (veja abaixo)
    requires_toolsets: [terminal]   # Opcional — ativação condicional (veja abaixo)
    config:                          # Opcional — configurações do config.yaml
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Título da skill

## Quando usar
Condições que disparam esta skill.

## Procedimento
1. Passo um
2. Passo dois

## Armadilhas
- Modos de falha conhecidos e correções

## Verificação
Como confirmar que deu certo.

Skills específicas de plataforma

Uma skill pode se restringir a certos sistemas operacionais pelo campo platforms:

Valor	Corresponde a
macos	macOS (Darwin)
linux	Linux
windows	Windows

platforms: [macos]            # só macOS (por exemplo, iMessage, Apple Reminders, FindMy)
platforms: [macos, linux]     # macOS e Linux

Quando o campo está preenchido, a skill some automaticamente do prompt de sistema, do skills_list() e dos comandos de barra em plataformas incompatíveis. Se você omitir, a skill carrega em todas as plataformas.

Saída da skill e entrega de mídia

Quando a resposta de uma skill (ou qualquer resposta do agente) inclui um caminho absoluto solto para um arquivo de mídia — por exemplo /home/user/screenshots/diagram.png — o gateway detecta sozinho, tira o caminho do texto visível e entrega o arquivo de forma nativa no chat do usuário (foto no Telegram, anexo no Discord etc.) em vez de deixar o caminho cru na mensagem.

No caso específico de áudio, a diretiva [[audio_as_voice]] promove arquivos de áudio a bolhas nativas de mensagem de voz nas plataformas que suportam isso (Telegram, WhatsApp).

Forçar entrega como documento: [[as_document]]

Às vezes você quer o contrário da pré-visualização embutida: quer o arquivo entregue como anexo para download, não como uma bolha de imagem recomprimida. O exemplo clássico é uma captura de tela ou um gráfico em alta resolução — o sendPhoto do Telegram recomprime para ~200 KB em 1280 px, destruindo a legibilidade. Um PNG de 1–2 MB enviado via sendDocument mantém os bytes originais intactos.

Se uma resposta (ou qualquer texto dentro dela — normalmente a última linha) contém a diretiva literal [[as_document]], todo caminho de mídia extraído daquela resposta é entregue como documento/anexo em vez de bolha de imagem:

Aqui está o seu gráfico renderizado:

/home/user/.hermes/cache/chart-q4-2025.png

[[as_document]]

A diretiva é removida antes da entrega, então os usuários nunca a veem. A granularidade é de propósito tudo-ou-nada por resposta: emita [[as_document]] uma vez e toda imagem daquela resposta vai como documento. É o mesmo escopo do [[audio_as_voice]].

Use isso numa skill quando:

• Você produz capturas de tela ou gráficos que o usuário precisa como arquivo (para editar em outra ferramenta, arquivar, compartilhar intactos).
• A pré-visualização com perdas esconderia detalhes (texto pequeno, diagramas com precisão de pixel, renderizações sensíveis a cor).

Plataformas sem um caminho separado para documentos (SMS, por exemplo) caem no mecanismo de anexo que tiverem.

Ativação condicional (skills de reserva)

Uma skill pode se mostrar ou se esconder sozinha conforme as ferramentas disponíveis na sessão. Isso é mais útil para skills de reserva — alternativas gratuitas ou locais que só devem aparecer quando uma ferramenta paga não está disponível.

metadata:
  hermes:
    fallback_for_toolsets: [web]      # Mostra SÓ quando esses toolsets estão indisponíveis
    requires_toolsets: [terminal]     # Mostra SÓ quando esses toolsets estão disponíveis
    fallback_for_tools: [web_search]  # Mostra SÓ quando essas ferramentas estão indisponíveis
    requires_tools: [terminal]        # Mostra SÓ quando essas ferramentas estão disponíveis

Campo	Comportamento
fallback_for_toolsets	A skill fica escondida quando os toolsets listados estão disponíveis. Aparece quando eles faltam.
fallback_for_tools	Igual, mas checa ferramentas individuais em vez de toolsets.
requires_toolsets	A skill fica escondida quando os toolsets listados estão indisponíveis. Aparece quando eles estão presentes.
requires_tools	Igual, mas checa ferramentas individuais.

Exemplo: a skill embutida duckduckgo-search usa fallback_for_toolsets: [web]. Com FIRECRAWL_API_KEY definida, o toolset web está disponível e o agente usa web_search — a skill do DuckDuckGo continua escondida. Se a chave de API não existe, o toolset web fica indisponível e a skill do DuckDuckGo aparece automaticamente como reserva.

Skills sem nenhum campo condicional se comportam como antes — estão sempre visíveis.

Configuração segura no carregamento

Uma skill pode declarar as variáveis de ambiente de que precisa sem sumir da descoberta:

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

Quando um valor faltante aparece, o Hermes pede por ele de forma segura — e só quando a skill é de fato carregada na CLI local. Você pode pular a configuração e continuar usando a skill. As superfícies de mensagem nunca pedem segredos no chat: elas mandam você usar hermes setup ou o ~/.hermes/.env localmente.

Uma vez definidas, as variáveis de ambiente declaradas são repassadas automaticamente aos sandboxes do execute_code e do terminal — os scripts da skill podem usar $TENOR_API_KEY direto. Para variáveis fora de skills, use a opção de configuração terminal.env_passthrough. Veja Repasse de variáveis de ambiente para os detalhes.

Configurações de skill

Skills também podem declarar configurações não secretas (caminhos, preferências) guardadas no config.yaml:

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path

As configurações ficam sob skills.config no seu config.yaml. O hermes config migrate pergunta pelas que ainda não foram definidas, e o hermes config show mostra todas. Quando uma skill carrega, os valores resolvidos são injetados no contexto para o agente já saber o que está configurado.

Veja Configurações de skill e Criar skills — Config Settings para os detalhes.

Estrutura de diretórios das skills

~/.hermes/skills/                  # Fonte única da verdade
├── mlops/                         # Diretório de categoria
│   ├── axolotl/
│   │   ├── SKILL.md               # Instruções principais (obrigatório)
│   │   ├── references/            # Documentação adicional
│   │   ├── templates/             # Formatos de saída
│   │   ├── scripts/               # Scripts auxiliares chamáveis pela skill
│   │   ├── examples/              # Exemplos de saída referenciados
│   │   └── assets/                # Arquivos complementares
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                # Skill criada pelo agente
│       ├── SKILL.md
│       └── references/
├── .hub/                          # Estado do Skills Hub
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest              # Rastreia as skills embutidas semeadas

Instalações de terceiros por URL e por GitHub incluem o SKILL.md mais os arquivos locais exatos que ele referencia em references/, templates/, scripts/, assets/ e examples/. Arquivos do repositório que não são referenciados não são copiados. O Hermes varre o pacote inteiro em quarentena e registra a URL de origem, o hash exato do conteúdo, a versão do scanner, os achados, o horário e se o resultado é novo ou veio do cache em skills/.hub/lock.json.

Varredura consultiva do SkillEvaluator

Além do scanner de segurança embutido (que aplica a política de instalação acima), o Hermes pode rodar as checagens de Tier 1 do NVIDIA SkillEvaluator em toda instalação pelo hub, como segunda opinião. O Tier 1 é determinístico e não precisa de chave — detecção de PII (e-mails vazados, caminhos pessoais, strings de conexão), detecção de contrabando por unicode, lint de scripts, conformidade de licença e uma varredura estática de segurança via NVIDIA SkillSpector.

A varredura é apenas consultiva: os achados são impressos com arquivo e linha antes da confirmação de instalação, e a instalação segue. Achados que parecem credenciais de verdade (chaves privadas, chaves de acesso de nuvem, tokens, strings de conexão com credencial) aparecem em vermelho, para você revisar as linhas sinalizadas antes de decidir. Achados da classe PII são informativos — o scanner de origem tem classes conhecidas de falso positivo (por exemplo, a sintaxe SSH git@github.com e e-mails de exemplo em documentação), então eles nunca bloqueiam nada.

Para habilitar, instale os binários opcionais do scanner (o segundo é o que alimenta a checagem security; sem ele, essa checagem simplesmente reporta "not run"):

uv tool install --python 3.13 \
  "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git@v0.1.0"
uv tool install "git+https://github.com/NVIDIA/SkillSpector.git@v2.9.5"

Sem o binário no PATH, a varredura é pulada em silêncio. Para desligar de vez:

skills:
  tier1_advisory: false

O botão de varredura do Browse-hub no painel devolve os mesmos dados consultivos na resposta (campo tier1), ao lado do veredito do scanner embutido.

Diretórios externos de skills

Se você mantém skills fora do Hermes — por exemplo, um diretório compartilhado ~/.agents/skills/ usado por várias ferramentas de IA — pode mandar o Hermes varrer esses diretórios também.

Acrescente external_dirs na seção skills do ~/.hermes/config.yaml:

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Os caminhos aceitam expansão de ~ e substituição de variáveis de ambiente com ${VAR}.

Como funciona

• Cria localmente, atualiza no lugar: skills novas criadas pelo agente são escritas em ~/.hermes/skills/. Skills existentes são alteradas onde estiverem, inclusive as que estão em external_dirs, quando o agente usa ações do skill_manage como patch, edit, write_file, remove_file ou delete.
• Diretório externo não é barreira de proteção contra escrita: se um diretório externo de skills é gravável pelo processo do Hermes, atualizações de skills feitas pelo agente podem mudar arquivos ali. Use permissões do sistema de arquivos ou um perfil/toolset separado se as skills externas compartilhadas precisam ficar somente leitura.
• Precedência da local: se o mesmo nome de skill existe no diretório local e num externo, a versão local vence.
• Integração completa: skills externas aparecem no índice do prompt de sistema, no skills_list, no skill_view e como comandos de barra /skill-name — sem diferença nenhuma para as locais.
• Caminhos inexistentes são pulados em silêncio: se um diretório configurado não existe, o Hermes ignora sem erro. Útil para diretórios compartilhados opcionais que podem não estar em toda máquina.

Exemplo

~/.hermes/skills/               # Local (principal, leitura e escrita)
├── devops/deploy-k8s/
│   └── SKILL.md
└── mlops/axolotl/
    └── SKILL.md

~/.agents/skills/               # Externo (compartilhado, mutável se for gravável)
├── my-custom-workflow/
│   └── SKILL.md
└── team-conventions/
    └── SKILL.md

As quatro skills aparecem no seu índice. Se você criar uma skill local chamada my-custom-workflow, ela sombreia a versão externa.

Skills locais do projeto

Repositórios podem carregar as próprias skills, ativas só em sessões iniciadas dentro daquele projeto — o mesmo padrão que outros ambientes de agente usam para configuração local de repositório. Quando você inicia o Hermes dentro de um checkout git, ele procura skills em:

<raiz-do-projeto>/.hermes/skills/    # localização nativa do Hermes
<raiz-do-projeto>/.agents/skills/    # convenção entre ferramentas (compartilhada com outras CLIs de agente)

A raiz do projeto é o diretório ancestral mais próximo que contém um .git (worktrees e submódulos contam).

Confiar num projeto

Skills são documentos de procedimento que o agente segue, então o Hermes não as carrega sozinho de repositórios clonados de qualquer lugar. Na primeira vez que você roda o Hermes num repositório com skills de projeto, o banner mostra um aviso:

◆ 3 project skill(s) found in /home/you/myproject but not loaded — run `hermes skills trust` to enable them.

Confie no repositório uma vez (de dentro dele, ou passando o caminho):

hermes skills trust             # confia no repositório atual
hermes skills trust ~/myproject # ou explicitamente
hermes skills untrust           # revoga

As raízes confiáveis ficam em skills.trusted_project_dirs no ~/.hermes/config.yaml. Defina skills.project_discovery: false para desligar o recurso por completo (sem varredura, sem avisos).

Precedência

Skills de projeto são a camada de maior precedência: projeto → local (~/.hermes/skills/) → external_dirs. Uma skill de projeto chamada deploy sobrepõe uma skill de perfil ou embutida com o mesmo nome nas sessões dentro daquele repositório — e é esse o objetivo: skills versionadas no repositório vencem no próprio território, sem mexer no seu perfil global. Skills de projeto são marcadas com [project] no índice de skills do agente, para a procedência ficar visível.

Assim como os diretórios externos, os diretórios de skills de projeto são tratados como propriedade do repositório: a manutenção autônoma de skills (o curador) nunca os altera, e skills novas criadas pelo agente vão sempre para ~/.hermes/skills/.

Quarentena na varredura

A confiança é uma decisão no nível do repositório, mas o conteúdo das skills de um repositório muda a cada git pull. Para fechar essa brecha, toda skill de projeto passa pelo mesmo scanner de segurança usado nas instalações do Skills Hub antes de entrar no índice. Uma skill cujo veredito é dangerous (diretivas de prompt injection, comandos de exfiltração de credenciais, truques de texto escondido) vai para a quarentena: não aparece no índice de skills, no skills_list nem nos comandos de barra, e se recusa a carregar pelo nome, com um erro explicativo. As varreduras ficam em cache por hash de conteúdo em ~/.hermes/cache/project_skill_scans/ (nunca dentro do seu repositório) e rodam de novo automaticamente quando o conteúdo da skill muda.

Superfícies não interativas (cron, API, ACP)

Tarefas de cron e outras superfícies não interativas herdam a sua decisão de confiança feita no modo interativo — elas nunca perguntam e nunca confiam sozinhas. A raiz do projeto é resolvida a partir do diretório de trabalho da superfície (o workdir de uma tarefa de cron, pelo mesmo mecanismo que a ferramenta de terminal usa). Uma tarefa de cron cujo workdir fica dentro de um repositório que você já confiou carrega as skills daquele projeto; uma tarefa num repositório não confiável ou ainda sem decisão não carrega nenhuma.

Pacotes de skills

Pacotes de skills (bundles) são arquivos YAML minúsculos que agrupam várias skills sob um único comando de barra. Quando você roda /<nome-do-bundle>, todas as skills listadas carregam de uma vez — útil quando uma tarefa sempre se beneficia do mesmo conjunto de skills junto.

Exemplo rápido

# Cria um bundle para trabalho de backend
hermes bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Trabalho de backend — revisão, testes, fluxo de PR"

Depois, na CLI ou em qualquer plataforma do gateway:

/backend-dev refatore o middleware de autenticação

O agente recebe as três skills carregadas numa única mensagem de usuário, com o texto depois do comando de barra anexado como instrução.

Esquema YAML

Os bundles ficam em ~/.hermes/skill-bundles/<slug>.yaml e são assim:

name: backend-dev
description: Backend feature work — review, test, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests, then implement.
  Open the PR through the standard workflow with co-author tags.

Campos:

• name (opcional — por padrão, o nome do arquivo sem extensão) — o nome de exibição do bundle. É normalizado para um slug com hifens no comando de barra (Backend Dev → /backend-dev).
• description (opcional) — texto curto mostrado em /bundles e em hermes bundles list.
• skills (obrigatório, lista não vazia) — nomes de skills ou caminhos relativos ao seu diretório de skills. Use o mesmo identificador que você passaria para /<nome-da-skill>.
• instruction (opcional) — orientação extra colocada antes do conteúdo das skills carregadas. Boa para codificar "como sempre usamos essas juntas".

Gerenciar bundles

# Lista todos os bundles instalados
hermes bundles list

# Inspeciona um bundle
hermes bundles show backend-dev

# Cria um bundle interativamente (omita as opções --skill para digitá-las uma por linha)
hermes bundles create research

# Sobrescreve um bundle existente
hermes bundles create backend-dev --skill ... --force

# Apaga um bundle
hermes bundles delete backend-dev

# Varre de novo ~/.hermes/skill-bundles/ e informa as mudanças
hermes bundles reload

De dentro de uma sessão de chat, /bundles lista todos os bundles instalados e suas skills.

Comportamento

• Bundles têm precedência sobre skills individuais quando os slugs colidem. Se você nomeia um bundle research e também tem uma skill chamada research, /research invoca o bundle. Isso é intencional — você optou pelo bundle ao nomeá-lo assim.
• Skills faltando são puladas, não são erro fatal. Se um bundle lista skill-foo e você não a instalou, o bundle ainda carrega as que resolvem, e o agente recebe uma nota listando o que foi pulado.
• Bundles funcionam em toda superfície — CLI interativa, TUI, chat do painel e toda plataforma do gateway (Telegram, Discord, Slack, …) — porque o despacho é centralizado no mesmo lugar dos comandos de skill individuais.
• Bundles não invalidam o cache do prompt. Eles geram uma mensagem de usuário nova no momento da invocação, do mesmo jeito que /<nome-da-skill> — sem mexer no prompt de sistema.

Quando o bundle ganha de instalar cada skill na mão

Use um bundle quando:

• Você sempre junta as mesmas skills numa tarefa recorrente (/backend-dev, /release-prep, /incident-response).
• Você quer um modelo mental mais curto do que digitar várias invocações /skill em sequência.
• Você quer distribuir um "perfil de tarefa" para o time, versionando o YAML do bundle num repositório de dotfiles compartilhado e criando um link simbólico dele em ~/.hermes/skill-bundles/.

Um bundle é só um apelido em YAML — ele não instala skills por você. As skills precisam já estar presentes (em ~/.hermes/skills/ ou num diretório externo de skills). Caso contrário, a invocação do bundle simplesmente pula as que faltam.

Skills gerenciadas pelo agente (ferramenta skill_manage)

O agente pode criar, atualizar e apagar as próprias skills com a ferramenta skill_manage. Essa é a memória procedural dele — quando ele descobre um fluxo não trivial, salva a abordagem como skill para reusar depois.

Skills e memória trabalham juntas no laço de autoaperfeiçoamento: a memória guarda fatos pequenos e duráveis que devem estar sempre no contexto, enquanto as skills guardam procedimentos longos que só devem carregar quando forem relevantes. A revisão em segundo plano pode sugerir ou preparar mudanças de skill depois de uma sessão, mas a trava de aprovação de escrita abaixo permite exigir revisão humana antes de as mudanças entrarem.

Quando o agente cria skills

O prompt de sistema pede que o agente registre um fluxo não trivial com skill_manage para reuso futuro. Na prática, isso cobre:

• Quando ele resolveu um fluxo de vários passos que vale repetir
• Quando ele bateu em erros ou becos sem saída e achou o caminho que funciona
• Quando o usuário corrigiu a abordagem dele

Ações

Ação	Serve para	Parâmetros principais
create	Skill nova do zero	name, content (SKILL.md completo), category opcional
patch	Correções pontuais (preferido)	name, old_string, new_string
edit	Reescritas estruturais grandes	name, content (substitui o SKILL.md inteiro)
delete	Remover uma skill por completo	name
write_file	Adicionar/atualizar arquivos de apoio	name, file_path, file_content
remove_file	Remover um arquivo de apoio	name, file_path

dica

A ação patch é a preferida para atualizações — ela gasta menos tokens que edit, porque só o texto alterado aparece na chamada de ferramenta.

Travar as escritas de skills do agente (skills.write_approval)

Por padrão o agente escreve skills à vontade — inclusive a partir da revisão de autoaperfeiçoamento em segundo plano que roda depois de um turno. Se você prefere aprovar cada escrita antes (modelos pequenos que erram na avaliação do que aprenderam, ambientes seguros, ou só querer um olho no laço de autoaperfeiçoamento), ligue a trava de aprovação de escrita:

skills:
  write_approval: false     # false = escreve à vontade (padrão) | true = exige aprovação

Com write_approval: true, toda escrita do skill_manage (create / edit / patch / delete / write_file / remove_file) fica preparada em vez de aplicada — um SKILL.md é grande demais para revisar inline, então a preparação vale tanto para escritas vindas de um turno em primeiro plano quanto da revisão em segundo plano. As escritas preparadas sobrevivem a reinícios em ~/.hermes/pending/skills/ e são revisadas pelo mesmo fluxo de aprovar/negar dos comandos perigosos:

/skills pending             # lista escritas de skill preparadas + um resumo de uma linha de cada
/skills diff <id>           # diff unificado completo (melhor visto na CLI ou no painel)
/skills approve <id>        # aplica (ou 'all')
/skills reject <id>         # descarta (ou 'all')
/skills approval on         # liga a trava (ou 'off') e persiste a escolha

A superfície de revisão funciona na CLI interativa e nas plataformas de mensagem (a saída do diff é truncada para caber nas bolhas de chat — leia o diff completo na CLI ou no arquivo JSON de pendências). As escritas de memória têm a mesma trava sob memory.write_approval — veja Controlar as escritas de memória.

A configuração separada skills.guard_agent_created é um scanner de conteúdo (heurísticas de padrões perigosos), não uma trava de aprovação — as duas são independentes. Veja Guarda nas escritas de skills criadas pelo agente.

Skills Hub

Navegue, busque, instale e gerencie skills de registros online, do skills.sh, de endpoints well-known diretos e das skills opcionais oficiais.

Comandos comuns

hermes skills browse                              # Navega por todas as skills do hub (oficiais primeiro)
hermes skills browse --source official            # Navega só pelas skills opcionais oficiais
hermes skills search kubernetes                   # Busca em todas as fontes
hermes skills search react --source skills-sh     # Busca no diretório skills.sh
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect openai/skills/k8s           # Pré-visualiza antes de instalar
hermes skills install openai/skills/k8s           # Instala com varredura de segurança
hermes skills install official/security/1password
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills install https://sharethis.chat/SKILL.md              # URL direta (+ arquivos de apoio referenciados)
hermes skills install https://example.com/SKILL.md --name my-skill # Define o nome quando o frontmatter não tem
hermes skills list --source hub                   # Lista skills instaladas pelo hub
hermes skills check                               # Verifica se há atualizações upstream das skills do hub
hermes skills update                              # Reinstala skills do hub quando há mudança upstream
hermes skills audit                               # Revarre todas as skills do hub em busca de problemas
hermes skills uninstall k8s                       # Remove uma skill do hub
hermes skills reset google-workspace              # Destrava uma skill embutida do estado "modificada pelo usuário" (veja abaixo)
hermes skills reset google-workspace --restore    # Também restaura a versão embutida, apagando suas edições locais
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json          # Exporta a configuração de skills
hermes skills tap add myorg/skills-repo           # Adiciona uma fonte GitHub própria

Fontes de hub suportadas

Fonte	Exemplo	Observações
official	official/security/1password	Skills opcionais que vêm com o Hermes.
skills-sh	skills-sh/vercel-labs/agent-skills/vercel-react-best-practices	Pesquisável com hermes skills search <query> --source skills-sh. O Hermes resolve skills em formato de alias quando o slug do skills.sh difere da pasta do repositório.
well-known	well-known:https://mintlify.com/docs/.well-known/skills/mintlify	Skills servidas direto de /.well-known/skills/index.json num site. Busque usando a URL do site ou da documentação.
url	https://sharethis.chat/SKILL.md	URL HTTP(S) direta para o SKILL.md mais os arquivos de apoio explicitamente referenciados. Resolução de nome: frontmatter → slug da URL → pergunta interativa → opção --name.
github	openai/skills/k8s	Instalações diretas de repositório/caminho do GitHub e taps próprios.
clawhub, lobehub, browse-sh	Identificadores específicos da fonte	Integrações comunitárias ou de marketplace.

Hubs e registros integrados

Hoje o Hermes integra com estes ecossistemas de skills e fontes de descoberta:

1. Skills opcionais oficiais (official)

São mantidas no próprio repositório do Hermes e instalam com confiança embutida.

• Catálogo: Catálogo oficial de skills opcionais
• Origem no repositório: optional-skills/
• Exemplo:

hermes skills browse --source official
hermes skills install official/security/1password

2. skills.sh (skills-sh)

É o diretório público de skills da Vercel. O Hermes pode buscar nele direto, inspecionar páginas de detalhe de skill, resolver slugs em formato de alias e instalar a partir do repositório de origem.

• Diretório: skills.sh
• Repositório da CLI/ferramentas: vercel-labs/skills
• Repositório oficial de skills da Vercel: vercel-labs/agent-skills
• Exemplo:

hermes skills search react --source skills-sh
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

3. Endpoints well-known de skills (well-known)

É descoberta por URL a partir de sites que publicam /.well-known/skills/index.json. Não é um hub central único — é uma convenção de descoberta na web.

• Exemplo de endpoint ativo: índice de skills da documentação da Mintlify
• Implementação de servidor de referência: vercel-labs/skills-handler
• Exemplo:

hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

4. Skills direto do GitHub (github)

O Hermes instala direto de repositórios do GitHub e de taps baseados no GitHub. Útil quando você já sabe o repositório/caminho ou quer adicionar seu próprio repositório como fonte.

Taps padrão (navegáveis sem nenhuma configuração):

• openai/skills

• anthropics/skills

• huggingface/skills

• NVIDIA/skills — skills verificadas pela NVIDIA (skill.oms.sig assinado + skill-card.md de governança)

• garrytan/gstack

• Exemplo:

hermes skills install openai/skills/k8s
hermes skills tap add myorg/skills-repo

Agrupamento por categoria (skills.sh.json). Um tap do GitHub pode trazer um arquivo skills.sh.json na raiz do repositório, seguindo o esquema do skills.sh. Os groupings dele (cada um com um title e uma lista de nomes de skill) são lidos na hora de indexar e viram os rótulos de categoria mostrados na página do Skills Hub — no lugar de um palpite derivado das tags. Isso é genérico: qualquer tap que traga o arquivo ganha categorização de verdade, sem nenhuma mudança do lado do Hermes.

{
  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
  "groupings": [
    { "title": "Inference AI", "skills": ["dynamo-recipe-runner", "dynamo-router-sla"] },
    { "title": "Decision Optimization", "skills": ["cuopt-developer", "cuopt-install"] }
  ]
}

5. ClawHub (clawhub)

Um marketplace de skills de terceiros integrado como fonte comunitária.

• Site: clawhub.ai
• Id da fonte no Hermes: clawhub

6. LobeHub (lobehub)

O Hermes busca e converte entradas de agente do catálogo público do LobeHub em skills instaláveis.

• Site: LobeHub
• Índice público de agentes: chat-agents.lobehub.com
• Repositório por trás: lobehub/lobe-chat-agents
• Id da fonte no Hermes: lobehub

7. browse.sh (browse-sh)

O Hermes integra com o browse.sh, o catálogo da Browserbase com mais de 200 arquivos SKILL.md de automação de navegador específicos por site (Airbnb, Amazon, arXiv, 12306.cn, Etsy, Xero e muitos outros). Cada skill descreve como conduzir um site de ponta a ponta e serve para uso com as ferramentas de navegador do Hermes e com qualquer skill de automação de navegador que você já tenha instalada.

• Site: browse.sh
• API do catálogo: https://browse.sh/api/skills
• Id da fonte no Hermes: browse-sh
• Nível de confiança: community

hermes skills search airbnb --source browse-sh
hermes skills inspect browse-sh/airbnb.com/search-listings-ddgioa
hermes skills install browse-sh/airbnb.com/search-listings-ddgioa

Os identificadores têm a forma browse-sh/<hostname>/<task-id> e batem com o slug exposto pelo catálogo do browse.sh. O conteúdo é resolvido pelo endpoint de detalhe de cada skill (/api/skills/<slug> → skillMdUrl), não pelo sourceUrl do GitHub que o catálogo traz.

8. URL direta (url)

Instale o SKILL.md direto de qualquer URL HTTP(S) — útil quando o autor hospeda a skill no próprio site (sem listagem em hub, sem caminho do GitHub para digitar). O Hermes também busca os arquivos explicitamente referenciados em references/, templates/, scripts/, assets/ e examples/, depois varre e instala o pacote completo.

• Id da fonte no Hermes: url
• Identificador: a própria URL (sem prefixo)
• Escopo: o SKILL.md mais os arquivos de apoio exatos referenciados nos diretórios permitidos. O Hermes não enumera nem copia arquivos não relacionados do host.

hermes skills install https://sharethis.chat/SKILL.md
hermes skills install https://example.com/my-skill/SKILL.md --category productivity

Resolução do nome, nesta ordem:

1. Campo name: no frontmatter YAML do SKILL.md (recomendado — toda skill bem formada tem um).
2. Nome do diretório pai no caminho da URL (por exemplo, .../my-skill/SKILL.md → my-skill, ou .../my-skill.md → my-skill), quando ele é um identificador válido (^[a-z][a-z0-9_-]*$).
3. Pergunta interativa num terminal com TTY.
4. Em superfícies não interativas (o comando de barra /skills install dentro da TUI, plataformas do gateway, scripts), um erro limpo apontando para a opção --name.

# O frontmatter não tem nome e o slug da URL não ajuda — forneça um:
hermes skills install https://example.com/SKILL.md --name sharethis-chat

# Ou dentro de uma sessão de chat:
/skills install https://example.com/SKILL.md --name sharethis-chat

O nível de confiança é sempre community — roda a mesma varredura de segurança de qualquer outra fonte. A URL é guardada como identificador de instalação, então o hermes skills update rebusca da mesma URL automaticamente quando você quiser atualizar.

Varredura de segurança e --force

Toda skill instalada pelo hub passa por um scanner de segurança que procura exfiltração de dados, prompt injection, comandos destrutivos, sinais de ataque à cadeia de suprimentos e outras ameaças.

O hermes skills inspect ... agora também mostra metadados upstream quando eles existem:

• URL do repositório
• URL da página de detalhe no skills.sh
• comando de instalação
• instalações por semana
• estados da auditoria de segurança upstream
• URLs de índice/endpoint well-known

Use --force quando você já revisou uma skill de terceiros e quer passar por cima de um bloqueio de política não perigoso:

hermes skills install skills-sh/anthropics/skills/pdf --force

Comportamentos importantes:

• --force consegue passar por cima de bloqueios de política em achados do tipo cuidado/aviso.
• --force não passa por cima de um veredito dangerous.
• Skills opcionais oficiais (official/...) são tratadas com confiança embutida e não mostram o painel de aviso de terceiros.

Níveis de confiança

Nível	Fonte	Política
builtin	Vem com o Hermes	Sempre confiável
official	optional-skills/ no repositório	Confiança embutida, sem aviso de terceiros
trusted	Registros/repositórios confiáveis como openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills	Política mais permissiva que a das fontes comunitárias
community	Todo o resto (skills.sh, endpoints well-known, repositórios GitHub próprios, a maioria dos marketplaces)	Achados não perigosos podem ser ignorados com --force; vereditos dangerous continuam bloqueados

Ciclo de atualização

O hub agora guarda procedência suficiente para reconferir as cópias upstream das skills instaladas:

hermes skills check          # Informa quais skills instaladas do hub mudaram upstream
hermes skills update         # Reinstala só as skills com atualização disponível
hermes skills update react   # Atualiza uma skill específica instalada do hub
hermes skills update react --force   # Sobrescreve uma skill que você editou localmente

Isso usa o identificador de origem guardado mais o hash do conteúdo do pacote upstream atual para detectar divergência.

Skills que você editou localmente (o conteúdo em disco não bate mais com o hash registrado na instalação) são puladas pelo hermes skills update, para que suas mudanças nunca sejam sobrescritas em silêncio. Passe --force para substituí-las pela versão upstream assim mesmo.

Limites de taxa do GitHub

As operações do hub de skills usam a API do GitHub, que tem um limite de 60 requisições por hora para usuários não autenticados. Se você vir erros de limite de taxa durante instalação ou busca, defina GITHUB_TOKEN no seu arquivo .env para subir o limite para 5.000 requisições por hora. A mensagem de erro inclui uma dica prática quando isso acontece.

Publicar um tap próprio de skills

Se você quer compartilhar um conjunto curado de skills — para o seu time, a sua organização ou para todo mundo — pode publicá-lo como um tap: um repositório do GitHub que outros usuários do Hermes adicionam com hermes skills tap add <owner/repo>. Sem servidor, sem cadastro em registro, sem pipeline de release. Só um diretório de arquivos SKILL.md.

Layout do repositório

Um tap é qualquer repositório do GitHub (público ou privado — o privado precisa de GITHUB_TOKEN) organizado assim:

owner/repo
├── skills/                       # caminho padrão; configurável por tap
│   ├── my-workflow/
│   │   ├── SKILL.md              # obrigatório
│   │   ├── references/           # arquivos de apoio opcionais
│   │   ├── templates/
│   │   └── scripts/
│   ├── another-skill/
│   │   └── SKILL.md
│   └── third-skill/
│       └── SKILL.md
└── README.md                     # opcional, mas ajuda

Regras:

• Cada skill fica no próprio diretório, dentro do caminho raiz do tap (por padrão, skills/).
• O nome do diretório vira o slug de instalação da skill.
• Cada diretório de skill precisa ter um SKILL.md com o frontmatter padrão do SKILL.md (name, description, mais os opcionais metadata.hermes.tags, version, author, platforms, metadata.hermes.config).
• Subdiretórios como references/, templates/, scripts/ e assets/ são baixados junto com o SKILL.md na instalação.
• Skills cujo nome de diretório começa com . ou _ são ignoradas.

O Hermes descobre skills listando cada subdiretório do caminho do tap e checando se há SKILL.md em cada um.

Exemplo mínimo de tap

my-org/hermes-skills
└── skills/
    └── deploy-runbook/
        └── SKILL.md

skills/deploy-runbook/SKILL.md:

---
name: deploy-runbook
description: Our deployment runbook — services, rollback, Slack channels
version: 1.0.0
author: My Org Platform Team
metadata:
  hermes:
    tags: [deployment, runbook, internal]
---

# Deploy Runbook

Step 1: ...

Depois de subir isso para o GitHub, qualquer usuário do Hermes pode assinar e instalar:

hermes skills tap add my-org/hermes-skills
hermes skills search deploy
hermes skills install my-org/hermes-skills/deploy-runbook

Caminhos fora do padrão

Se as suas skills não ficam em skills/ (comum quando você acrescenta uma subárvore skills/ a um projeto que já existe), edite a entrada do tap em ~/.hermes/skills/.hub/taps.json:

{
  "taps": [
    {"repo": "my-org/platform-docs", "path": "internal/skills/"}
  ]
}

O comando hermes skills tap add cria taps novos com path: "skills/"; edite o arquivo direto se você precisa de outro caminho. O hermes skills tap list mostra o caminho efetivo de cada tap.

Instalar skills individuais direto (sem adicionar um tap)

Também dá para instalar uma única skill de qualquer repositório público do GitHub sem adicionar o repositório inteiro como tap:

hermes skills install owner/repo/skills/my-workflow

Útil quando você quer compartilhar uma skill só, sem pedir que a pessoa assine o seu registro inteiro.

Níveis de confiança dos taps

Taps novos recebem confiança community por padrão. Skills instaladas a partir deles passam pela varredura de segurança padrão e mostram o painel de aviso de terceiros na primeira instalação. Se a sua organização ou uma fonte amplamente confiável deve ter confiança maior, acrescente o repositório dela a TRUSTED_REPOS em tools/skills_hub.py (exige um PR no núcleo do Hermes).

Gerenciar taps

hermes skills tap list                                # mostra todos os taps configurados
hermes skills tap add myorg/skills-repo               # adiciona (caminho padrão: skills/)
hermes skills tap remove myorg/skills-repo            # remove

Dentro de uma sessão em execução:

/skills tap list
/skills tap add myorg/skills-repo
/skills tap remove myorg/skills-repo

Os taps ficam em ~/.hermes/skills/.hub/taps.json (criado sob demanda).

Atualização das skills embutidas (hermes skills reset)

O Hermes vem com um conjunto de skills embutidas em skills/ dentro do repositório. Na instalação e a cada hermes update, uma passada de sincronização copia essas skills para ~/.hermes/skills/ e grava um manifesto em ~/.hermes/skills/.bundled_manifest, mapeando cada nome de skill para o hash do conteúdo no momento da sincronização (o hash de origem).

Em cada sincronização, o Hermes recalcula o hash da sua cópia local e compara com o hash de origem:

• Sem alteração → é seguro puxar as mudanças upstream, copiar a nova versão embutida e gravar o novo hash de origem.
• Alterada → tratada como modificada pelo usuário e pulada para sempre, para as suas edições nunca serem atropeladas.

A proteção é boa, mas tem uma aresta. Se você edita uma skill embutida e depois quer abandonar suas mudanças e voltar à versão embutida só copiando e colando de ~/.hermes/hermes-agent/skills/, o manifesto ainda guarda o hash de origem antigo, de quando rodou a última sincronização bem-sucedida. O conteúdo recém-colado (hash embutido atual) não bate com esse hash de origem defasado, então a sincronização continua marcando a skill como modificada pelo usuário.

O hermes skills reset é a saída de emergência:

# Seguro: limpa a entrada do manifesto para esta skill. Sua cópia atual é preservada,
# mas a próxima sincronização usa ela como novo ponto de partida, então as atualizações
# futuras voltam a funcionar normalmente.
hermes skills reset google-workspace

# Restauração completa: também apaga sua cópia local e copia de novo a versão
# embutida atual. Use quando você quer a skill upstream original de volta.
hermes skills reset google-workspace --restore

# Não interativo (em scripts ou no modo TUI) — pula a confirmação do --restore.
hermes skills reset google-workspace --restore --yes

O mesmo comando funciona no chat como comando de barra:

/skills reset google-workspace
/skills reset google-workspace --restore

Perfis

Cada perfil tem o próprio .bundled_manifest sob o próprio HERMES_HOME, então hermes -p coder skills reset <name> só afeta aquele perfil.

Comandos de barra (dentro do chat)

Todos os mesmos comandos funcionam com /skills:

/skills browse
/skills search react --source skills-sh
/skills search https://mintlify.com/docs --source well-known
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills install openai/skills/skill-creator --force
/skills check
/skills update
/skills reset google-workspace
/skills list

As skills opcionais oficiais continuam usando identificadores como official/security/1password e official/migration/openclaw-migration.

---