How Agents Turn a Single Success into a Reusable Skill

1. What a Skill Is in Hermes

Hermes separates memory from reusable procedural knowledge. Four storage locations are used: ~/.hermes/memory/MEMORY.md – user identity and current state. ~/.hermes/USER.md – user preferences, habits, expectations.

~/.hermes/skills/<name>/SKILL.md – the actionable procedure for a class of tasks.

SQLite FTS5 full‑text index – scenario‑level episodic memory.

A SKILL.md file is a structured operation manual, not a raw dialogue fragment. Example:

# ~/.hermes/skills/python-debugging/SKILL.md
---
name: python-debugging
description: Systematic method for debugging Python runtime errors
version: 1.0.0
---

# Python Debugging Skill

## Trigger Scenarios
- User encounters a Traceback error
- User says "报错了" or "跑不起来"

## Steps
1. Read the full Traceback
2. Locate the last <code>File</code> line (the true error source)
3. Show surrounding code ±5 lines
...

When a similar task is triggered later, the agent loads the corresponding SKILL.md and follows the defined steps.

2. Four‑Level Priority: New Skills Are the Last Resort

The background review prompt defines the preference order (see background_review.py):

# agent/background_review.py
_SKILL_REVIEW_PROMPT = (
    "Preference order - prefer the earliest action that fits:
"
    "  1. UPDATE A CURRENTLY-LOADED SKILL.
"
    "  2. UPDATE AN EXISTING UMBRELLA (via skills_list + skill_view).
"
    "  3. ADD A SUPPORT FILE under an existing umbrella.
"
    "  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class.
"
)

The design aims for a dense skill library. Creating a new skill for every conversation would produce hundreds of one‑off skills and generate massive retrieval noise. Instead, Hermes maintains a small set of class‑level umbrella skills, each covering a family of tasks, while details accumulate in references/, templates/, and scripts/ sub‑directories.

3. Supporting File System: Three Directories with Distinct Roles

The allowed sub‑directories are defined in skill_manager_tool.py:

# tools/skill_manager_tool.py
ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"}

references – knowledge memos such as common error cases or API snippets.

templates – reusable starting points, e.g., a debug‑report template.

scripts – deterministic scripts that can be executed directly.

Example layout for the python-debugging skill:

~/.hermes/skills/python-debugging/
├── SKILL.md               # main file: trigger + steps
├── references/
│   ├── common-errors.md  # knowledge base
│   └── session-2025-01-20.md # full Traceback
├── templates/
│   └── debug-report.md   # reusable template
└── scripts/
    └── check-env.py      # executable script

4. Skill CRUD Operations

The skill_manage tool (implemented in skill_manager_tool.py) supports six actions:

# create: new skill directory + SKILL.md
skill_manage(action="create", name="python-debugging", content="...")

# edit: full replacement of SKILL.md
skill_manage(action="edit", name="python-debugging", content="...")

# patch: precise replacement of a fragment (recommended)
skill_manage(
    action="patch",
    name="python-debugging",
    old_content="## 步骤
1. 读取完整 Traceback
2. 逐行分析...",
    new_content="## 步骤
1. 直接定位最后一个 File 行
2. 输出修复命令"
)

# write_file: add a supporting file
skill_manage(
    action="write_file",
    name="python-debugging",
    file_path="references/session-20250120.md",
    content="..."
)

# remove_file: delete a supporting file
skill_manage(action="remove_file", name="python-debugging", file_path="references/outdated.md")

# delete: remove an entire skill (blocked if pinned)
skill_manage(action="delete", name="python-debugging")

The patch action is favored because it modifies only the necessary fragment, avoiding the high token cost and accidental overwrites of a full edit.

5. When to Create a New Skill: Three Hard Rules

Rule 1 – Class‑level name : The name must describe a whole class of tasks, not a specific PR, error string, or session artifact. Valid examples: python-debugging, code-review-workflow, meeting-summary.

Rule 2 – Front‑matter : SKILL.md must start with YAML frontmatter containing at least name and description, and must have a non‑empty body.

Rule 3 – Pin protection : A skill marked as pinned cannot be deleted, though it can be edited or patched.

6. Usage Tracking: The Skill "Thermometer"

Each skill records usage count and last‑used timestamp via skill_usage.bump_use():

# tools/skill_usage.py
def bump_use(skill_name: str) -> None:
    rec = get_record(skill_name)
    rec["use_count"] = rec.get("use_count", 0) + 1
    rec["last_used_at"] = datetime.now(timezone.utc).isoformat()
    _write_record(skill_name, rec)

The Curator process later marks skills as stale after 30 days of inactivity and archived after 90 days, keeping the library clean.

7. Common Pitfalls: Experiences That Should Not Become Skills

Environment‑setup fixes (e.g., installing Node) – they are transient configuration issues.

One‑off tasks such as a specific quarterly report summary – these are session artifacts, not reusable classes.

Tool failures recorded as permanent constraints – a temporary network glitch should not become a permanent refusal.

Embedding such noise would cause the agent to repeatedly suggest incorrect actions.

8. End‑to‑End Data Flow: From Dialogue to Skill

The complete pipeline for generating a skill is:

User dialogue
    ↓
conversation_loop.py detects turn end
    ↓
spawn_background_review() starts background thread
    ↓
Background Review Agent (inherits parent model/credentials)
    ↓
Execute _SKILL_REVIEW_PROMPT
    ↓
Apply four‑level priority:
  1. PATCH current loaded skill
  2. PATCH existing similar skill
  3. write_file into references/
  4. CREATE new class‑level skill
    ↓
skill_manager_tool validates & writes files
    ↓
skill_usage.bump_use() creates tracking record
    ↓
Next invocation loads the skill directly, no re‑learning needed.

Key configuration for the background Review Agent includes max_iterations=16 (enough room for complex patches) and skip_memory=True (prevents side effects on external memory plugins).

9. Industry Comparison

How major agent frameworks handle experience consolidation:

LangChain : Stores conversation buffer or vector embeddings; agent writes are manual; no structured executable format; no lifecycle management.

AutoGPT : Stores natural‑language fragments; agent can write autonomously; still lacks structured steps and lifecycle management.

OpenAI Assistants : Files must be uploaded by a human; no autonomous writes; no executable structure; no lifecycle.

Claude Code (Anthropic) : Uses MEMORY.md for preferences/context; agent can write, but the file contains no stepwise procedure.

Hermes : Stores SKILL.md operation manuals; agent can write autonomously; front‑matter plus explicit steps provide a structured executable; built‑in stale/archived lifecycle management.

Conclusion

In Hermes, a skill is an encoded operation manual rather than a raw dialogue snippet. New skills are created only as a last resort; the preferred order is patch → add supporting file → create new skill, which prevents knowledge fragmentation. The three supporting directories each have a clear purpose, and usage tracking plus a stale/archived lifecycle keep the skill library healthy. Pinned skills can evolve via edit/patch but cannot be deleted, providing a safety net for critical expertise.