Criar Skills

Skills são o jeito preferido de acrescentar capacidades novas ao Hermes Agent. Elas são mais fáceis de criar do que ferramentas, não exigem mudança de código no agente e podem ser compartilhadas com a comunidade.

Deve ser uma skill ou uma ferramenta?

Faça uma skill quando:

• A capacidade pode ser expressa como instruções + comandos de shell + ferramentas existentes
• Ela embrulha uma CLI ou API externa que o agente consegue chamar pelo terminal ou pelo web_extract
• Ela não precisa de integração Python própria nem de gerenciamento de chave de API embutido no agente
• Exemplos: busca no arXiv, fluxos de git, gerenciamento de Docker, processamento de PDF, e-mail por ferramentas de CLI

Faça uma ferramenta quando:

• Ela exige integração de ponta a ponta com chaves de API, fluxos de autenticação ou configuração de vários componentes
• Ela precisa de lógica de processamento própria que tem que executar com precisão toda vez
• Ela lida com dados binários, streaming ou eventos em tempo real
• Exemplos: automação de navegador, TTS, análise de visão

Estrutura de diretórios de uma skill

As skills embutidas ficam em skills/, organizadas por categoria. As skills opcionais oficiais usam a mesma estrutura em optional-skills/:

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # Obrigatório: instruções principais
│       └── scripts/              # Opcional: scripts auxiliares
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

Formato do SKILL.md

---
name: minha-skill
description: Descrição curta (aparece nos resultados de busca de skills)
version: 1.0.0
author: Seu Nome
license: MIT
platforms: [macos, linux]          # Opcional — restringe a sistemas operacionais específicos
                                   #   Válidos: macos, linux, windows
                                   #   Omita para carregar em todas as plataformas (padrão)
metadata:
  hermes:
    tags: [Categoria, Subcategoria, PalavrasChave]
    related_skills: [nome-de-outra-skill]
    requires_toolsets: [web]            # Opcional — só aparece quando estes conjuntos estão ativos
    requires_tools: [web_search]        # Opcional — só aparece quando estas ferramentas existem
    fallback_for_toolsets: [browser]    # Opcional — esconde quando estes conjuntos estão ativos
    fallback_for_tools: [browser_navigate]  # Opcional — esconde quando estas ferramentas existem
    config:                              # Opcional — ajustes de config.yaml de que a skill precisa
      - key: my.setting
        description: "O que este ajuste controla"
        default: "padrao-sensato"
        prompt: "Texto exibido na configuração"
    blueprint:                              # Opcional — marca esta skill como automação executável
      schedule: "0 9 * * *"              #   expressão cron / "every 2h" / timestamp ISO
      deliver: origin                    #   opcional (padrão: origin)
      prompt: "Instrução de tarefa para cada execução"  # opcional
      no_agent: false                    # opcional
required_environment_variables:          # Opcional — variáveis de ambiente de que a skill precisa
  - name: MY_API_KEY
    prompt: "Digite a sua chave de API"
    help: "Consiga uma em https://example.com"
    required_for: "acesso à API"
---

# Título da Skill

Introdução curta.

## Quando usar
Condições de disparo — quando o agente deve carregar esta skill?

## Referência rápida
Tabela dos comandos ou chamadas de API mais comuns.

## Procedimento
Instruções passo a passo que o agente segue.

## Armadilhas
Modos de falha conhecidos e como lidar com eles.

## Verificação
Como o agente confirma que deu certo.

Skills específicas de plataforma

As skills podem se restringir a sistemas operacionais específicos pelo campo platforms:

platforms: [macos]            # só macOS (por exemplo, iMessage, Lembretes da Apple)
platforms: [macos, linux]     # macOS e Linux
platforms: [windows]          # só Windows

Quando definido, a skill é escondida automaticamente do prompt do sistema, do skills_list() e dos comandos de barra em plataformas incompatíveis. Se o campo for omitido ou ficar vazio, a skill carrega em todas as plataformas (compatível com o comportamento antigo).

Ativação condicional de skills

