| name | hermes-developer |
| description | Develop and extend Hermes Agent — architecture, contribution, tools/plugins/skills/providers, and keep this skill current with official docs. |
| version | 1.1.0 |
| author | Mahdi Hedhli |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["hermes","developer","architecture","contributing","plugins","tools","skills","providers"],"homepage":"https://github.com/MahdiHedhli/skills/tree/main/skills/hermes-developer","related_skills":["hermes-agent"]}} |
Hermes Developer
Authoritative skill for building on Hermes Agent itself: core contributions, plugins, tools, skills, providers, adapters, and internals.
For day-to-day configure / setup / use of an installed Hermes instance, load hermes-agent instead. Use this skill when the task is code, PRs, extension surfaces, or understanding how the platform works.
Live docs (source of truth): https://hermes-agent.nousresearch.com/docs/developer-guide/
Local checkout (preferred when present): $HERMES_HOME/hermes-agent → usually ~/.hermes/hermes-agent
In-repo AI/dev guide: $HERMES_HOME/hermes-agent/AGENTS.md
Doc sources: $HERMES_HOME/hermes-agent/website/docs/developer-guide/
If this skill and live docs disagree, docs win. Then refresh this skill (see Keep this skill current).
Sacred design constraints
Every change is reviewed through these lenses (from AGENTS.md + Architecture):
- Prompt caching is sacred. Do not mutate past context, swap toolsets, or rebuild the system prompt mid-conversation. Exception: explicit context compression. System prompt must stay byte-stable for the life of a conversation (except user actions like
/model).
- Narrow waist, wide edges. Every model tool is sent on every API call. Prefer CLI + skill → service-gated tool (
check_fn) → plugin → MCP catalog → new core tool (last resort). Product surface (platforms, providers, TUI, desktop) may grow aggressively at the edges.
- Strict message alternation. Never two assistant or two user messages in a row. Only consecutive
tool results are allowed. Never inject a synthetic user message mid-loop.
- Profile-safe paths. Never hardcode
~/.hermes. Use get_hermes_home() / display_hermes_home() from hermes_constants.
- Secrets vs config. API keys/tokens →
.env. Behavioral settings → config.yaml. No new HERMES_* env vars for non-secret config.
Footprint ladder (new capability)
- Extend existing code
- CLI command + skill (zero model-tool footprint)
- Service-gated tool with
check_fn
- Plugin (
~/.hermes/plugins/ or pip entry point)
- MCP server in catalog
- New core tool (only if fundamental and unreachable via terminal/file/MCP)
Third-party product integrations (vendor SaaS, observability backends, etc.) ship as standalone plugin repos, not under core plugins/.
Architecture map
Entry: CLI (cli.py) | Gateway (gateway/run.py) | ACP | Batch | API Server | Library
↓
AIAgent (run_agent.py)
Prompt Builder │ Provider Runtime │ Tool Dispatch (model_tools + registry)
Compression │ 3 API modes │ 70+ tools / ~28 toolsets
↓
SessionDB (SQLite+FTS5) Tool backends (terminal×6, browser×5, web×4, MCP…)
| Subsystem | Primary files | Doc |
|---|
| Agent loop | run_agent.py | agent-loop |
| Prompt assembly | agent/prompt_builder.py, agent/system_prompt.py | prompt-assembly |
| Caching / compression | agent/prompt_caching.py, agent/context_compressor.py | context-compression-and-caching |
| Providers | hermes_cli/runtime_provider.py, hermes_cli/auth.py | provider-runtime, adding-providers |
| Tools | tools/registry.py, model_tools.py, toolsets.py | tools-runtime, adding-tools |
| Sessions | hermes_state.py, gateway/session.py | session-storage |
| Gateway | gateway/run.py, gateway/platforms/* | gateway-internals |
| Plugins | hermes_cli/plugins.py, plugins/* | plugins |
| Cron | cron/jobs.py, cron/scheduler.py | cron-internals |
| ACP | acp_adapter/ | acp-internals |
| Slash commands | hermes_cli/commands.py → CLI/gateway consumers | extending-the-cli |
| Skills | skills/, optional-skills/, hub | creating-skills |
API modes: chat_completions (default OpenAI-compatible) · codex_responses · anthropic_messages
Agent-loop intercepted tools (stateful; not pure registry dispatch): todo, memory, session_search, delegate_task.
Tool discovery: any tools/*.py with top-level registry.register() is auto-imported. Handlers must return JSON strings; errors as {"error": "..."} never raised.
Prompt tiers (cached): stable (identity, tools, skills, env) → context (project files) → volatile (memory/profile/timestamp). Ephemeral per-call overlays are separate and must not break the stable prefix.
Task routing — what to load / where to edit
| Goal | Path | Start here |
|---|
| Custom tool without core PR | Plugin | docs: plugins; ~/.hermes/plugins/<name>/ |
| Built-in core tool | Core PR | tools/your_tool.py + toolsets.py |
| Procedural capability | Skill | SKILL.md under skills/ or hub |
| Inference backend (simple API key) | Model-provider plugin | plugins/model-providers/ |
| First-class built-in provider | Core PR | adding-providers checklist |
| Messaging channel | Platform adapter | gateway/platforms/, adding-platform-adapters |
| Memory / context engine / secrets / image / video / web / browser backend | Typed plugin | matching *-provider-plugin / context-engine-plugin doc |
| External tools as-is | MCP | mcp_servers in config.yaml |
| Slash command | Registry | CommandDef in hermes_cli/commands.py + handlers |
| Cron automation | Skill blueprint or cron API | creating-skills blueprints; cron-internals |
| Programmatic embed | Library | programmatic-integration |
Full interface map lives in references and the plugins guide's "If you want to add…" table.
Contribution workflow (condensed)
Priorities: bugs → cross-platform → security → robustness → skills → tools (rare) → docs.
Dev bootstrap (preferred):
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
uv pip install -e ".[all,dev]"
scripts/run_tests.sh
PR hygiene:
- Branch:
fix/…, feat/…, docs/…, refactor/…
- Conventional commits:
fix(scope): … scopes include cli, gateway, tools, skills, agent, security
- Focused PRs; reproduce on current
main; fix the whole bug class
- Tests: behavior contracts / invariants, not change-detector snapshots of lists or counts
- E2E for resolution chains, security boundaries, remote backends — real imports + temp
HERMES_HOME
- Cross-platform: no unguarded
SIGKILL/setsid/killpg; UTF-8 explicit; pathlib
- Windows:
scripts/check-windows-footguns.py when touching I/O, processes, terminals
Verify premise before "fixing": intentional isolation (e.g. profile islands) is not a gap. Read git log -p -S for original intent.
Recipes (minimal)
Skill (preferred for most capability)
See creating-skills. Structure: SKILL.md + optional scripts/, references/, templates/, assets/.
Secrets → required_environment_variables; non-secrets → metadata.hermes.config.
Template tokens: ${HERMES_SKILL_DIR}, ${HERMES_SESSION_ID}.
Built-in tool
tools/foo_tool.py — handler + schema + check_fn + registry.register(...)- Add name to
_HERMES_CORE_TOOLS or a toolset in toolsets.py
- Optional:
OPTIONAL_ENV_VARS in hermes_cli/config.py
- Test:
hermes chat -q "…"
Plugin
mkdir -p ~/.hermes/plugins/myplugin
hermes plugins list
Hooks: pre_tool_call / post_tool_call and others per plugins guide. Do not patch core files from plugins — widen the generic surface if needed.
Slash command
CommandDef in COMMAND_REGISTRY (hermes_cli/commands.py)- Handler in
cli.py process_command
- Optional gateway handler in
gateway/run.py
Help, autocomplete, Telegram menu, Slack map all derive from the registry.
Tests
scripts/run_tests.sh
python -m pytest tests/tools/ -q -o 'addopts='
Suite auto-redirects HERMES_HOME to temps — never point tests at real home.
Keep this skill current
When Hermes docs or AGENTS.md change, or before a non-trivial platform task, refresh this skill.
Refresh procedure (mandatory when docs may have drifted)
-
Locate sources
-
Pull latest if git-managed
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent" && git fetch && git log -1 --oneline origin/main
-
Run the refresh script (writes reference snapshots + stamp)
bash ${HERMES_SKILL_DIR}/scripts/refresh_from_docs.sh
-
Diff & patch
- Read
references/LAST_REFRESH.md and changed reference files
- Patch this
SKILL.md if ladders, file maps, or recipes drifted
- Use
skill_manage(action='patch') for surgical updates; full edit only for major overhauls
-
Also update the user-facing hermes-agent skill if CLI/commands/config surfaces changed (related skill).
-
Verify
- Spot-check one architecture claim against source (
run_agent.py or docs)
- Confirm doc URLs still resolve (local files or browser)
When to refresh without being asked
- User says Hermes was updated /
hermes update ran
- A procedure in this skill fails against real code
- Contributing to Hermes and docs are older than ~2 weeks vs local
git log
- New extension surface appears (new plugin kind, new API mode, new entry point)
What NOT to bake into this skill
- Full verbatim copies of every developer page (use references + links)
- User config walkthroughs (belongs in
hermes-agent)
- Stale model lists / tool counts as hard assertions (counts change; say "see toolsets.py")
Pitfalls
| Pitfall | Fix |
|---|
| Mid-conversation tool enable | Won't apply until new session — preserves cache |
| New core tool "because it's easier" | Use skill/plugin/MCP first |
Hardcoded ~/.hermes | Breaks profiles — use get_hermes_home() |
| Handler returns dict / raises | Always json.dumps; catch and return error JSON |
| Lazy pagination on instructional tools | Models skip page 2 — load fully |
| Plugin in core tree for third-party SaaS | Standalone repo + ~/.hermes/plugins/ |
| Change-detector tests | Assert invariants, not enumeration counts |
| Synthetic user msg mid-loop | Breaks alternation / providers reject |
| Venv inside agent workspace | Agent may rm -rf it — keep venv outside tree |
Quick links
Reference files
| File | Purpose |
|---|
references/docs-index.md | Full developer-guide catalog + reading order |
references/extension-map.md | Skill vs tool vs plugin vs provider decision table |
references/architecture-snapshot.md | Condensed architecture / loop / prompt tiers |
references/contributing-checklist.md | PR / security / anti-patterns checklist |
references/workflows.md | Agent playbooks (orient, add capability, refresh) |
references/LAST_REFRESH.md | Last docs sync stamp |
references/_doc_headings.md | Drift-detection headings snapshot |
scripts/refresh_from_docs.py | Re-sync from local $HERMES_HOME/hermes-agent docs |
Related skill: hermes-agent — install, configure, CLI, gateway, day-to-day ops.
