The /learn Command: Teaching Hermes Anything
- Select the appropriate /learn source type for any given learning scenario
- Trace the agent pipeline that converts raw source material into a valid SKILL.md file
- Configure write_approval gating to control whether /learn commits new skills automatically or stages them for review
The Learning Gap: Why /learn Exists
Most skill authoring guides start with the SKILL.md file format. That is the right place to understand the structure, but it is not how most skills get created in practice. Writing a SKILL.md from scratch is precise work: you need to know all the frontmatter fields, the four required sections, the 60-character description rule, and Hermes tool framing conventions. Getting all of that right on a first attempt takes time and attention.
The /learn command eliminates that friction. Instead of writing the file yourself, you describe what Hermes should learn from — a directory, a URL, a workflow you just completed, or notes you paste in — and the agent authors the SKILL.md for you, applying all the authoring standards automatically. /learn is the primary skill creation path for most developers, and understanding exactly how it works helps you give it better inputs and review its outputs confidently.
The Four Source Types
The /learn command accepts four fundamentally different types of input, each suited to a different learning scenario.
Local directory: Point /learn at a directory on your filesystem — typically an SDK, a project, or a documentation folder — and the agent reads through it, identifies the key APIs and patterns, and authors a skill that captures how to work with that codebase. This is the right choice when you want Hermes to understand an internal library, a private SDK, or a framework the agent has not encountered before.
/learn ./libs/internal-api/
Documentation URL: Provide a URL to online documentation and the agent fetches and processes the content. It handles multiple pages by following links within the same domain. This is the right choice for public APIs, tools with official documentation, or any external system you want to codify into a reusable procedure.
/learn https://docs.stripe.com/api/charges
Current-session workflow: After completing a multi-step task during a session, you can ask Hermes to turn what it just did into a skill. The agent reviews the session history, identifies the procedure it followed, and captures it as a SKILL.md. This is powerful because the Pitfalls section gets populated with the actual problems encountered during execution, not hypothetical ones.
/learn the workflow we just used to deploy the staging environment
Pasted notes or described procedures: For processes you already understand but have not yet codified, you can paste notes or describe the procedure in natural language. The agent structures what you provide into a proper SKILL.md. This is the right choice for institutional knowledge that exists in someone's head or in an informal document.
/learn [paste checklist or description]
Inside the /learn Pipeline
When you invoke /learn, the agent runs a multi-tool pipeline to gather and structure the source material. The exact tools used depend on the source type, but the general flow is consistent.
For a local directory, the agent uses read_file and search_files to traverse the directory, identify relevant files, and extract key patterns. It skips binary files and focuses on code, documentation, and configuration.
For a URL, the agent uses web_extract to fetch and process the page content. For multi-page documentation, it discovers and follows relevant links to build a complete picture of the system.
For a session workflow, the agent reviews the current conversation and tool call history to reconstruct the procedure from what it actually did, rather than what it intended to do.
After gathering material, the agent authors the SKILL.md. It applies all authoring standards: the description is compressed to 60 characters or fewer, the body follows the four-section structure, the Procedure steps use Hermes tool framing, and the Pitfalls section is populated from real issues encountered in the source material or session.
The final step depends on your write_approval configuration. If approval is off (the default), the skill is committed immediately to ~/.hermes/skills/. If approval is on, it goes to the staging area for your review.
Authoring Standards Enforced by /learn
One of the most important properties of /learn is that it enforces the SKILL.md authoring standards automatically. The agent knows these standards and applies them as it writes. This is what distinguishes a /learn-generated skill from an unconstrained text summary of a document.
Standards enforced during /learn:
- Description is kept to 60 characters or fewer, with the most specific trigger signal prioritized
- All four body sections (When to Use, Procedure, Pitfalls, Verification) are present and in the correct order
- Every Procedure step is expressed using a real Hermes tool — no invented commands
- Frontmatter includes a name, version, and appropriate category
- The skill does not fabricate commands or claim capabilities the source material does not document
These constraints are why /learn produces skills that work reliably on first use, rather than requiring manual cleanup.
When to /learn vs Write Manually
The /learn command handles most skill creation scenarios well, but manual authoring has advantages in specific situations.
Use /learn when: the knowledge exists in a form Hermes can process (a directory, URL, session history, or clear notes); when you want the Pitfalls section populated from real errors; when speed matters more than fine-grained control over the output structure.
Write manually when: the skill requires very specific tool framing that /learn might not infer correctly from the source material; when the Procedure has a complex branching structure that is clearer when authored explicitly; when you are maintaining an existing skill and only need to patch one section.
In practice, many developers use /learn to generate a first draft and then patch specific sections manually — combining the speed of /learn with the precision of hand-authoring for critical steps.
The Dashboard Learn Button
The Hermes web dashboard provides a graphical interface for /learn that does not require typing the command. The Learn button is accessible from the Skills section of the dashboard and presents a form where you select the source type, provide the input (URL, path, or notes), and submit.
The dashboard Learn workflow is identical to the CLI /learn command in behavior — it runs the same agent pipeline and respects the same write_approval configuration. The difference is interface: the dashboard is well-suited to sessions where you are already working in the browser, while the CLI command integrates naturally into terminal workflows.
- /learn accepts four source types — directory, URL, current-session workflow, and pasted notes — each suited to a different scenario for capturing knowledge as a reusable skill.
- The /learn pipeline uses read_file, search_files, and web_extract to gather material before authoring — the source type determines which tools run, but the output always follows SKILL.md standards.
- /learn enforces authoring standards automatically: 60-char descriptions, four required sections, Hermes tool framing, and no invented commands — producing skills that work reliably on first use.
- Use /learn for speed and real-world Pitfall capture; write manually when you need precise control over branching procedure steps or complex tool framing that /learn might not infer correctly.
- The write_approval gate controls whether /learn commits skills immediately or stages them for review — enabling the gate is the right call for team environments or when working with smaller models.