hermes-models
Skill3 starsChanged 53 days agoMITView on GitHub
Configure Hermes model providers, transports and routing: provider entries, default-route switching, reasoning effort, delegation pins, per-profile copies, and proving a route with live signals. Use when a model 404s or rejects an endpoint, a profile ignores its key, config drifts between root and profiles, vision or image generation errors, or a relay's effort/cost looks wrong. Not for another harness's own model configuration.
- Reads credentials
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 69
Put per-model levels in agent.reasoning_overrides and say which models moved.
- Very specific: line 86
Profiles carry their own
providers:and.env: Add the block, delete any inherited inline model.api_key (it outranks key_env), copy the … - Very specific: line 143
Always report which layers changed and which stayed instruction-only.
- Very specific: line 169
A provider outage is a fleet cutover, not a default change: Every home and every harness that names the dead provider moves in one pass, …
- Distinctive: line 249
Read the session rows as a before/after pair: the newest row must show the new id *and* the row under it must still show the old one — one …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Install-side hooks (the check is required, the script is not)
$HERMES_HOME/scripts/*.py in these docs names a hook the install may ship — a config snapshot
(config-snapshot.py), an install-facts snapshot (snapshot-install-facts.py), a fleet-switch adapter
(model-switch.py), catalog sync/smoke helpers, and the fleet verification pair
(profile-layer-reconcile.py, contract-drift-check.py). What matters is the outcome each one
verifies (the route is live, the metadata resolves, the generated layer agrees with its source), not the
filename. Resolve the command from the install or from this skill's config keys; when the install ships
none, say the check is unavailable instead of implying it passed.
Hermes Models & Providers
<!-- install-root: `$HERMES_HOME` below means the install root; it defaults to `~/.hermes` -->Provider keys in these examples (local-chat, local-openai, …) belong to the reference install:
read your own providers: block and substitute.
When to Use
| You hear / see | Load |
| 换默认模型 / 加 provider / 换 endpoint | rules below + references/model-switching.md |
某模型 404、does not support the responses endpoint | references/custom-providers.md |
| "让 subagent 用便宜点的模型" | references/delegation-routing.md |
| "routing 机制怎么运作" / "能不能按任务自动选模型" | rules 6 + 16 + 18, references/delegation-routing.md |
| profile 里模型/密钥不生效、只有 root 能用 | references/delegation-routing.md → per-profile provider |
| 配置在 root 和 profile 之间漂移 | references/config-drift.md |
| "review 全部 model routing" / 审计整条路由策略 | rules 16 + 18, references/config-drift-audit.md |
vision / image_gen 报错、auto 路由 | references/config-drift.md |
| 给模型声明 context_length / 元数据 | references/provider-metadata-audit.md |
| 某 relay 的 effort/成本/流式行为异常 | references/model-endpoint-matrix.md |
Not for: harness-level endpoints (pi/omp/opencode/dsh) → agent-harness-model-gateways.
Rules
- Transport is per model, not per endpoint. One proxy serves
/v1/responsesfor some ids and/v1/chat/completionsfor others; probe both before concluding a capability is missing. - Provider entries live under top-level
providers:;model.providernormally names the bare key (local-openai). Acustom:<name>prefix is also accepted for custom-gateway entries, so a drift check must strip a leadingcustom:before comparing against theproviders:keys — a raw string compare reports every valid custom route as undefined. Declarecontext_lengthper model. - Switching the default route: writing
model.providerclearsmodel.base_url/model.api_mode. Order: backup →model.default→model.provider→model.api_mode→model.base_url→agent.reasoning_effort. Takes effect on/newor next session start. Promoting a provider that already ledfallback_providersleaves the chain starting with the new default itself — reorder the chain in the same pass so entry 1 is a different provider. - Prove the route with three signals, never
config get: one-shothermes chat -q 'Reply with exactly: PROBE_OK'; thesessionsrow it created (read-onlystate.db); andresolve_reasoning_config(load_config(), "<model>"). agent.reasoning_effortis global, not per model — change it and every selectable model re-tiers. Put per-model levels inagent.reasoning_overridesand say which models moved. The "not a recognized config key" warning is noise; the runtime reads it. Effort is also per surface: the Hermes session,opencode(#maxvariant), andomp/omo(thinking level) can legitimately sit on different tiers for the same id — e.g.deepseek-v4.1-flashathighinside Hermes while the CLIs runmax. Ask which surface the owner means before "aligning" them; do not raise the session tier because a CLI is higher.- Delegation pin is global to the profile;
delegate_taskhas no per-task model parameter and its schema is built at session start (never flip mid-conversation). Per-task granularity = Kanban card override, cron pin, or independent spawn. Verify with a real child spawn + its live transcript. The section is re-read on every spawn (_load_config()insidedelegate_task), so editingdelegation.provider|modelapplies to the next child — no restart, no/new; blank means "inherit the parent model". True per-task routing needsdelegation.backendset to a registeredDelegationProvider(agent/delegation_registry.py); the only bundled one isplugins/delegation/default, which merely applies thedelegation.*section. A custom backend returns one route per task (provider,model, optionalreasoning_effort/profile) and may declare extratask_parameters()to the model — that is the seam for "background work → cheap pool, hot path → fast pool". Until such a plugin exists, per-task routing is the caller's job: name the model explicitly on thepi/ompspawn. - Profiles carry their own
providers:and.env. Add the block, delete any inherited inlinemodel.api_key(it outrankskey_env), copy the key into that profile's.env, then verify with a live one-shot underHERMES_HOME=<profile>. - Dotted model ids cannot go through a dotted path —
providers.<n>.models.deepseek-v4.1-flash.context_lengthbuilds a phantom nested mapping. Set the whole map as one JSON value instead (hermes config set providers.<n>.models '{"GLM-5.3":{"context_length":1048576},"deepseek-v4.1-flash":{"context_length":1000000}}'), or edit YAML with plain dotted keys. Back up first, then read the file back with a YAML parse — a maskedconfig getcannot prove the map shape, and a successful chat does not prove the override was read. - Reasoning effort is a hint, not a guarantee, and the effort→cost ladder is per relay and
non-monotonic. Judge from
usage.reasoning_tokens; sizemax_tokensper model because reasoning is charged against it on chat-completions transports. auxiliary.vision: autois a trap — doctor green only proves routing resolved. Pin provider+model in root and every profile, then run one real image call per profile.- Config drift is the default failure mode. Classify root-only keys as "never overrode" vs
"deliberately different" before mirroring; read back after every write; regenerate
$HERMES_HOME/scripts/config-snapshot.py. - Text-only one-shot generation is
-t clarify, not-t "". An empty-tvalue leaves the FULL toolset enabled — the model can write files and emits tool/diff previews into stdout, corrupting programmatic parsing;-t noneis rejected as an unknown toolset name. Inert form:hermes chat --query-file <f> -m <model> --provider <p> -t clarify -Q --ignore-rules --max-turns 1, then strip the trailingsession_id:line from stdout.hermes chattakes-q/--query(add--oneshotto answer and exit) — there is no-p;-pis thepi/ompflag. Prove inertness once per model by asking it to create a file and checking it cannot. - Aliases and fallbacks are separate records from the provider entry.
model_aliases.<name>is a DirectAlias (model,provider: custom,base_url,key_env) resolved before the catalog, so it needs its own copy of the URL and key variable.fallback_providersentries are{provider: <provider key>, model: <id>}resolved through the provider registry, and they are per-home — set them in root and every profile. Prove both with one probe: point a throwaway alias at a nonexistent model id; the error names that id (alias routed) and the run continues on the fallback (Model fallback: … via <provider>), which proves the chain end to end. Delete the probe alias afterwards. A fallback entry must name a different provider thanmodel.provider— same-provider fallback dies with the outage it was meant to cover, so a default onopencode-go-flashfalls back to a second gateway, not to another id on the same one. - A single bounded task on a non-default model: harness CLI first (
pi, thenomp), nothermes chat.pi -p --no-tools --no-skills --model <provider>/<id> --thinking high @prompt.mdcarries the prompt and nothing else — no tool schemas, no session context — so instruction following on long writing/analysis prompts is measurably tighter. Resolve the binary before concluding it is missing:command -v pi, then the install's own lookup if it has one (mise which pi), then an explicit path the operator keeps. A CLI installed through npm, a tool manager, or a pinned path is just as valid — andcommand -vreturning empty in a non-interactive shell means "not on this PATH", not "not installed". Export whatever directory holds it, or call the absolute path.omp -pis the fallback (it truncates large attachments). - Long generation runs in the background; wait on the event, never on a foreground
sleep.terminal(background=true, notify_on_complete=true)then end the turn, or block once withprocess_manage wait(600 s) — do not poll a file size withsleep 60..240calls: each one blocks the same wall-clock, blocks every other task, and any sleep over the 180 s foreground timeout dies empty-handed.sleepis only for a fixed delay with no event to wait on (e.g. a CI run not yet visible ingh run list), and then ≤30 s. If a long generation comes back truncated (a few hundred bytes instead of a full answer), re-run with--thinking mediumplus an explicit stop condition ("write through to the last section") rather than the same call again. - Name the layer before the model. Seven places decide a model, each with its own lifetime:
model.default|provider(per session,/newor/model),delegation.*(per spawn),delegation.backend(per task, plugin), per-job cron pin (hermes cron edit --model/--provider), each profile'sprofile.yaml, per-invocationpi/omp --model, andfallback_providers(runtime). Instruction files (AGENTS.md / SOUL.md) only steer which layer the agent reaches for — they never change resolution, so "I edited AGENTS.md" is not an implementation of routing. Always report which layers changed and which stayed instruction-only. A whole-surface audit must enumerate all seven plus every cron store: each profile home keeps its owncron/jobs.json, so a job pinned only in root leaves the same work unpinned where it actually runs. Pins onno_agentscript jobs are inert — nothing reads them, so they never count as free-pool coverage — and a harness catalog must be read from that harness's ownmodelscommand, not from its config file. $HERMES_HOME/config.yamlcannot be edited withpatch/write_file— the tool refuses it ("Refusing to write to Hermes config file"); route every write throughhermes config set <dotted.key> <value>. List-valued keys take a JSON string (hermes config set fallback_providers '[{"provider":"p", "model":"m"}]') and land as proper YAML; back up the file first, thenhermes config get <key>plus a read of the YAML block for shape.- Tiered routing: fast pool on the hot path, free/slow pool for everything that can wait. The default session and anything the user waits on stay on the fast provider; subagents, cron agent jobs, batch lanes, self-improvement runs and isolated-context work go to the free pool; paired or multi-view lanes (blind review, MoA references) keep at least one free-pool model so the cheap capacity actually gets used. When the free pool is one gateway with several ids, a 5xx rotates across ids — the failure is the upstream id, not the route config, so probe each id once before blaming the config.
- A fallback or pin is only as real as that home's catalog.
providers.<p>.modelsis a per-home map: root can be missing an id that several profiles already run as their default (gpt-6.1-solran in three profiles while root's catalog never listed it), and a fallback entry naming a missing id fails at failover — exactly when it is needed. Read the catalog of the home you are editing and add the id there first (whole-map JSON, rule 8), then wire the fallback. Effort variants: a#variantis supplied by the client config, so prove the relay accepts it with a CLI override before editing anything —opencode run -m <provider>/<id>#max 'Reply with exactly: V_OK'. Editing the config first leaves you unable to tell a rejected variant from a flaky relay. Config surgery inside generated/provider files (repeated blocks) →references/config-drift.md. - A provider outage is a fleet cutover, not a default change. Every home and every harness that
names the dead provider moves in one pass, and the provider entry itself stays in
providers:so restoration is a single key flip. Two places make a half-cutover look finished: a generated home whose route lives in its generator's repo (editing the generated config is reverted on the next apply), and per-harness effort metadata (thinkingLevelMap/#variant) that lacks the new id's top tier, which silently downgrades every "max" pin. Inventory → migrate → verify against every surface:references/fleet-cutover.md. - A fleet cutover is one command, not 16 edits. An adapter — resolved as
HERMES_MODELS_SWITCH_CMD(env →$XDG_CONFIG_HOME/hermes-models/config.yaml→ amodel-switch.pythe install ships) — applies a preset fromHERMES_MODELS_PRESETSacross Hermes root + every enumerated profile,omp,omo(settings +thinkingLevelMap),opencode(model,agents.build.model, effort variants), the OMP wrapper script defaults and the roster repo's bot bindings;<preset> --checkreports drift,--dry-rundiffs,--rollbackrestores the newest backup,--restart-gatewayschedules the post-cutover restart (whether a hosted bot needs it is per-home — read that home's ownstate.dbrows after real traffic instead of assuming, and treat restart as gated). Edits are line/block level so comments, key order and byte layout survive a round trip. Extend the preset file for a new fleet state instead of hand-editing or writing another script; the binding files stay uncommitted on purpose (repo sync owns commit+push). An install without such an adapter does the same cutover by hand — the contract above is the requirement, the command is configuration. Document the adapter's own usage next to it, not in a personal notes tree. Two presets-file landmines abort every subcommand,listincluded: anoverridesentry naming a profile that no longer exists (target file missingkills the whole run), and a preset still describing the previous fleet state, which silently reports "drift" and would apply the old route. So the order is alwayslist/--check→ fix stale overrides + bringfreeup to the intended state →--dry-run(read the 6 line-level diffs) → apply. A wrong-state preset is worse than no preset: it is a one-command rollback to a route you already left. Preset targets are discovered, never typed.overridesandnana_bindingskeys must resolve as exact name → glob (*-nrs) →all, expanded against what exists ($HERMES_HOME/profiles/*/config.yaml; the roster repo's own bot matrix file — the SSOT the binding files must agree with). A hand-typed roster drifts both ways: a stale name aborts every subcommand, and a missing name half-applies a "switch the fleet" pass while reporting success. So an unknown exact name is a hard error that lists the discovered candidates, and an empty expansion (glob matching nothing,alldiscovering nothing) is an error too — "switch everything" must never silently become "switch zero". The caller that wants precision passes--profiles a,b,*-nrs/--bots …at invocation (and can list candidates first with--list-profiles/--list-bots); the on-disk preset carries the fleet-wide default. Those subcommands, the--check/--dry-run/--rollback/--restart-gatewaysurface and the line-preserving edits are the adapter contract: a reference adapter implements them, a hand pass reproduces them. Validate every target and print all errors before writing anything;--check= 0 match / 1 drift / 2 spec error. Any change to this tool ships a stdlib-unittest fixture suite under the adapter's own test directory, driven through--home <tmpdir>— a fleet-switch script edited without tests is an outage waiting for the next quota reset.
21b. A new id in the same provider is an id swap, not a cutover — the old id stays in every catalog
(rollback), and only live routes move: model.default, delegation.model, MoA aggregator,
model_aliases.*, fallback_providers, cron pins, harness model/modelRoles, wrapper DEFAULT_MODEL.
Three silent-failure traps (model_aliases needs --force, catalog copies need a comma/section-boundary
insert, omo keeps the id in three files) → references/fleet-cutover.md §6.
Proof
The scope is the operator's fleet, not a fixed roster. A "switch the default model" request spans the
root model entry plus every home and binding that pins a model: enumerate $HERMES_HOME/profiles/*/config.yaml
(hermes config paths), the harness settings that carry ids, and the roster repo's per-bot bindings before
deciding the scope, then state what you enumerated. A home you could not enumerate is not covered — say so
rather than assuming it is. Bindings and a roster tiers: block are prose-level truth: the materializer only
validates tier names, so a tier left naming the old model makes that repo lie about the fleet after a cutover.
hermes chat -q 'Reply with exactly: PROBE_OK' # 1. live answer
hermes -p <profile> chat -q 'Reply with exactly: PROBE_OK' \
-t clarify -Q --ignore-rules --max-turns 1 # 1b. same, inside one home
python3 - <<'PY' # 2. the session row
import glob, os, sqlite3
root = os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes")) # quoted heredoc: bash does not expand
for home in [root] + sorted(glob.glob(root + "/profiles/*")):
c=sqlite3.connect(f"file:{home}/state.db?mode=ro",uri=True)
print(home, c.execute("select model from sessions order by started_at desc limit 2").fetchall())
PY
python3 - <<'PY' # 3. effort resolution
import os, sys
root = os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes"))
sys.path.insert(0, root + "/hermes-agent")
from hermes_constants import resolve_reasoning_config
from hermes_cli.config import load_config
print(resolve_reasoning_config(load_config(), "<model>"))
PY
# if the install ships a fact-snapshot hook (look under $HERMES_HOME/scripts), run it here;
# with none, record this check as unavailable rather than implying the sheet matchesRead the session rows as a before/after pair: the newest row must show the new id and the row under it
must still show the old one — one new row alone cannot distinguish a real switch from a route that was already
there. Each home has its own state.db ($HERMES_HOME/profiles/<p>/state.db); root's rows say nothing about a
profile. The sessions table has no provider column — selecting it raises no such column: provider, so
prove the provider from the config/preset and let model carry the runtime evidence. Free-pool probes answer in
10–40 s each; run the per-home loop as one background command with a per-home timeout, not one foreground
call per profile.
Delegation: spawn one real child and read $HERMES_HOME/cache/delegation/live/<id>/task-0.log.
Vision: one real vision_analyze call per profile.
References
references/custom-providers.md— provider YAML shape, transport table, per-model sizing, relay header quirks, and the install's own policy overlay (banned ids, unavailable families, vision pinning) — the method for each is above; the list itself belongs to the install, not to this skill.references/model-switching.md— switching order, three-signal proof, ghc-proxy deployment, Copilot fallback hygiene.references/fleet-cutover.md— multi-home, multi-harness provider cutover (quota outage, retirement, restore): inventory map, generated homes, effort-tier gaps, verification matrix, rollback.references/delegation-routing.md— which layer decides the model (7-row table), delegation precedence, fast-pool/free-pool tier policy + pool probe loop, per-profile provider migration checklist.references/config-drift.md— drift audit, lettered tier menu, reasoning-effort layers, auxiliary vision.references/provider-metadata-audit.md,references/model-endpoint-matrix.md,references/config-drift-audit.md— audit detail.references/cases.md— historical cases: Copilot fallback cleanup, ghc-proxy deployment.scripts/audit-provider-metadata.py,scripts/audit-config-drift.py,scripts/audit-routing-inventory.py,scripts/probe-provider-endpoint.sh— runnable probes (the inventory one dumps every routing layer for all homes into JSON and flags self-fallbacks and cron coverage);templates/ghc-proxy.service— unit template.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

