How Hermes Skills Evolve: From skill_manage To Progressive Loading
How Hermes Skills Evolve: From skill_manage To Progressive Loading
Hermes documentation calls skills procedural memory. In practice, that means SKILL.md files under ~/.hermes/skills/, plus the skill_manage tool that can modify those files. There is also a layer of progressive disclosure: every session does not load the full manual for every skill into the model context.
This article first separates skills from built-in memory, then explains what layered loading is doing. After that, it looks at when skill_manage writes to disk and which parts of SKILL.md usually change. The small stories near the end are illustrative examples based on official trigger conditions, not real session logs. If you run Hermes locally, you can check ~/.hermes/skills/ to see whether similar changes have appeared.
Skills And MEMORY Are Not The Same Thing
Hermes has two things that are often discussed together, but they serve different purposes.
Built-in memory lives in MEMORY.md and USER.md under ~/.hermes/memories/. These files have strict length limits. At the beginning of each session, their content is inserted into the system prompt as a fixed block. During the session, this block normally does not change; even if the file changes on disk, the updated content only affects later sessions. This is suitable for preferences, environment notes, and short reminders. The official documentation covers this under Persistent Memory.
Skills live under ~/.hermes/skills/. The core file is SKILL.md, compatible with the open format from agentskills.io. What it stores is repeatable procedure: when to use it, how to do it, what can go wrong, and how to verify the result. So when people say a skill “evolves,” they usually mean that these procedural instructions are rewritten, not that a whole chat transcript is compressed into MEMORY.
One is “facts and preferences.” The other is “a reusable operating manual.” Mixing the two makes it sound as if the agent merely “understands you better after chatting.” On disk, these are different write paths.
What Progressive Disclosure Solves
As the number of skills grows, loading every SKILL.md in full for every session would quickly burn through tokens. Hermes documentation describes layered loading. The first layer loads only a list, roughly names and descriptions. The second layer loads the full text of a specific skill by name. A third layer can fetch attached files by path.
In the official API shape, this corresponds to skills_list(), skill_view(name), and skill_view(name, path). The agent first sees a directory, then expands only what it needs. A skill system cannot scale without this design. The “self-evolution” discussed later also depends on it; if every update forced all skill text back into context, the product would not hold up.
What skill_manage Changes On Disk
The Skills System documentation has a section called Agent-Managed Skills. The agent uses skill_manage to create, patch, replace, or delete skills. It can also add or remove supporting files for a skill.
The documentation describes several typical situations.
Sometimes a task has many steps and many tool calls, and eventually succeeds. That is a good moment to turn the pattern into a skill.
Sometimes the agent first tries a wrong path, fails, then finds a working one. This is also a reason to update skills. After success, the working route can be written into SKILL.md, so the next run avoids the old pitfall.
User correction also matters. If you explicitly say “do not use this command, use that one,” and the correction maps to a repeatable workflow, it belongs in Procedure or Pitfalls more than in MEMORY.
Another case is when the agent notices a workflow recurring often enough to deserve its own skill. The documentation describes this as non-trivial work. In practice, it means something more substantial than answering one sentence.
When updating an existing skill, the documentation recommends using patch first, changing only a section rather than rewriting the whole file with edit. For the model, patching saves tokens; for humans, the diff is easier to review.
In engineering terms, the model calls skill_manage, and then files under ~/.hermes/skills/ change. If you want to verify it, inspect tool call records or keep that directory under version control. That is more direct than guessing whether the agent “learned” something.
Commonly Updated Parts Of SKILL.md
The Creating Skills guide usually splits a skill into sections such as when to use it, procedure, pitfalls, and verification. Evolution most often edits those parts.
Procedure may gain a step, or replace a command with one better suited to your environment. Pitfalls may gain a note about when something fails. Verification may change because the acceptance check changed.
This is not the same kind of information as “reply more briefly” in USER.md. The former changes how to do work; the latter changes how to talk to you.
Small Stories: What Evolution Might Look Like
The following examples are invented illustrations, not real logs. They map to the trigger conditions described in the documentation. If you see similar file changes locally, that means the skill_manage path is doing work.
Story 1: Replacing a command.
A deployment skill says docker-compose up, but your machine only has Docker Compose V2, so the correct command is docker compose. After a few failed attempts, the task succeeds. The agent patches the Procedure line. Next time the skill loads, it will not repeat the old command.
Story 2: Adding an environment pitfall.
npm ci keeps timing out in a particular environment. After the successful path is found, the agent adds a Pitfalls note: if installation times out, check network/package registry settings first. That is more useful than storing a vague memory note that “the user’s network is unreliable.” It is an executable hint.
Story 3: Creating a new skill.
Suppose you ask the agent to tag a release, push it, and write release notes. The task uses terminal and Git several times. This matches the “complex task” idea from the documentation. At the end, the agent may create a new directory with a SKILL.md, so the workflow can be reused later.
Story 4: Changing a default.
You say your team’s default branch is develop, not main. The agent patches an existing skill to replace the hard-coded branch. This is better than only writing “the user likes develop” in USER.md, because the next command will actually use the right branch.
session_search, External Memory, Hub Installs, And Local Skills
If you want to know exactly what was said in a conversation three weeks ago, that is a different mechanism. Hermes has session_search, which searches historical sessions in SQLite and can work with summaries. That is for looking up old conversations. Writing steps into SKILL is for preserving reusable procedures.
The documentation also mentions optional external memory providers such as Honcho and Mem0. Those provide deeper modeling or retrieval ability, but they do not replace the small built-in MEMORY and USER blocks. They are also not the same kind of thing as skill files.
Skills installed through Hub, GitHub, or skills.sh with hermes skills install are packaged skills from others, with their own safety scanning and version management. Skills that the agent writes into ~/.hermes/skills/ during work are local procedural knowledge grown from your own usage.
The two paths can coexist. You may install a community skill and also grow several private skills locally. Keeping these concepts separate avoids mixing up “I installed a marketplace skill” with “a task produced my own local SKILL.”
References
Skills System, Persistent Memory, and Creating Skills.
Follow ZiCode on WeChat
If this post was useful, you can follow later updates on WeChat as well.
X / Twitter
Follow @ax2_zicode
Faster technical notes, short thoughts, and new-post alerts are posted on X.
