🧩 Extensibilidade e Novos Recursos

Especificação aberta para empacotar capacidades de agentes em pastas autocontidas, portáveis entre runtimes (Hermes, Claude Code, Codex, etc).

Escreve uma vez, roda em qualquer agente compatível. Skills são a unidade de extensibilidade de mais alto nível do Hermes.

SKILL.md como manifest, frontmatter YAML, instruções em markdown, assets opcionais (scripts, templates), description acionável para o roteador escolher quando carregar.

Pasta com nome da skill contendo SKILL.md na raiz e arquivos auxiliares (scripts, templates, referências) usados pela skill em runtime.

Estrutura previsível significa instalação trivial: copia a pasta para skills/ e o agente já encontra.

~/.hermes/skills/<name>/SKILL.md, paths relativos a partir do SKILL.md, separar instruções (markdown) de execução (scripts).

Frontmatter YAML com name, description e metadata; corpo markdown com instruções operacionais para o modelo.

A description é o gatilho do roteador — uma description ruim significa skill ignorada mesmo se a lógica estiver perfeita.

Description com "Use when X" explícito, triggers naturais, instruções em imperativo direto, exemplos de uso embedados.

Conjunto de prompts representativos + respostas esperadas, rodados antes de publicar para garantir que o roteador escolhe a skill e que a saída faz sentido.

Skill sem eval é skill quebrada esperando para acontecer. Modelo muda, descrição precisa reverificar trigger rate.

Trigger rate, false positives, regressão por modelo, evals.yaml com casos positivos e negativos.

Publicar a pasta da skill em repositório git público (GitHub) e/ou registrá-la em marketplaces como agentskills.io.

Distribuição via URL torna trivial instalar (hermes skill install <repo>) e construir reputação no ecossistema.

README com screenshots/exemplos, LICENSE clara (MIT recomendado), tags semânticas, versionamento via git tags.

Hermes pode detectar padrões repetidos no histórico e sugerir consolidar como nova skill, com SKILL.md gerado automaticamente.

Reduz fricção de criação e captura conhecimento tácito que de outra forma se perderia entre sessões.

Detecção via N repetições, revisão humana antes de install, skill-creator interno, governance de skills geradas.

Model Context Protocol — padrão aberto da Anthropic para conectar agentes a fontes de dados e ferramentas externas via servers locais ou remotos.

Ecossistema MCP cresce rápido — filesystem, GitHub, Postgres, Slack, etc — e Hermes conecta a qualquer um declarativamente.

mcpServers no YAML, stdio vs SSE, scopes (user/project), env vars sensíveis, list/call/disable.

Camada que registra funções Python como tools nativas do agente via decorator @hermes.tool, com schema inferido por type hints.

Quando você quer lógica imperativa rápida (chamar API interna, ler banco) sem o overhead de empacotar um MCP server.

Type hints → schema JSON, docstring → description, hot-reload em dev, isolation por workspace.

Canal = adapter entre uma plataforma de mensagem (Telegram, Discord, WhatsApp) e o core do Hermes, implementando interface Channel.

Permite o agente "morar" onde seus usuários já estão, sem cliente próprio.

on_message / send_message, autenticação por canal, mapeamento conversation_id, normalização de attachments.

Agendador integrado que dispara skills em horários definidos por expressão cron, com retry e logs persistentes.

Transforma o agente de reativo em proativo — briefings matinais, checagens periódicas, relatórios semanais.

Expressão cron padrão (5 campos), timezone, --skill vs --command, hermes cron add/list/rm.

Fluxo de contribuição open source no repo NousResearch/hermes-agent — issues, fork, branch, testes, PR, review, merge.

Bug que você encontrou hoje é bug que todo mundo terá amanhã. Devolver para o upstream multiplica seu impacto.

CONTRIBUTING.md, conventional commits, testes obrigatórios, discussão prévia em issue para breaking changes.

Discord da Nous Research, GitHub Discussions, fóruns paralelos e marketplaces de skills/MCPs.

