There are two kinds of knowledge an AI agent can hold. Declarative knowledge is what the model knows from training — facts, patterns, relationships. Procedural knowledge is what the model *does* — the step-by-step sequence that turns intent into output. The gap between these two is where most agent systems fail.
A model can be told, in its system prompt, how to publish a WordPress post. It can read documentation about wp-cli commands. But until it actually *does* it — executes the sequence, hits the failure modes, internalizes the recovery patterns — the knowledge stays declarative. Fragile. One context window away from forgetting.
Skills, in the Hermes ecosystem, are procedural memory. They are the encoded execution patterns that allow an agent to repeat what it has learned. Not by re-deriving the answer each time, but by loading a SKILL.md and following the steps as if they were muscle memory.
## Three memory layers, three functions
The Hermes stack operates on three persistence layers, each serving a distinct cognitive function:
– **state.db** — episodic memory. Raw session transcripts. “What happened on August 4th?” Temporal, searchable, but unstructured. You can replay a conversation but you can’t extract a procedure from it.
– **ChromaDB** — semantic memory. Curated embeddings. “What is conceptually related to this?” Fuzzy matching, context-aware retrieval. Good for finding related knowledge, not for executing a known sequence.
– **Skills (SKILL.md)** — procedural memory. Encoded execution patterns. “How do I do this?” Deterministic, structured, repeatable. The agent loads the skill, follows the numbered steps, and produces output.
This three-layer architecture maps directly to human cognition. Episodic memory remembers events. Semantic memory stores facts and relationships. Procedural memory encodes skills — how to ride a bike, how to type, how to publish a post.
The critical insight: procedural memory is the only one that *executes*. You can have perfect episodic recall and rich semantic knowledge, but without procedural memory, the agent cannot act. Skills are the layer where knowledge becomes behavior.
## What a skill actually encodes
A SKILL.md file is not a document. It is an execution template. The frontmatter defines the trigger conditions — *when* this skill should be loaded. The body defines the procedure — *how* to execute it. The pitfalls section defines the failure modes — *what goes wrong* and how to recover.
Consider the `kanban-orchestrator` skill. Its frontmatter specifies the trigger: when an orchestrator profile receives a decomposition task. The body provides the procedure: create child tasks with explicit assignees, set parent dependencies, complete with structured handoffs. The pitfalls document what goes wrong: unknown assignee profiles silently dropped, phantom task IDs rejected, missing parents creating orphan cards.
This is not documentation about kanban orchestration. It *is* kanban orchestration, compressed into a file. The difference matters. Documentation describes a procedure; a skill *is* the procedure. When an agent loads `kanban-orchestrator`, it doesn’t read about orchestrating — it becomes an orchestrator for the duration of that task.
The procedural encoding is explicit. Numbered steps. Exact commands. Decision trees with concrete conditions. No prose to interpret, no abstractions to reason about. The skill removes ambiguity by replacing judgment with sequence.
## The execution loop: where learning happens
Procedural memory in humans forms through repetition. You ride a bike badly at first, then the motor patterns solidify through practice. Agent procedural memory forms differently — through the author-test-deploy cycle:
1. **Author**: A SKILL.md is written to solve a specific problem. The author encodes what worked into numbered steps and what failed into the pitfalls section.
2. **Test**: The skill is loaded by an agent in a real task. The agent follows the steps. Failure modes surface that the author didn’t anticipate.
3. **Iterate**: The pitfalls section is updated. Steps are refined. Triggers are adjusted based on what actually matched.
4. **Deploy**: The skill enters the local library with provenance `created_by: agent`. It is now institutional memory — available to every future agent session.
Each cycle through this loop is a learning event. The skill gets better not because someone retrained the model, but because the encoded procedure was refined through actual execution. The model itself doesn’t change. The encoded procedure does.
This is why the `curator-docs` skill tracks usage metrics. Skills that sit unused for 30 days are flagged — not because they’re bad, but because they represent procedural memory that’s no longer being practiced. Unused skills atrophy. Active skills compound.
## Institutional memory vs. individual memory
A single session can hold a procedure in context. But when the session ends, the procedure vanishes. The next session starts fresh. This is the fundamental limitation of stateless agents: they cannot accumulate procedural memory across sessions without an external encoding.
Skills solve this by externalizing procedural memory into files. The `LOCAL-CUSTOM-SKILLS-INVENTORY` tracks 160 SKILL.md files across 37 categories. Each one represents a procedure that was learned, tested, and preserved. The inventory is not a catalog of tools — it is a map of institutional memory. What the system knows how to do, encoded as executable templates.
The gap between the bundled library (~110 skills) and the local custom library (160 skills) tells the story. The bundled library provides generic procedures — how to search the web, how to create a file, how to run a terminal command. The local library provides institutional procedures — how to govern an agent fleet, how to validate a kanban completion, how to publish to WordPress with the right taxonomy. The local customs are the procedures the system *learned*, not the ones it was shipped with.
## The skill-memory boundary
Procedural memory has a specific shape. It is sequential (step 1 before step 2). It is conditional (if X, do Y). It is recoverable (the pitfalls section documents failure). It is NOT a fact, a definition, or a relationship.
This matters for where skills end and other knowledge types begin. A wiki concept page defines *what* something is — that belongs in the vault, queryable via ChromaDB. A session transcript captures *what happened* — that belongs in state.db. A skill encodes *how to do it* — that belongs in `~/.hermes/skills/`.
The `skills-alignment-map` documents this boundary explicitly. When a skill references a wiki concept, it is grounding procedural memory in semantic knowledge. When a skill references a session, it is grounding procedure in episodic evidence. The three layers interact but do not merge. Confusing them produces fragile systems — skills that contain definitions instead of steps, or memory stores that try to execute.
## What comes next
S4.3 examines the curator — who maintains the procedural memory library and how the lifecycle actually works in practice. S4.5 deepens the three-layer stack — how skills, memory, and vault interact as a unified knowledge system. S4.8 draws the precise skill/memory boundary — what belongs where and why.
But the foundation is this: skills are not documentation. They are not references. They are procedural memory — the encoded ability to act. An agent that loads a skill doesn’t learn something new. It *becomes* something new, for as long as that skill is loaded. And when the skill is refined through execution, the institutional memory of the entire system improves.
That is why agents learn by doing. Not by being told, not by reading, but by executing the procedure, hitting the failure, and encoding the recovery. Skills are the mechanism by which a system accumulates the one kind of knowledge that actually produces output.
