/learn: Turning Any Source Into a Skill

The Manual Skill Problem

Skills are one of the most powerful parts of Hermes — reusable, on-demand knowledge documents that the agent loads only when it needs them, adding near-zero overhead when they're not in use. The Advanced track introduced skills and covered the SKILL.md format. There is one problem with skills as introduced there: you have to write them.

Writing a SKILL.md well takes time. You need to get the frontmatter right, follow the standard section order (When to Use, Procedure, Pitfalls, Verification), keep the description under 60 characters, and make sure every procedure step references real Hermes tools rather than invented ones. For a seasoned Hermes user, writing a good skill takes maybe twenty minutes. For someone still learning the format, it takes longer and often produces a skill that works inconsistently.

The /learn command, introduced in v0.18, removes that barrier. You point it at a source, and Hermes authors the SKILL.md for you — correctly, according to the contribution standards, using only tools that actually exist in Hermes.

The Four Source Types

The /learn command accepts four types of input:

A local directory. /learn /path/to/project — Hermes reads the directory using its read_file and search_files tools, builds a model of the project structure, and authors a skill that captures its conventions: the deploy commands, the environment setup, the testing patterns, the pre-flight checks. A developer who passes their entire project directory to /learn comes out with a deploy skill that knows the exact Docker flags, environment variables, and required pre-conditions for that specific codebase.

A URL. /learn https://docs.example.com/api — Hermes fetches the page with its web_extract tool and distills the content into a skill. Useful for learning an external API's conventions, a library's idioms, or a methodology described in an online document. A researcher who points /learn at a stack of methodology papers comes out with a literature-review skill that knows the framework.

The current conversation workflow. /learn the deployment process we just walked through — Hermes uses the conversation history as the source. Whatever you and the agent just did together — a multi-step process, a debugging workflow, a configuration sequence — becomes the raw material for the skill. The agent distills what happened into a repeatable procedure. This is particularly useful for capturing novel workflows the first time you discover them, before you forget the details.

Pasted notes or described procedures. /learn followed by a description in plain language. If you have a procedure documented informally — a Notion page, a Slack thread, a mental model you want to formalize — you can paste it or describe it and Hermes authors a skill from it. The agent normalizes informal descriptions into the standard SKILL.md structure.

What the Agent Does Under the Hood

When you invoke /learn, Hermes builds a standards-guided prompt and hands it to the agent as a normal turn. The agent uses its existing tools:

• read_file and search_files for local directory sources
• web_extract for URL sources
• Conversation history access for workflow sources

After gathering the material, the agent authors a SKILL.md that follows the house standards. It then saves the file using the skill_manage tool, which handles the placement in ~/.hermes/skills/ and the category directory structure. The entire process runs as a normal agent turn — which means it works identically across the CLI, the TUI, the messaging gateway, and the web dashboard.

The SKILL.md Authoring Standards

The standards enforced during /learn authoring exist for specific reasons:

• Description under 60 characters. Hermes loads skill metadata (the description) at the session start as part of the progressive disclosure system. Long descriptions bloat the context window before the skill is even invoked. Sixty characters forces the author — human or agent — to be precise about what the skill does.
• Standard section order. When to Use, Procedure, Pitfalls, Verification. This order matters because Hermes loads skills progressively: it reads the When to Use section to decide whether to load the rest. A skill that buries its trigger conditions in the middle of a long prose block gets loaded incorrectly or not at all.
• No invented commands. Every procedure step must reference tools and commands that actually exist in Hermes. This prevents the most common failure mode for manually-authored skills: a procedure that describes a command Hermes does not have, leaving the agent confused when it tries to follow the skill.

The /learn agent is given these standards explicitly as part of its authoring prompt. It does not invent features. It does not reference tools that do not exist. If the source material describes a workflow that requires a tool Hermes does not have, the authored skill notes the limitation in its Pitfalls section.

write_approval: Reviewing Agent-Authored Skills

By default, skills authored by /learn are saved immediately to ~/.hermes/skills/. If you want to review the SKILL.md before it is committed to your skills directory, enable write_approval in config.yaml:

skills:
  write_approval: true

With write approval enabled, any skill write — whether from /learn, a direct agent skill creation, or a skill edit — enters a pending queue. You review the proposed SKILL.md with /skills diff <id>, approve it with /skills approve <id>, or reject it with /skills reject <id>. The pending queue is visible with /skills pending.

Write approval is most valuable in team environments where a shared skills directory contains carefully curated procedures. It prevents an agent from overwriting a production deploy skill with a new version that hasn't been reviewed. For personal use, most practitioners leave write approval off and trust the /learn output — with the understanding that any skill can be edited or deleted after the fact.

The Dashboard Learn Button

The web dashboard adds a graphical interface for the /learn command: a "Learn a skill" button in the Skills section that presents a form with three inputs — a directory field, a URL field, and a text box for notes or workflow descriptions. Submitting the form sends the appropriate /learn command to the active session. The resulting skill appears in the Skills list when the agent finishes authoring it.