Suporte em tempo real, roadmap visível, oportunidade de influenciar a direção do projeto cedo.

Etiqueta open source, search antes de perguntar, MRE em bug reports, retribuir respondendo outros.

Skill orquestradora chamando outras skills via hermes.invoke() e compondo seus resultados num grafo controlado.

Reuso real (a mesma skill atende múltiplos casos), eval isolado, troca barata de implementação.

invoke() com max_depth, hermes skill graph, detecção de ciclos, profundidade controlada.

Workflow de N passos sequenciais com estado serializado entre eles, retomada automática após falha e auditoria por passo.

Skills que chamam APIs externas precisam sobreviver a crashes sem refazer trabalho já cobrado.

@hermes.step, depends_on, retries+backoff, hermes run resume, checkpoint em ~/.hermes/state/runs/.

Embedding model + ChromaDB local versionado junto da skill para consultar corpus específico (políticas, docs, FAQs).

Controle total sobre chunking, relevância e fontes — sem depender de MCP externo para conhecimento de domínio.

ingest() separado de run(), 3-8 chunks, sentence-transformers, retornar fontes na resposta.

Router interno na skill que escolhe o modelo (Haiku, Hermes 70B/405B, GPT-4o) baseado no tipo de subtarefa.

Reduz custo ~70% mantendo qualidade — classify/extract no modelo barato, redação no modelo grande.

Mapa de MODELS, função pick(), métricas de custo relativo, observabilidade por subtarefa.

Conjunto de decoradores (@idempotent, @lock) + propagação de idempotency_key para evitar duplicação em chamadas que alteram o mundo.

Modelo pode retomar/retentar silenciosamente — sem idempotência, você cobra o cliente duas vezes.

Chave estável (sha256 dos args), saga, outbox, circuit breaker, chain of responsibility.

Sintomas (description com 3+ ORs, SKILL.md de 500 linhas, run() com switch de "modos") e padrão de refactor em skills focadas.

Monólito mata trigger rate, inviabiliza eval e afasta colaboradores. Quebrar cedo custa pouco.

Regra "1 frase sem ou", description <200 chars, SKILL.md <150 linhas, eval com 5-15 casos.

Critério de decisão entre criar um MCP server completo ou apenas usar requests/tool decorator numa skill específica.

MCP tem overhead — vale quando há reuso real entre skills, portabilidade entre agentes ou consumo por times externos.

Tabela MCP vs REST vs gRPC, 5+ consumidores como threshold, 1 server = 1 domínio.

MCP = JSON-RPC 2.0 sobre stdio ou HTTP+SSE; capabilities = tools (funções), resources (URIs), prompts (templates).

Entender o handshake (initialize → list → call) é essencial para debugar quando algo não funciona.

protocolVersion, inputSchema, content[], stdio vs SSE, capability negotiation.

Framework Python que transforma funções com type hints em tools MCP via @mcp.tool().

Menor cerimônia para chegar a server funcional — ideal para iteração rápida e adopção pelo time.

FastMCP("name"), Literal/Optional viram enum/optional, docstring vira description, mcp.run(transport=...).

SDK oficial @modelcontextprotocol/sdk com Server, handlers de schema e validação via Zod.

Quando o time já vive em JS/TS ou quando você precisa rodar em serverless edge (Workers, Vercel).

Server + StdioServerTransport, setRequestHandler, ListToolsRequestSchema, zodToJsonSchema.

Três caminhos de auth: service account (estático), JWT por usuário (auditável), OAuth (3rd party em nome do user).

Server interno expõe dados sensíveis — auth correta evita vazamento de PII e ações erradas em nome de usuários.

JWT RS256 com TTL curto, secrets via env/secret manager, ctx.session.user_email, confused deputy risk.

Empacotamento e distribuição: Docker para infra interna, pip/npm para distribuição open, SaaS para multi-tenant.

Build path bem definido leva do esqueleto ao server em produção em ~90 minutos, replicável por toda squad.

python:3.12-slim, ENTRYPOINT stdio, transport SSE em SaaS, awesome-mcp-servers para contribuição.