Skill Authoring & The Curator
Relevant source files
The following files were used as context for generating this wiki page:
Skill Authoring and the Curator form the lifecycle management system for Hermes Agent's capabilities. Skill authoring provides the standards and workflows for creating reusable agent behaviors, while the Curator acts as an autonomous background orchestrator that maintains the health, discoverability, and organization of these skills.
The system ensures that skills are not just one-off session artifacts but are distilled into a library of class-level instructions. The Curator prevents library decay by archiving stale content and consolidating overlapping micro-skills into broad "umbrella" skills.
Sources: agent/curator.py:270-290, skills/software-development/hermes-agent-skill-authoring/SKILL.md:200-210
Skill Authoring Standards
Hermes enforces hardline authoring standards to ensure predictability and scannability. Skills are stored as SKILL.md files containing YAML frontmatter and Markdown bodies.
Mandatory Frontmatter
Every SKILL.md must begin with a YAML block. The validator enforces strict limits to ensure the system prompt remains efficient.
| Field | Requirement | Description |
|---|---|---|
name | ≤ 64 chars | Lowercase, hyphenated identifier. |
description | ≤ 60 chars | One sentence ending with a period. Truncated at 57 chars in the system prompt. |
version | SemVer | New skills start at 0.1.0. |
author | Human (Handle) | Credit the human contributor first, then "Hermes Agent". |
platforms | List | OS-bound primitives (e.g., [linux, macos]). |
metadata | Tags/Related | Capitalized tags and list of other in-repo skills. |
Sources: agent/learn_prompt.py:20-40, skills/software-development/hermes-agent-skill-authoring/SKILL.md:50-85
Structural Requirements
A standard skill body follows a specific section order to maintain scannability:
- Introduction: 2-3 sentences explaining what it does and dependency stance.
- When to Use: Bulleted triggers and counter-triggers.
- Prerequisites: Environment variables, API keys, and installs.
- How to Run: Canonical invocation using Hermes tools.
- Quick Reference: Command list without narration.
- Procedure: Numbered steps with checkable completion criteria.
- Pitfalls: Known limits and rate limits.
- Verification: A command or check proving the skill worked.
Sources: agent/learn_prompt.py:45-60, skills/software-development/hermes-agent-skill-authoring/SKILL.md:120-140
The Curator Orchestrator
The Curator is a background orchestrator that manages the skill lifecycle. It operates in two phases: deterministic transitions based on time/activity and an optional LLM-driven consolidation pass.
Curator Lifecycle States
Skills transition between three primary states based on activity telemetry.
The diagram shows the transition of skills from active usage to long-term storage in the archive.
Sources: agent/curator.py:23-28, agent/curator.py:155-185
Deterministic Pruning
The Curator runs automatically when the agent is idle. It checks interval_hours (default 168h/7 days) since the last run. It uses curated_report() to identify skills for transition. Pinned skills and skills referenced by active cron jobs are protected from automatic archival.
Sources: agent/curator.py:115-130, agent/curator.py:165-175
LLM Consolidation Pass
When consolidate is enabled, the Curator forks an AIAgent to perform a qualitative review of the skill library. The goal is to reduce "micro-skill" sprawl.
Consolidation Logic
The Curator identifies "Prefix Clusters" (e.g., hermes-config-*) and determines if they should be merged into an umbrella skill.
The sequence illustrates the interaction between the Curator orchestrator and the specialized LLM agent during consolidation.
Sources: agent/curator.py:270-350, agent/curator.py:815-850
Rehoming Content
Consolidation involves three primary strategies:
- Merge: Absorbing siblings into a broad existing skill.
- Create: Generating a new class-level umbrella.
- Demote: Moving narrow logic to the umbrella's
references/,templates/, orscripts/directories.
Sources: agent/curator.py:315-335, agent/learn_prompt.py:100-115
Configuration & Persistence
The Curator maintains its state in ~/.hermes/skills/.curator_state.
| Setting | Default | Description |
|---|---|---|
interval_hours | 168 (7d) | Frequency of curator runs. |
stale_after_days | 14 | Days of inactivity before marking "Stale". |
archive_after_days | 30 | Days of inactivity before moving to .archive/. |
consolidate | False | Whether to run the LLM consolidation fork. |
Sources: agent/curator.py:23-28, agent/curator.py:70-85
Curator State Structure
{
"last_run_at": "2024-03-20T10:00:00Z",
"run_count": 5,
"paused": false,
"last_run_summary": "auto: 2 archived, 1 marked stale; llm: consolidated 3 into hermes-core",
"last_report_path": "~/.hermes/logs/curator/20240320-100000/run.json"
}
Sources: agent/curator.py:38-50
Skill Documentation Generation
The generate-skill-docs.py script bridges raw SKILL.md files to the Docusaurus website. It categorizes skills as "Bundled" (core) or "Optional" (niche/heavy).
Generation Workflow
- Discovery: Scans
skills/andoptional-skills/forSKILL.md. - Parsing: Validates frontmatter and extracts metadata.
- Escaping: Uses
mdx_escape_bodyto handle MDX-dangerous characters like{and<. - Ascii Guard: Automatically wraps ASCII art/box-drawing characters in
<!-- ascii-guard-ignore -->markers. - Catalog Update: Regenerates
skills-catalog.mdandoptional-skills-catalog.md.
Sources: website/scripts/generate-skill-docs.py:15-50, website/scripts/generate-skill-docs.py:150-180
Skill Authoring and the Curator ensure that the Hermes Agent develops a cohesive, high-quality knowledge base rather than a fragmented collection of session notes. The system combines strict human-centric standards with automated maintenance to preserve library integrity over time.