SkillPedia Skills Encyclopedia
中文 EN

Skills 2026-09-24 02:37 UTC

hermes-optimization-guidev1.4

Version [v1.4] committed by OnlyTerp. Update Category: Feature Addition & Enhancement. Commit details: Restructure guide into 16 sequential chapters; remove legacy docs (#35). This update introduces new capabilities and module extensions.

OnlyTerp f865f8a OnlyTerp/hermes-optimization-guide

CommitRaw commit message

Restructure guide into 16 sequential chapters; remove legacy docs (#35)

* Guide v2 (WIP): rebuild against Hermes v0.21.4

Start the from-scratch rewrite of the guide, pinned to Hermes Agent
v0.21.4 (tag v2026.9.21). This checkpoint adds:

- guide/: chapters 01 (How Hermes Works), 02 (Install), 05 (Cost &
  Speed), 06 (Personality & Context Files), 15 (Troubleshooting),
  16 (Recipes) and the cheat sheet. Token figures are measured on a
  real v0.21.4 install; troubleshooting fixes cite official docs,
  merged PRs, or release notes.
- scripts/drift_guard.py: installs the pinned release and checks every
  hermes subcommand and flag, slash command, config key, env var, and
  official-docs link and anchor; also runs upstream's skill linter.
- skills/: four new operations skills (cost audit, health check,
  security review, encrypted off-machine backup) with zero upstream
  lint findings; the backup script is shellchecked and tested.
- templates/config/: lean.yaml and messaging-bot.yaml, validated
  against the v0.21.4 schema and loaded into a real install.
- New README, CHANGELOG (with a v1 part -> v2 chapter map),
  CONTRIBUTING, issue/PR templates, CI (links, anchors, YAML,
  shellcheck) and a drift-guard workflow with an upstream-release
  watcher.

Remaining chapters, templates, and removal of the v1 files follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Troubleshooting: re-source two fixes to official docs, narrow Weixin row

#53008 and #21915 were closed as not planned, so the compression-loop and
restart-loop rows now cite the official docs sections that describe the
behavior. #96134 is Weixin-specific; #95189 notes the version it was
reported on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Stop routing auxiliary.vision in templates; teach drift guard docs 'config set' keys

An explicit auxiliary.vision backend makes Hermes describe every image in
text, even when the main model can see (agent/image_routing.py,
_explicit_aux_vision_override). The lean and messaging-bot templates set
one, which silently downgraded native vision. Removed it there, in
chapter 05's examples, the README, cheat sheet, troubleshooting row, and
the cost-audit skill, and added a warning explaining when to set it.

drift_guard extract now also collects keys the official docs set with
'hermes config set <key>' (e.g. model.lmstudio_load_mode).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 05: summarizer window rule; chapter 15: what debug share really uploads

The compression trigger is clamped to the auxiliary summarizer's window
(context_compressor._apply_threshold_tokens_cap), so a small summarizer
compacts early and often. 'hermes debug share' redacts only secrets;
names, platform IDs, message text and paths go to a public paste
(hermes_cli/debug.py privacy notice).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 01: a profile is not a sandbox; drift guard knows guide-defined commands

Profiles separate state, not filesystem access (docs user-guide/profiles
'Profiles vs workspaces vs sandboxing').

The drift guard now accepts slash names the guide itself creates: bundles
made with 'hermes bundles create', example SKILL.md frontmatter names, and
quick_commands keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Remove v1 CI workflows and scripts

bootstrap-smoke, pin-watch, release-hash-check and release-publisher
existed for scripts/vps-bootstrap.sh and its installer hash pin, which no
longer matches upstream. validate_skills.py enforced an invented skill
schema; skills are now checked with upstream's own linter via
drift_guard.py lint-skills. The old first-token CLI checkers are replaced
by drift_guard.py, and score-your-setup.py by the cost-audit and
security-review skills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Remove v1 images and infographics

The SVG infographics were tied to the v1 part structure and carried v1
claims (token tax, seven security layers, release timeline). The desktop
and MoA banners were decorative (the desktop mock-up shows an old model
picker). The hero banner is kept as a 59 KB JPEG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Add chapters 03 (Models & Providers) and 04 (Local Models), local template

Chapter 03 covers choosing a main model for tool calling, provider routes
and what subscription plans actually pay for, /model scope and cache cost,
reasoning effort, auxiliary routing, the retry/fallback ladder, credential
pools, OpenRouter routing, MoA and hermes proxy. Chapter 04 covers
runtimes, the 64K rule, a tool-calling checklist, small-model tuning with
measured prefixes, and hybrid setups.

templates/config/local.yaml: a local-model profile, validated with the
real v0.21.4 loader. Tool schemas drop from 43,062 B (25 tools) to
24,642 B (15 tools), about 4,300 tokens per call.

Recipe 6 now uses 'hermes verify --save' so verify_on_stop has a recipe.
The drift guard treats provider_routing.models.<id> as open-ended.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Drift guard: check toolset names, gateway keys, correct anchor slugs

- Toolset names in 'hermes tools enable|disable', -t/--toolsets, and
  agent.disabled_toolsets / platform_toolsets YAML are checked against the
  pinned release's registry (static TOOLSETS plus tool/plugin
  registrations). mcp-<server>, no_mcp, server:tool and MCP servers the
  guide defines are accepted.
- Top-level keys the gateway reads without a DEFAULT_CONFIG entry
  (gateway/config_loader.py _TOPLEVEL_BRIDGE) count as config keys.
- Heading slugs strip markup before slugging, so underscores inside code
  spans survive (#...write_approval), matching Docusaurus.
- A crash can no longer be silent: importing Hermes swaps sys.stderr, so
  tracebacks now go to sys.__stderr__ and extract prints where it wrote.

Recipe 1 and the cheat sheet: 'hermes cron runs' filters by job ID only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Add chapters 07 (Memory) and 08 (Skills); bot template drops shared USER.md

Chapter 07 covers the frozen memory snapshot, what belongs in memory,
write approval and cleanup, measured costs, session boundaries and
retention, external providers, and privacy. Chapter 08 covers the skill
loading levels with measured costs, trust levels and the scanner,
writing and linting skills, auto_load and bundles, the curator's real
scope, and project/shared skills.

messaging-bot.yaml now sets memory.user_profile_enabled: false: USER.md
is one file per profile, so on a shared bot what it learns about one
person lands in everyone's prompt. Re-measured: ~42 KB -> ~17 KB of tool
schemas on Telegram, about 5,800 tokens per message.

skills/README.md: install straight from GitHub with 'hermes skills
install OnlyTerp/hermes-optimization-guide/skills/<name>' (owner/repo/path
identifiers, tools/skills_hub_github.py).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Add chapters 11 (Automation) and 12 (Delegation & Multi-Agent)

Chapter 11 covers choosing a trigger, cron (schedules, delivery, model
resolution, zero-token and pay-on-change runs, continuity, trimming the
cron toolsets: measured -4,100 tokens per call, fleet health, unattended
safety), webhooks, /goal, /loop and /heartbeat, hooks, blueprints,
scripting with -z, stream-json and send, and the emergency brake.

Chapter 12 covers when to split, subagents (what a child gets, measured
7,700 tokens of schemas per call, config, steering, limits), coding
agents and worktrees, the Codex runtime, ACP, Kanban and its traps,
profiles as agents and distributions, Bot Mode, hermes peer, and A2A.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* CHANGELOG: say where LightRAG went and why the old templates were removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* README: link the top-ten list to the exact sections

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* WIP: chapters 09, 10, 13, 14 drafts and the hardened template

Drafts pass the drift guard and anchor checks; final review follows.
templates/config/hardened.yaml is the chapter 13 hardened profile, and
the real v0.21.4 loader reports no structure issues.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Correct the protected-file claim: your own SOUL.md is not approval-gated

tools/file_tools_write_guards.py exempts the Hermes home from
security.protected_instruction_files ('this gate targets PROJECT-LOCAL
files only'). Tested on v0.21.4: a write to ~/.hermes/SOUL.md passes the
gate, while a project SOUL.md or AGENTS.md is gated. The upstream SOUL
guide says otherwise; the code wins.

Chapter 06 now says so and tells you to back up SOUL.md before the Molty
rewrite; the cheat sheet row is fixed; the security-review skill checks
the extra patterns and the memory/skill write gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Pairing: say when strangers really get a code

gateway/authz_mixin.py treats a global unauthorized_dm_behavior: pair as
the default, and the default becomes 'ignore' once any allowlist is set.
The messaging-bot template's global 'pair' line did nothing, so it is
replaced by a comment showing the per-platform setting that does work
(tested: platforms.telegram.unauthorized_dm_behavior lands in the
platform's extra and wins). Recipe 5 now says to leave the allowlist
empty when you want pairing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Docs: the drift guard also checks toolset names; note screenshots removal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* WIP: chapter 09/10 precision edits from the writer's verification pass

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 10 final pass; fix chapter 05 streaming claim; guard reads indented YAML

Chapter 05 said Telegram streams by default. It doesn't: streaming.enabled
is the master switch and defaults to false, and on a fresh install no
per-platform value overrides it (gateway/run_turn_runner.py,
gateway/display_config.py). The row now says how to turn it on.

Chapter 10's final verification pass: approval button sets per platform,
Discord intents, /busy scope, the ExecStopPost fix, FAQ anchors, and more.

drift_guard reads docs and guide YAML fences at any indentation (docs nest
them inside list items).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 11: name the four tools webhook runs get

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Cheat sheet: tools, MCP, plugins and security commands; guard accepts --

New rows: /rollback and 'hermes verify --save', a tools/MCP/plugins/
security section (catalog installs, security audit, approvals test and
suggest, /platform pause), and approvals.deny / streaming.enabled in the
settings table.

drift_guard treats '--' as argparse's end of options, so
'hermes approvals test -- <command>' (checked on v0.21.4) passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Remove the v1 guide: parts 1-29, docs/, benchmarks/, old templates

Everything listed in the CHANGELOG's 'Removed' section: the 29 part files
(mapped to v2 chapters in CHANGELOG.md), README-zh/ja, docs/ (outreach,
evidence, wizard, reference architectures, quickstart, failure modes),
benchmarks/, diagrams/, screenshots/, ECOSYSTEM.md, ROADMAP.md, and the
v1 templates (five config files, systemd, caddy, compose, cron). All of it
remains in git history.

With the v1 files gone, every relative link and anchor in the repo
resolves, and the drift guard, skill lint, yamllint and shellcheck pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 05: explain why byte counts differ slightly between chapters

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* README: point v1 readers to the part-to-chapter map

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Health-check skill: 'not a recognized config key' can be a false alarm

v0.21.4 prints it for some real keys (agent.reasoning_effort,
model_aliases.*, skills.creation_nudge_interval), found while verifying
chapters 03 and 08. Split it from the missing-options row, whose fix is
config migrate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* WIP: chapter 13/14 verification-pass edits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapter 14: which service names hermes update restarts

hermes-serve.service (or hermes-serve-<name>) is restarted by the fleet
pass (hermes_cli/update_cmd_fleet.py). hermes-dashboard.service is
restarted by the post-update dashboard cleanup step
(update_cmd_maint._finish_dashboard_update_cleanup), which skips it
when the Node.js dependency refresh failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Gateway setup: the service is the normal path; don't stack a system unit

'hermes setup' installs and starts a user gateway service without asking
(hermes_cli/setup_platforms.setup_gateway), and 'hermes gateway setup'
offers to, defaulting to yes (gateway_setup_wizard). Chapter 10 told
readers to run 'hermes gateway run' next, which refuses while an
installed service is running (_guard_supervised_gateway_conflict). It
also recommended adding 'sudo hermes gateway install --system', which
would leave two units fighting over one bot token.

Chapter 10, the cheat sheet, chapter 15 and the health-check skill now
treat the installed service as the normal path, keep the foreground run
for debugging with the service stopped, and point to chapter 14's
system-unit steps, which uninstall the user service first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Chapters 01/02: setup installs the gateway service; say so

ensure_gateway_service (hermes_cli/gateway.py) installs and starts a
user-scope service without prompting at the end of Quick and Full setup,
so a new user isn't surprised by a background process and doesn't start a
second gateway by hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* Troubleshooting: list the open Portal OAuth checkpoint issue (#120602)

Opened 2026-09-23 and still open: the Portal's Vercel checkpoint returns
403/429 on the OAuth token and JWKS endpoints, so dashboard logins fail.
Listed as unsolved, with the documented alternative (SSH tunnel to the
loopback-bound dashboard).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* CONTRIBUTING: keep hardened.yaml and chapter 13's block in sync

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

* CI: move actions to their Node 24 majors

The first PR run warned that actions/checkout@v4 and
actions/setup-python@v5 target the deprecated Node.js 20. checkout@v5,
setup-python@v6 and github-script@v8 declare runs.using: node24 and keep
the inputs these workflows use (checked in each tag's action.yml).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf

---------

Co-authored-by: Claude <noreply@anthropic.com>