How Hermes Agent’s Skills System Enables Self‑Learning AI Agents

The Hermes Agent, an open‑source AI assistant (71.8K GitHub stars), introduces a novel Skills closed‑loop system that turns successful task executions into reusable, iteratively refined SOPs. The system follows a seven‑stage lifecycle: experience extraction → knowledge storage → intelligent retrieval → context injection → execution verification → automatic improvement.

Global View: Seven‑Stage Loop

The Skills pipeline is visualized as a data flow from creation to self‑improvement, enabling the agent to remember and reuse procedures across sessions.

Skill Creation: When and How

The agent decides autonomously when to create a Skill. Trigger conditions are encoded in SKILLS_GUIDANCE within agent/prompt_builder.py:

SKILLS_GUIDANCE = (
    "After completing a complex task (5+ tool calls), fixing a tricky error, "
    "or discovering a non‑trivial workflow, save the approach as a skill with skill_manage so you can reuse it next time.
"
    "When using a skill and finding it outdated, incomplete, or wrong, patch it immediately with skill_manage(action='patch') — don't wait to be asked.
"
    "Skills that aren't maintained become liabilities."
)

Key rules include requiring at least five tool calls, fixing non‑trivial errors, and proactive patching.

Seven Security Checks During Creation

The _create_skill function in skill_manager_tool.py enforces a chain of validations:

def createskill(name: str, content: str, category: str = None) -> Dict[str, Any]:
    # 1. Name validation – lowercase, digits, hyphens, ≤64 chars
    err = validatename(name)
    # 2. Category validation – single‑level, no path traversal
    err = validatecategory(category)
    # 3. Frontmatter validation – must contain YAML header with name & description
    err = validatefrontmatter(content)
    # 4. Size limit – ≤100,000 characters (~36K tokens)
    err = validatecontent_size(content)
    # 5. Name conflict check – ensure uniqueness across local & external dirs
    existing = findskill(name)
    # 6. Atomic write – tempfile + os.replace() for crash‑safe persistence
    atomicwrite_text(skill_md, content)
    # 7. Security scan – 90+ threat patterns, rollback on failure
    scan_error = securityscan_skill(skill_dir)
    if scan_error:
        shutil.rmtree(skill_dir, ignore_errors=True)

Atomic writes prevent partially corrupted files, and the post‑write security scan eliminates TOCTOU race conditions.

Index Construction: Two‑Layer Cache

To avoid scanning thousands of Skill files on every conversation, Hermes uses a two‑layer cache:

Layer 1 – In‑process LRU cache (max 8 entries) keyed by skill directory, external dirs, available tools, toolsets, and platform hint.

Layer 2 – Disk snapshot storing a manifest of each Skill’s mtime and size; invalidated when any file changes.

Performance results show ~0.001 ms for Layer 1 hits, ~1 ms for Layer 2 hits, and 50‑500 ms for a full scan.

Conditional Activation

Skills are shown in the System Prompt only when their front‑matter conditions match the current environment. The logic in skill_utils.py and prompt_builder.py checks fields such as requires_toolsets and fallback_for_toolsets to hide irrelevant Skills, preventing index bloat.

Progressive Disclosure

Inspired by Anthropic’s Claude, Hermes loads only the Skill index (≈20 tokens per entry) into the System Prompt. When a Skill is needed, the agent calls skill_view(name) to inject the full Skill as a User Message , preserving Prompt Cache and drastically reducing token cost.

Security Scanning

The skills_guard.py module runs a static analysis with 90+ regex patterns (e.g., detecting curl exfiltration of environment variables, DAN jailbreak attempts, hidden Unicode characters) and structural limits (max 50 files, 1 MiB total size, disallowing binary extensions). Findings are categorized by severity and can trigger allow, block, or ask actions based on the Skill’s source (builtin, trusted, community, agent‑created).

Self‑Improvement Mechanism

When a Skill is used and the agent discovers missing steps or incorrect commands, the System Prompt contains mandatory instructions to patch the Skill immediately. The _patch_skill function employs a fuzzy‑match engine to tolerate minor formatting differences, then clears both cache layers so the next conversation loads the updated version.

Design Trade‑offs and Future Directions

Key trade‑offs include:

User‑Message injection protects Prompt Cache but gives the Skill lower instruction weight.

Write‑then‑scan avoids TOCTOU but requires rollback logic.

Two‑layer caching balances hot‑path speed with cold‑start latency.

Fuzzy matching improves patch success but may produce unintended replacements.

Conditional activation reduces token waste but adds front‑matter complexity.

Potential improvements:

Version control for Skills (e.g., backup directory).

Semantic security scanning beyond regex (LLM‑assisted review).

Embedding‑based Skill retrieval to reduce missed matches.

Distributed storage/synchronisation for multi‑device setups.

Relation to Academic Work

The system mirrors the 2023 NVIDIA Voyager paper’s “Skill Library” concept but extends it to real‑world deployment, handling concurrency, cost optimisation, security, and cross‑platform compatibility.

Conclusion

Hermes Agent’s Skills system demonstrates a practical, open‑source implementation of procedural memory for AI agents, offering a valuable reference architecture for anyone building self‑learning, secure, and cost‑effective AI assistants.