As skills podem declarar dependência de ferramentas ou conjuntos de ferramentas específicos. Isso controla se a skill aparece no prompt do sistema em uma dada sessão.

metadata:
  hermes:
    requires_toolsets: [web]           # Esconde se o conjunto web NÃO estiver ativo
    requires_tools: [web_search]       # Esconde se a ferramenta web_search NÃO existir
    fallback_for_toolsets: [browser]   # Esconde se o conjunto browser ESTIVER ativo
    fallback_for_tools: [browser_navigate]  # Esconde se browser_navigate ESTIVER disponível

Campo	Comportamento
requires_toolsets	A skill fica escondida quando QUALQUER conjunto listado não está disponível
requires_tools	A skill fica escondida quando QUALQUER ferramenta listada não está disponível
fallback_for_toolsets	A skill fica escondida quando QUALQUER conjunto listado está disponível
fallback_for_tools	A skill fica escondida quando QUALQUER ferramenta listada está disponível

Caso de uso do fallback_for_*: criar uma skill que serve de contorno quando uma ferramenta principal não está disponível. Por exemplo, uma skill duckduckgo-search com fallback_for_tools: [web_search] só aparece quando a ferramenta de busca na web (que exige chave de API) não está configurada.

Caso de uso do requires_*: criar uma skill que só faz sentido quando certas ferramentas estão presentes. Por exemplo, uma skill de fluxo de raspagem web com requires_toolsets: [web] não polui o prompt quando as ferramentas de web estão desligadas.

Exigências de variáveis de ambiente

As skills podem declarar as variáveis de ambiente de que precisam. Quando uma skill é carregada pelo skill_view, as variáveis exigidas por ela são registradas automaticamente para repasse aos ambientes de execução isolados (terminal, execute_code).

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Chave de API do Tenor"           # Exibido ao pedir ao usuário
    help: "Pegue a sua chave em https://tenor.com"  # Texto de ajuda ou URL
    required_for: "funcionalidade de busca de GIF"  # O que precisa desta variável

Cada entrada aceita:

• name (obrigatório) — o nome da variável de ambiente
• prompt (opcional) — o texto exibido ao pedir o valor ao usuário
• help (opcional) — texto de ajuda ou URL para obter o valor
• required_for (opcional) — descreve qual recurso precisa desta variável

Os usuários também podem configurar variáveis de repasse na mão, no config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

Veja skills/apple/ para exemplos de skills exclusivas do macOS.

Configuração segura no carregamento

Use required_environment_variables quando uma skill precisar de uma chave de API ou de um token. Valores faltando não escondem a skill da descoberta. Em vez disso, o Hermes pede esses valores de forma segura quando a skill é carregada na CLI local.

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Chave de API do Tenor
    help: Pegue uma chave em https://developers.google.com/tenor
    required_for: funcionalidade completa

O usuário pode pular a configuração e continuar carregando a skill. O Hermes nunca expõe o valor bruto do segredo para o modelo. Sessões de gateway e de mensageria mostram uma orientação de configuração local em vez de coletar segredos na própria conversa.

Repasse para o sandbox

Quando a sua skill é carregada, toda required_environment_variables declarada que estiver definida é repassada automaticamente para os sandboxes de execute_code e terminal — incluindo backends remotos como Docker e Modal. Os scripts da sua skill conseguem acessar $TENOR_API_KEY (ou os.environ["TENOR_API_KEY"] em Python) sem que o usuário precise configurar nada a mais. Veja Repasse de variáveis de ambiente para os detalhes.

O antigo prerequisites.env_vars continua com suporte, como apelido retrocompatível.

Ajustes de configuração (config.yaml)

As skills podem declarar ajustes não secretos, guardados no config.yaml sob o espaço de nomes skills.config. Diferente das variáveis de ambiente (que são segredos guardados no .env), os ajustes de configuração servem para caminhos, preferências e outros valores não sensíveis.

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Caminho do diretório de dados do pl### Entregue mídia como documento (`[[as_document]]`) {#deliver-media-as-documents-asdocument}
      - key: myplugin.domain
        description: Domínio em que o plugin atua
        default: ""
        prompt: Domínio do plugin (por exemplo, pesquisa em IA/ML)

