The Agent's Skill Loop

Writing a skill by hand is useful. But the feature that makes Hermes different from every other agent platform is that it can write its own skills. When Hermes completes a non-trivial task, something that took multiple tool calls, required conditional logic, or produced a procedure worth repeating, it can call skill_manage to save what it learned as a reusable SKILL.md. This lesson covers how the loop works and how to trigger it.

What you'll learn

• Hermes creates skills by calling the skill_manage tool, the same tool you'd use to write a skill by hand
• The /learn command turns any reference material (a doc page, a directory, a procedure you describe) into a skill
• Progressive disclosure (Level 0/1/2) means skills only consume tokens when they're actually needed

The problem

You can write skills by hand, and you should, for procedures you already know. But the real power of the skill system is that Hermes builds up its own library over time. You don't need to anticipate every procedure it might ever need. When it works through something complex and succeeds, it can write down exactly what it did, and next time a similar task comes up, it follows the procedure it already proved works.

How the loop works

The core of the self-improving loop is a decision tree executed automatically after every successful task. If the procedure is reusable, the agent documents it; otherwise, the session terminates cleanly.

The skill_manage tool has these actions:

Action	What it does
create	Write a new SKILL.md with full YAML frontmatter and markdown body
patch	Targeted find-and-replace edit in an existing skill (preferred for fixes)
edit	Full rewrite of an existing skill
delete	Remove a skill (with optional absorbed_into for consolidation)
write_file	Write a supporting file in the skill directory
remove_file	Remove a supporting file

Build it

Step 1: Trigger the skill loop

Give Hermes a genuinely non-trivial task, something that requires multiple tool calls and produces a repeatable procedure:

Set up a new Python project with the following requirements:
1. Create a pyproject.toml with uv as the build backend
2. Set up pytest with coverage reporting
3. Configure ruff for linting with the default rules
4. Create a src/ directory with an __init__.py
5. Run the tests to confirm everything works
6. Document the entire setup procedure as a reusable skill

Hermes will work through the steps, verify everything works, and then call skill_manage to write a SKILL.md documenting the full procedure.

Step 2: Verify the skill was created

Check the local registry to ensure the system successfully generated and indexed the new skill markdown file.

hermes skills list | grep python

You should see a skill called something like python-project-setup in the list. Inspect it:

hermes skills inspect python-project-setup

Step 3: Use the skill in a new session

Initialize a fresh agent with the skill explicitly injected. This verifies that the isolated procedure functions correctly in a blank context.

hermes --skills python-project-setup

Or in an existing session: /skill python-project-setup

Hermes loads the skill's instructions and follows the documented procedure. If the skill references files or commands that don't exist in the current environment, Hermes adapts, skills are procedural guides, not rigid scripts.

Step 4: Use /learn to create skills from reference material

/learn is the fast path. Point it at anything you can describe and Hermes gathers the material with its tools, then authors a skill:

# A URL
/learn https://docs.example.com/api/quickstart

# A local directory
/learn the deployment scripts in ~/projects/deploy, focus on the rollback procedure

# A procedure you describe
/learn filing an expense: open the portal, New > Expense, attach the receipt, submit

The agent reads the source material, extracts the procedure, and writes a SKILL.md following the standard format. The write-approval gate (skills.write_approval) applies if you have it on, you'll be prompted to approve before the skill is saved.

Step 5: Configure write approval

Enable explicit approval gates to intercept write operations to the skill directory. This provides an audit log and manual review for automatically authored procedures.

hermes config set skills.write_approval true

When enabled, the agent must ask for confirmation before creating or modifying any skill. This is a safety gate, it prevents the agent from silently writing skills you haven't reviewed. For development, leave it off. For production deployments where you want an audit trail, turn it on.

Progressive disclosure, how skills load

Hermes doesn't load every installed skill into every session. That would blow up the context window. Instead, it uses a three-level progressive disclosure pattern:

Level	Call	Returns	Token cost
0	skills_list()	[{name, description, category}, ...]	~3,000 tokens for all skills
1	skill_view(name)	Full SKILL.md content + metadata	Varies per skill
2	skill_view(name, file_path)	A specific reference file within the skill	Varies per file

At session start, Hermes sees only the Level 0 summary of every skill. When it needs a specific skill, it loads the full content (Level 1). If the skill has reference files, it loads those on demand (Level 2). This means you can have 50 skills installed without paying the token cost of loading all 50 into every session.

What goes wrong

Mistake	How you notice it	The fix
Agent doesn't create skills even for complex tasks	After a multi-step task, no new skill appears in the list	The agent won't create a skill for every task, it needs to judge the procedure as genuinely reusable. Add "Document this as a skill" to your prompt to trigger it explicitly
Skill contains incorrect or incomplete steps	The skill fails when reused in a different environment	Edit the skill directly (hermes skills edit or edit the SKILL.md file) and add environment-specific notes. Skills are guides, not rigid scripts
/learn produces a skill that's too vague	The generated skill is generic and misses environment-specific details	/learn works best with specific source material. Point it at a real config file, a real script, or a real procedure, not a high-level description
Too many skills accumulate, cluttering the list	hermes skills list shows 50+ skills, many unused	The Curator handles this automatically. Configure curator.enabled: true and set curator.stale_after_days to a reasonable threshold

Confirm it worked

Run a full end-to-end test of the skill loop by giving the agent a task, verifying the artifact generation, and applying the new skill in a temporary directory.

# 1. Give Hermes a task that warrants a skill:
hermes chat -q "Set up a git pre-commit hook that runs ruff and pytest. Document the setup as a reusable skill."

# 2. Verify the skill was created:
hermes skills list | grep pre-commit

# 3. Inspect the skill:
hermes skills inspect pre-commit-hook

# 4. Test it in a new project:
mkdir /tmp/test-skill-project && cd /tmp/test-skill-project
hermes --skills pre-commit-hook chat -q "Apply the pre-commit hook setup to this project"
cd - && rm -rf /tmp/test-skill-project

Next: The Curator, Skill Lifecycle, keeping your skill library clean as it grows.