Skill Install Lifecycle: Where They Live, How They Load

+15 Mana ✨
Skills Directory Layout(DOCUMENTATION)

Introduction

From the agent's point of view, every skill is just text loaded into the prompt at the right moment. From your point of view as the user, that text has a physical address on disk. Understanding where skills live and how Hermes loads them at startup makes the rest of the system make sense (and gives you a place to look when something is not behaving the way you expect).

Key Concepts

  • ~/.hermes/skills/: The single source of truth for installed skills. Hermes writes here, reads here, and the agent can edit skills here.
  • .bundled_manifest: A file in ~/.hermes/skills/ that records the origin hash of each bundled skill, so updates can sync without overwriting user edits.
  • .hub/: A subdirectory tracking hub-installed skills (lock file, quarantine, audit log).
  • Progressive disclosure: The three-stage loading pattern Hermes uses so dozens of installed skills do not balloon the prompt.

Real World Context

A developer installs three skills: the bundled plan skill, official/security/1password, and a community skill aws-cloudwatch-debug from skills.sh. All three end up under ~/.hermes/skills/, each in its own directory. At the next session start, the agent sees a list of all three with just their names and descriptions. The user types a security-flavored question, and Hermes expands the body of 1password into the prompt only at that moment. The plan and cloudwatch skills stay collapsed. Three installed, one loaded, no context wasted.

Deep Dive

Hermes lays out the skills directory like this:

text
~/.hermes/skills/
├── mlops/
│   ├── axolotl/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   ├── templates/
│   │   ├── scripts/
│   │   └── assets/
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/
│       ├── SKILL.md
│       └── references/
├── .hub/
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest

Categories like mlops/ and devops/ are just directories. Their names show up in discovery so the agent can shortlist by category for category-shaped questions.

The two dotfiles are bookkeeping:

  • .bundled_manifest maps each bundled skill name to the content hash at last sync. On every hermes update, Hermes recomputes the local hash and compares. If it matches, the upstream version copies in and the manifest updates. If it differs, the skill is user-modified and the upstream change is skipped (your edits survive).
  • .hub/ tracks hub-installed skills: which source they came from, which version, audit history, and any quarantined skills the scanner rejected.

At session start, Hermes scans ~/.hermes/skills/ (plus any directories declared in skills.external_dirs in config.yaml) and assembles three levels of context:

  1. Level 0 (~3k tokens): A list of every installed skill with just {name, description, category}. Always loaded. This is what the agent uses to pick.
  2. Level 1 (varies): The full SKILL.md body. Loaded only when the agent decides to activate the skill.
  3. Level 2 (varies): Specific files inside the skill (e.g., a reference doc under references/). Loaded only when the agent decides it needs them.

The agent triggers Level 1 with the skill_view(name) tool and Level 2 with skill_view(name, path). You usually never see this happen: the agent does it transparently when it picks a skill.

External skill directories let you share skills across tools (Hermes, Claude Code, Cursor). Add them under skills.external_dirs:

yaml
skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills

External directories are read-only as far as Hermes is concerned (the agent always writes new skills to ~/.hermes/skills/). Local always wins on name conflicts.

Common Pitfalls

  1. Searching outside ~/.hermes/skills/: Hermes does not auto-pick up skills from random directories. If you put a skill somewhere else, add the path to skills.external_dirs.
  2. Forgetting that user edits stop syncing: Once you edit a bundled skill, hermes update will not overwrite it. That is intentional. If you want the upstream version back, use hermes skills reset --restore.

Best Practices

  1. Trust progressive disclosure: Resist the urge to keep only a handful of skills installed because of context. Level 0 is cheap. Install what you may want, let the agent pick.
  2. Keep external dirs minimal: One or two shared directories with team skills is fine. Many overlapping external dirs make resolution confusing.

Summary

  • All installed skills live under ~/.hermes/skills/, organized by category subdirectories.
  • .bundled_manifest and .hub/ track lifecycle state.
  • Loading is progressive: Level 0 metadata always loaded, Level 1 full body on activation, Level 2 reference files on demand.
  • External directories (via skills.external_dirs) let you share skills with other agent tools.

Code Examples

bash
# Inspect the layout on your machine
ls ~/.hermes/skills/
ls ~/.hermes/skills/.hub/
cat ~/.hermes/skills/.bundled_manifest | head -5

# Add an external shared directory in ~/.hermes/config.yaml
cat <<'EOF' >> ~/.hermes/config.yaml
skills:
  external_dirs:
    - ~/.agents/skills
EOF

# Confirm a skill is discovered
hermes skills list
✓ Completed