feat(skills): skills.auto_load pins skills into every new session (salvage #74060/#26840)

[teknium1]

Summary

skills.auto_load in config.yaml now pins skills as fully loaded at the start of every new session — CLI, TUI, gateway, cron, and API agents all included — the "always-on skill" pattern Cursor shipped as Custom Modes in its Aug 19, 2026 changelog.

Salvages #74060 by @ctaylor86 (itself an authorship-preserving salvage of #26840 by @ArcherQAQ, whose feature commit leads the branch) onto current main, adapted to the backgrounded --skills preload that landed since.

skills:
  auto_load:
    - my-workflow
    - github-pr-workflow

Their mechanism vs ours

• Cursor: pick a skill → "Use as Mode" → the skill stays pinned in the chat, keeping the agent on a playbook.
• Hermes: profile-scoped config list; skills are resolved once when the agent's system prompt is first built and the exact rendered bytes are reused across model switches, compression, and static-prefix restoration — so prompt caching stays intact. Missing/disabled skills warn and are skipped. --ignore-rules / HERMES_IGNORE_RULES=1 suppresses auto-load with the rest of the auto-injected context. Explicit --skills requests dedupe against auto-load by canonical name.

Changes

• agent/skill_commands.py: resolve_auto_load_skills() + build_auto_load_prompt() (purpose-built activation note; same disabled-skill gate and Curator usage bump as --skills)
• agent/system_prompt.py: resolve-once injection in the shared prompt path (all agent surfaces), lifecycle-stable
• agent/agent_init.py, hermes_cli/cli_agent_setup_mixin.py: per-agent resolve-once cache, CLI hands its pre-resolved result to the lazily built agent
• cli.py: auto-load resolution after session-ID creation; adaptation to current main — the --skills payload load is now a background thread joined by finalize_preloaded_skills(), so the dedup set is passed into the background loader and the activated-skills display merges at finalize time (auto_load first)
• hermes_cli/config_defaults.py: skills.auto_load: [] default
• Docs: website/docs/user-guide/cli.md (new section from the original PR) + website/docs/user-guide/configuration.md

Validation

Check	Result
tests/agent/test_skills_auto_load.py + tests/cli/test_cli_preloaded_skills.py	29 passed
Prompt-cache/system-prompt suites (test_system_prompt, test_prompt_builder, test_prompt_caching, test_prompt_cache_boundary, test_prompt_cache_scope)	183 passed
E2E (isolated HERMES_HOME, real skill files, real build_system_prompt_parts on a real AIAgent)	injection ✓, missing-skill warning ✓, resolve-once byte stability after on-disk skill mutation ✓, HERMES_IGNORE_RULES suppression ✓
ruff on all touched files	clean
scripts/audit_pr_attribution.py --fix	all emails mapped

Closes #26840. Closes #74060.

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 42f27c7 — fix(skills): adapt auto_load salvage to backgrounded --skill}

⚠️ Warnings

CI timings · View report · View job

Wall time 7m39s vs 5m10s (+48.1%). 12 job(s) slower, 12 faster, 1 unchanged.

• Python tests / Run tests slice 4/12: -42.0s
• Python tests / Run tests slice 1/12: -40.0s
• Python tests / Run tests slice 11/12: +39.0s
• Python tests / Run tests slice 7/12: +35.0s
• Docs Site / docs-site-checks: +28.0s

---

OSV vulnerability scan · View job

7 known vulnerabilities found in pinned dependencies.

• CVE-2026-67213 in package-lock.json
• CVE-2026-67213 in website/package-lock.json
• CVE-2026-71554 in uv.lock
• CVE-2026-70608 in package-lock.json
• CVE-2026-56876 in package-lock.json
• CVE-2026-70606 in package-lock.json
• CVE-2026-71554 in uv.lock

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

[Sora-bluesky]

Cross-reference: #68608 (open, CI green) also changes agent/agent_init.py and agent/system_prompt.py, for an unrelated mechanism: it gates the kanban worker protocol (KANBAN_GUIDANCE) on HERMES_KANBAN_TASK instead of kanban_show tool presence, at the session-static resolution in init_agent and at the fallback in build_system_prompt_parts. The hunks sit in different regions from the skills preload here, and a merge of the two heads is clean. I will rebase #68608 once this lands.

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

This salvage does the two hard things right. First, cache safety by construction: auto-load resolves once per agent lifecycle and the exact rendered bytes are reused across model switches, compression, and static-prefix restoration (_auto_load_skills_resolved + seeded result), with HERMES_IGNORE_RULES captured at first resolution so the prompt stays stable even if env changes mid-session — the system prompt remains byte-stable for the conversation's life, which is the invariant that matters most here. Second, contributor credit: authorship-preserving salvage from #74060/#26840 with the contributors email mapping included.

The CLI adaptation to the backgrounded --skills preload is also correct: pre-resolve after session creation (so ${HERMES_SESSION_ID} substitution sees the real ID), seed the agent cache so the shared prompt path doesn't re-read config, pass the canonical-name exclusion set into the background loader, and merge display names auto_load-first at finalize time. E2E validation against a real agent with real skill files, including byte stability after on-disk mutation, is the verification standard the repo asks for on context-affecting paths.

Minor points:

1. First-turn latency on non-CLI surfaces: gateway/TUI/cron agents resolve lazily inside the first build_system_prompt_parts, so each configured skill's tree walk (~0.5s per the description for large libraries) lands inside the first turn rather than a startup phase. Probably imperceptible for 1–3 skills; worth a doc line so users with long lists know where the cost goes, and a natural follow-up would be warm-preloading where a background phase already exists (as the CLI does).
2. Missing/disabled entries warn once per agent and skip — good failure direction; consider including whether a similarly-named skill exists in the warning to shorten the typo-debugging loop.
3. Config edits take effect next session (resolve happens at first build) — consistent with the repo's deferred-invalidation default; no action needed, just confirming that's intended behavior worth stating in configuration.md (the new section covers usage; a one-line "picks up on next session" note would help).