Auto-switch active skills by detected mode. Cuts system prompt tokens by ~32%. Curator-aware — survives skill archival and consolidation.
Hermes loads every installed skill into the system prompt on every turn. At 112 skills, that's ~8,000-12,000 wasted tokens. The gatekeeper detects your mode from your message and keeps only the relevant skills — same agent, same memory, trimmer prompt.
See the architecture in action:
How keyword detection routes to mode switching — click for interactive version
Why loading all 112 skills is like a library kiosk reading every book title
# Clone
git clone https://github.com/jayelbotvibe-web/skill-gatekeeper.git
cd skill-gatekeeper
# Install (creates skill directory + symlinks script)
./install.sh
# Test detection (doesn't switch anything)
python3 skill-gatekeeper.py --detect "Research latest CVEs"
# Switch to a mode
python3 skill-gatekeeper.py research
# → Switched to research — 19 skills active (83% reduction)
# → Run /reload-skills in Hermes
# Check current mode
python3 skill-gatekeeper.py --list
# Reset to all skills
python3 skill-gatekeeper.py --resetSet a default mode that survives resets and gateway restarts:
# Set your preferred mode permanently
python3 skill-gatekeeper.py --set-default dev
# Reapply at any time (cron-friendly)
python3 skill-gatekeeper.py --bootAdd --boot to your cron/daemon to auto-trim after restarts. Two approaches:
- System crontab (if available):
*/30 * * * * python3 /path/to/skill-gatekeeper.py --boot - Hermes scheduler (restricted VPS, no crontab): create wrapper script +
cronjob(action='create', no_agent=true, schedule='*/30 * * * *')
--reset now temporarily restores all skills but keeps your default.
| Mode | Skills | Example prompt |
|---|---|---|
research |
~19 | "Research latest CVEs" |
dev |
~37 | "Fix this Python bug" |
creative |
~25 | "Design a landing page" |
productivity |
~26 | "Schedule my workout" |
podcast |
~14 | "Publish episode 10" |
data |
~10 | "Train this model" |
infra |
~18 | "Check Docker containers" |
gaming |
~5 | "Host a modded Minecraft server" |
social |
~6 | "Post to Twitter" |
all |
112 | Default, all skills loaded |
Ambiguous messages ("hello", "thanks", "what's the weather") fall back to all — no skills are removed.
Not every skill needs to be pre-loaded. Some are supporting skills — pulled on-demand by the core skills when their phase requires them, then disregarded when not. Think of it like a mechanic's tool chest: wrenches and screwdrivers live on the top tray (always visible). The torque wrench and compression tester stay in the drawer until the engine rebuild actually starts.
This keeps the gatekeeper lean without sacrificing capability:
| Layer | Skills | When loaded |
|---|---|---|
| Core | Workflow, production, publishing, etc. | At mode switch — always visible |
| Supporting | Google Workspace, X/Twitter API, YouTube tools, browser automation | On-demand — pulled by core skills only when their phase needs them |
The core skills reference their supporting skills explicitly (e.g., "use google-workspace for Drive uploads"). The agent loads them when it reaches that step. If the step is skipped, those tokens are never spent. No pre-loading, no wasted context.
This two-tier architecture means a podcast production mode stays at ~7 core skills instead of ~20 — but still has access to every supporting tool when it counts.
💡 Pro tip: Tell your agent what mode you're in. Start a session with "I'm working in dev mode today" or "research mode this morning." The agent detects it and switches modes before you even start typing your tasks. More reliable than letting the agent guess from your first message — especially for
gamingandsocialmodes, which have no detection keywords.
Tested on 50 prompts spanning all modes with threshold=1:
| Metric | Value |
|---|---|
| Overall accuracy | 92% (46/50) |
| Research | 100% (12/12) |
| Creative | 100% (8/8) |
| Dev | 83% (10/12) |
| Productivity | 83% (5/6) |
| False positives (neutral→wrong mode) | 0 |
/reload-skills integration |
Verified working on Hermes v0.13+ |
Failures are tie-breaks when two modes score equally (e.g., "Send an email about the deployment" scores dev:1 + productivity:1 → dev wins alphabetically). Recovery is one /reload-skills away.
User sends message
│
▼
Agent detects mode from keyword scoring (zero API calls)
│
├── Score ≥ 1? ──▶ Move irrelevant SKILL.md → skills-disabled/
│ Saves mode as persistent default
│ Agent: "Switched to research (17 skills). /reload-skills"
│
└── Score = 0? ──▶ Keep all skills. Proceed normally.
Cron/daemon runs --boot every 30m
│
▼
Skills directory stays trimmed across gateway restarts
Read ARCHITECTURE.md for design decisions, mode detection algorithm, and customization.
Hermes Curator autonomously maintains your skill library — archiving stale skills, consolidating duplicates. Without coordination, the curator and gatekeeper can conflict: the curator archives a skill the gatekeeper still references, causing silent failures.
v2.0 resolves this. On every mode switch, the gatekeeper reads the curator's run.json trail and adapts:
- Consolidated skill (e.g.,
podcast-production→zeroday-master-workflow) → auto-redirects to the umbrella - Archived with no replacement → skips gracefully with a warning log
- Active skills → pass through unchanged
No manual syncing needed. Both systems run independently, sharing the curator's structured run trail as a common language.
- Hermes Agent (any version)
- Python 3.8+ (stdlib only — no pip install needed)
- Write access to your Hermes skills directory
./install.shThis:
- Copies
skill-gatekeeper.pyto your Hermes scripts directory - Installs the
skill-mode-switchskill so your agent knows how to use it - Adds mode definitions to your
config.yaml
Manual install:
# 1. Copy the script
cp skill-gatekeeper.py ~/.hermes/scripts/
# 2. Install the skill
cp -r skill-mode-switch/ ~/.hermes/skills/devops/skill-mode-switch/
# 3. Restart Hermes or run /reload-skillspython3 skill-gatekeeper.py --reset
# → All 112 skills restored. Default mode preserved.
# → Run /reload-skills.Nothing is ever deleted — skills are moved, not removed.
Edit the MODE_SKILLS and MODE_KEYWORDS dictionaries in skill-gatekeeper.py to add your own skills or adjust detection. The structure is self-documenting.
Hermes profiles isolate skill sets but fragment context — separate conversation histories, separate memory. The gatekeeper keeps everything unified. Same agent, same history, same memory — just a trimmer system prompt.
Classifying the mode with an LLM would be more accurate. But it would also consume tokens — defeating the purpose. Keyword scoring is deterministic, instantaneous, and free. It's right ~92% of the time, and the failure mode (switching to the wrong mode) is visible and one command away from fixed.
MIT