Cada entrada aceita:

• key (obrigatório) — o caminho pontuado do ajuste (por exemplo, myplugin.path)
• description (obrigatório) — explica o que o ajuste controla
• default (opcional) — valor padrão caso o usuário não configure
• prompt (opcional) — texto exibido durante o hermes config migrate; na falta dele, usa o description

Como funciona:

1. Armazenamento: os valores são gravados no config.yaml em skills.config.<key>:

   skills:
     config:
       myplugin:
         path: ~/my-data

2. Descoberta: o hermes config migrate varre todas as skills habilitadas, encontra os ajustes não configurados e pergunta ao usuário. Os ajustes também aparecem no hermes config show, em "Skill Settings".

3. Injeção em tempo de execução: quando uma skill carrega, os valores de configuração dela são resolvidos e anexados à mensagem da skill:

   [Skill config (from ~/.hermes/config.yaml):
     myplugin.path = /home/user/my-data
   ]

   O agente vê os valores configurados sem precisar ler o config.yaml por conta própria.

4. Configuração manual: os usuários também podem definir valores direto:

   hermes config set skills.config.myplugin.path ~/my-data

Quando usar cada um

Use required_environment_variables para chaves de API, tokens e outros segredos (guardados em ~/.hermes/.env e nunca mostrados ao modelo). Use config para caminhos, preferências e ajustes não sensíveis (guardados no config.yaml, visíveis no config show).

Exigências de arquivos de credencial (tokens de OAuth etc.)

Skills que usam OAuth ou credenciais em arquivo podem declarar os arquivos que precisam ser montados em sandboxes remotos. Isso vale para credenciais guardadas como arquivos (não como variáveis de ambiente) — em geral, arquivos de token de OAuth produzidos por um script de configuração.

required_credential_files:
  - path: google_token.json
    description: Token OAuth2 do Google (criado pelo script de configuração)
  - path: google_client_secret.json
    description: Credenciais de cliente OAuth2 do Google

Cada entrada aceita:

• path (obrigatório) — caminho do arquivo, relativo a ~/.hermes/
• description (opcional) — explica o que é o arquivo e como ele é criado

No carregamento, o Hermes confere se esses arquivos existem. Arquivos faltando disparam o setup_needed. Arquivos existentes são automaticamente:

• Montados em contêineres Docker como bind mounts somente leitura
• Sincronizados em sandboxes do Modal (na criação e antes de cada comando, para que o OAuth no meio da sessão funcione)
• Disponíveis no backend local sem nenhum tratamento especial

Quando usar cada um

Use required_environment_variables para chaves de API e tokens simples (strings guardadas em ~/.hermes/.env). Use required_credential_files para arquivos de token de OAuth, segredos de cliente, JSON de conta de serviço, certificados ou qualquer credencial que seja um arquivo em disco.

Veja o skills/productivity/google-workspace/SKILL.md para um exemplo completo usando os dois.

Diretrizes para skills

Sem dependências externas

Prefira a biblioteca padrão do Python, o curl e as ferramentas que o Hermes já tem (web_extract, terminal, read_file). Se uma dependência for necessária, documente os passos de instalação dentro da skill.

Revelação progressiva

Coloque o fluxo mais comum primeiro. Casos de borda e uso avançado vão para o fim. Isso mantém o consumo de tokens baixo nas tarefas comuns.

Inclua scripts auxiliares

Para análise de XML/JSON ou lógica complexa, inclua scripts auxiliares em scripts/ — não espere que o LLM escreva parsers inline toda vez.

Entregue mídia como documento ([[as_document]])

Se a sua skill produz uma captura de tela em alta resolução, um gráfico ou qualquer imagem em que a compressão com perdas da pré-visualização atrapalharia — emita a diretiva literal [[as_document]] em algum ponto da resposta (em geral, na última linha). O gateway remove a diretiva e entrega cada caminho de mídia extraído daquela resposta como anexo baixável, em vez de um balão de imagem embutido. Veja Saída de skill e entrega de mídia para a semântica completa.

