The Write Approval Gate: Controlled Skill Creation

When Autonomous Skill Creation Needs Oversight

The self-improvement loop is one of Hermes's most powerful features: the agent autonomously creates skills from completed workflows, building a library that grows more capable over time without requiring manual intervention. But autonomy has a cost. An agent creating skills without oversight can introduce procedures with subtle errors, encode incomplete workflows, or — in security-sensitive environments — capture information that should not be persisted.

The write approval gate is the oversight mechanism. When enabled, it intercepts all skill_manage write operations — creates, patches, edits, and file writes — and places them in a staging area rather than committing them immediately. You review the staged changes, see exactly what the agent is proposing to add or modify, and approve or reject each one. The agent's autonomy is preserved; your control over what gets committed is too.

Enabling the Gate

The write approval gate is disabled by default. Enable it in config.yaml:

skills: write_approval: true

Once enabled, every skill_manage operation from the agent is staged rather than committed. The agent receives a confirmation that the write was staged, but the skill does not appear in ~/.hermes/skills/ or the agent's skill directory until you approve it.

The gate applies to all write operations: create, edit, patch, write_file, and remove_file. Read operations — skills_list() and skill_view() — are unaffected. The agent can still read its existing skills; it just cannot silently modify them.

The Staging Workflow

Staged writes accumulate in ~/.hermes/pending/skills/. Each staged write is given a unique identifier and stored as the complete file diff — the before state and the proposed after state — along with metadata about what triggered the write and when.

The staging area is persistent across sessions. If a skill write is staged during one session, it remains pending until you approve or reject it, regardless of how many sessions run in the meantime. This means a high-productivity session that triggers many skill creates or patches can accumulate multiple pending items for review at a time that is convenient for you.

Review Commands: pending, diff, approve, reject

Four commands manage the approval workflow, all available as both slash commands (in chat) and via the CLI.

/skills pending (or hermes skills pending): Lists all staged writes with their IDs, types (create/patch/edit), skill names, and timestamps. This is the starting point for any review session.

/skills diff <id> (or hermes skills diff <id>): Displays the unified diff for a specific staged write, showing exactly what the agent is proposing to add, change, or remove. For a create operation, this shows the full proposed SKILL.md content. For a patch, it shows only the changed lines in context.

/skills approve <id> (or hermes skills approve <id>): Commits the staged write. The skill is moved from the staging area to ~/.hermes/skills/ and becomes active in the agent's skill directory after the next /reload-skills.

/skills reject <id> (or hermes skills reject <id>): Discards the staged write. The proposal is deleted from the staging area. The agent can propose the same change again in a future session, but the current proposal is gone.

Toggling Approval Mode

You can toggle the gate on and off without editing config.yaml, using a slash command that persists the setting:

/skills approval on

/skills approval off

This is useful for temporarily suspending the gate during a session where you want the agent to build up a skill library quickly, then re-enabling it when the exploratory phase is done. The toggle persists to config.yaml so the setting survives session restarts.

Choosing the Right Approval Strategy

The approval gate is not needed in every context. Matching the approval strategy to the deployment environment avoids unnecessary friction where oversight is not required.

For a solo developer working locally with a large, capable model, the default (gate off) is typically correct. You have full visibility into what the agent is doing, the model is capable of producing high-quality skills, and the cost of a bad skill is low because you can patch it immediately.

For team deployments where a shared agent has write access to a team skill library, the gate is essential. Skills written to the shared library by an autonomous agent without review can propagate errors to everyone who uses the library. The gate ensures a human reviews every proposed addition before it affects the shared repository.

For deployments using smaller or less capable models as the primary agent, the gate catches the higher error rate that comes with reduced model capability. Smaller models are more likely to produce procedure steps that reference invented commands, descriptions that exceed 60 characters, or sections that are missing. The gate is cheap insurance against these quality issues reaching the active skill library.