Referenciar scripts embutidos a partir do SKILL.md

Quando uma skill é carregada, a mensagem de ativação expõe o diretório absoluto da skill como [Skill directory: /abs/path] e também substitui dois tokens de template em qualquer ponto do corpo do SKILL.md:

Token	Substituído por
${HERMES_SKILL_DIR}	Caminho absoluto do diretório da skill
${HERMES_SESSION_ID}	O id da sessão ativa (fica como está se não houver sessão)

Então um SKILL.md pode mandar o agente rodar um script embutido direto, assim:

Para analisar a entrada, rode:

    node ${HERMES_SKILL_DIR}/scripts/analyse.js <entrada>

O agente vê o caminho absoluto já substituído e chama a ferramenta terminal com um comando pronto para rodar — sem conta de caminho, sem uma ida e volta extra ao skill_view. Desligue a substituição globalmente com skills.template_vars: false no config.yaml.

Trechos de shell inline (opcional)

As skills também podem embutir trechos de shell inline, escritos como !`cmd` no corpo do SKILL.md. Quando isso está habilitado, a saída padrão de cada trecho é inserida na mensagem antes de o agente ler, de modo que as skills conseguem injetar contexto dinâmico:

Data atual: !`date -u +%Y-%m-%d`
Branch do git: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

Isso vem desligado por padrão — qualquer trecho em um SKILL.md roda no host sem aprovação, então só habilite para fontes de skill em que você confia:

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # segundos por trecho

Os trechos rodam com o diretório da skill como diretório de trabalho, e a saída é limitada a 4000 caracteres. Falhas (timeouts, saídas com código diferente de zero) aparecem como um marcador curto [inline-shell error: ...] em vez de quebrar a skill inteira.

Teste

Rode a skill e confirme que o agente segue as instruções direito:

hermes chat --toolsets skills -q "Use a skill X para fazer Y"

Onde a skill deve morar?

As skills embutidas (em skills/) vêm com toda instalação do Hermes. Elas devem ser amplamente úteis para a maioria dos usuários:

• Manipulação de documentos, pesquisa na web, fluxos comuns de desenvolvimento, administração de sistemas
• Usadas com frequência por gente de perfis variados

Se a sua skill é oficial e útil, mas não é necessária universalmente (por exemplo, integração com um serviço pago, ou uma dependência pesada), coloque em optional-skills/ — ela vem com o repositório, dá para descobrir com hermes skills browse (marcada como "official") e instala com confiança embutida.

Se a sua skill é especializada, contribuída pela comunidade ou de nicho, o lugar dela é um Skills Hub — publique em um registro e compartilhe com hermes skills install.

Blueprints: skills que também são automações

Um blueprint é uma skill comum que, além do resto, declara um agendamento no frontmatter. Adicione um bloco metadata.hermes.blueprint e a skill vira uma automação executável e compartilhável:

metadata:
  hermes:
    tags: [blueprint, email]
    blueprint:
      schedule: "0 8 * * *"     # a presença de `blueprint:` marca como executável
      deliver: telegram          # opcional (padrão: origin)
      prompt: "Resuma os meus e-mails não lidos e a agenda de hoje."  # opcional
      no_agent: false            # opcional

Como um blueprint é uma skill, ele passa por todo o pipeline de skills sem mudança nenhuma — busca, inspeção, instalação, varredura de segurança, procedência, taps, o índice centralizado e o hermes skills publish para compartilhar. Nada de novo para aprender.

Instalar um blueprint. Quando você instala uma skill que carrega um bloco blueprint:, o Hermes a registra como tarefa de cron sugerida em vez de agendá-la. O agendamento é opcional — instalar nunca cria uma tarefa recorrente às escondidas. Você revisa e aceita pelo /suggestions:

hermes skills install owner/morning-brief
# → Blueprint: 'morning-brief' é uma automação (agenda 0 8 * * *).
#   Adicionada às suas sugestões — rode /suggestions para agendar ou descartar.

# depois, dentro de uma sessão:
/suggestions             # lista as sugestões pendentes, numeradas
/suggestions accept 1    # cria a tarefa de cron
/suggestions dismiss 1   # nunca mais oferecer

Os blueprints são uma fonte da superfície unificada de Tarefas de Cron Sugeridas — o mesmo lugar onde aparecem as automações iniciais curadas e (mais adiante) as sugestões por padrão de uso e por integração. Veja Tarefas de cron sugeridas mais abaixo.

Compartilhar uma automação que você criou. Um blueprint carregado por uma tarefa de cron (hermes cron create --skill <nome> ...) pode ser exportado de volta para um SKILL.md e publicado como qualquer outra skill, de modo que uma automação que você ajustou para si vira uma instalação de um comando só para outra pessoa.

A camada de blueprint não acrescenta tipo de objeto, armazenamento nem transporte novo — o blueprint é uma skill, o agendamento é uma tarefa de cron, e o compartilhamento é o caminho de publicação/tap/índice que já existe.

Tarefas de cron sugeridas

O Hermes consegue propor automações e deixar você aceitá-las com um toque, em vez de obrigar você a montar tarefas de cron na mão. Toda proposta passa por uma única superfície — o comando /suggestions — não importa de onde ela venha:

Fonte	Disparo
catalog	Automações iniciais curadas (/suggestions catalog) — briefing diário, monitor de e-mails importantes, revisão semanal, lembrete de início de expediente
blueprint	Você instalou uma skill que carrega um bloco blueprint:
usage	A revisão em segundo plano notou um pedido recorrente que um agendamento atenderia
integration	Você conectou uma conta (Gmail, GitHub, ...) e as automações óbvias são oferecidas

/suggestions             # lista as pendentes
/suggestions accept N    # agenda a sugestão N (cria a tarefa de cron)
/suggestions dismiss N   # descarta — fica travado, nunca mais é oferecido
/suggestions catalog     # adiciona as automações iniciais curadas

Aceitar uma sugestão chama o mesmo cron.jobs.create_job que a ferramenta cronjob usa — não existe um segundo motor de tarefas. As sugestões nunca criam tarefas sozinhas; a aceitação é sempre explícita. Sugestões descartadas travam por uma chave estável, então a mesma proposta nunca é oferecida de novo. A lista de pendentes tem teto, para que nunca vire um paredão de cobrança.

A entrada de catálogo do monitor de e-mails importantes é o padrão consultar→classificar→expor: ela pontua os itens da caixa de entrada com um modelo classificador barato (auxiliary.monitor no config.yaml) e entrega só os que passam de um limiar de urgência, ficando calada no resto do tempo.

Publicar skills

Para o Skills Hub

hermes skills publish skills/minha-skill --to github --repo owner/repo

Para um repositório próprio

Adicione o seu repositório como tap:

hermes skills tap add owner/repo

Aí os usuários podem buscar e instalar a partir do seu repositório.

Varredura de segurança

Toda skill instalada pelo hub passa por um scanner de segurança que procura:

• Padrões de exfiltração de dados
• Tentativas de injeção de prompt
• Comandos destrutivos
• Injeção de shell

Níveis de confiança:

• builtin — vem com o Hermes (sempre confiável)
• official — vem de optional-skills/ no repositório (confiança embutida, sem aviso de terceiro)
• trusted — vem de openai/skills, anthropics/skills, huggingface/skills
• community — achados não perigosos podem ser sobrepostos com --force; veredictos dangerous continuam bloqueados

Hoje o Hermes consegue consumir skills de terceiros a partir de vários modelos de descoberta externos:

• identificadores diretos do GitHub (por exemplo, openai/skills/k8s)
• identificadores do skills.sh (por exemplo, skills-sh/vercel-labs/json-render/json-render-react)
• endpoints well-known servidos em /.well-known/skills/index.json

Se você quer que as suas skills sejam descobertas sem um instalador específico do GitHub, considere servi-las por um endpoint well-known, além de publicá-las em um repositório ou marketplace.

---