Write, Capture, or Install

Three Paths Into Your Library

Every skill in your library arrived through one of three paths. Which path you choose shapes the quality, ownership, and maintenance burden you inherit:

• Hand-write — you author the SKILL.md directly. Full control, maximum quality, highest effort. Right for skills that encode team conventions, complex branching procedures, or security-sensitive workflows where ambiguity is not acceptable.
• Capture — an agent authors the skill from a workflow you just completed, a documentation URL, a local codebase, or pasted notes. Lower authoring effort; good quality for procedural, well-bounded workflows. Always treat the result as a first draft.
• Install — you pull a skill from the community hub. Zero authoring effort; unknown quality and unknown maintenance history. Carries trust and security considerations covered in Lesson 12.

Automated Capture on Hermes: /learn and skill_manage

Hermes provides two mechanisms for automated skill authoring.

/learn accepts four source types:

• Local directories — e.g., "the REST client in ~/projects/acme-sdk, focus on auth and pagination"
• Documentation URLs — e.g., a public API quickstart page
• Recent conversations — e.g., "how I just deployed the staging server"
• Pasted unstructured notes — e.g., "filing an expense: open the portal, click New, attach receipt, submit"

Hermes uses its existing tools — read_file, search_files, and web_extract — to gather source material. There is no separate ingestion engine; /learn constructs a standards-guided prompt and processes it as a normal agent turn. The output follows the agentskills.io format, including When to Use, Procedure, Pitfalls, and Verification sections.

skill_manage is an autonomous tool. After completing complex multi-step workflows — typically five or more tool calls, or after finding a working solution following dead ends — Hermes can independently create a skill capturing what it just did. This is the self-improvement loop: the agent builds its own toolkit as it works. The default configuration allows autonomous writes; the write_approval gate controls whether those writes require human review first.

The write_approval gate: When enabled, every agent-authored skill change stages under ~/.hermes/pending/skills/ for human review before landing in the production skill directory. Run hermes chat --toolsets skills, let the agent complete its work, then review the generated diff before accepting. This prevents autonomous skill writes from modifying your library without review — the same discipline as requiring pull request approval before merging.

Automated Capture on Claude Code

Claude Code has no /learn equivalent. The equivalent pattern is instructed capture: after completing a complex workflow, tell Claude directly — "Write a SKILL.md capturing what you just did." Claude authors the file from its session context and places it in .claude/skills/ for your review before you commit it to the repository.

The approval step is manual rather than gated by a config flag, but the principle is identical to Hermes's write_approval workflow: the agent proposes, the human reviews and commits. The skill is not active until it lands in a loaded skill directory and the session picks it up.

The Quality Gap Between Paths

Auto-captured skills consistently underspecify two sections that hand-written skills get right:

• Pitfalls — the agent documents the happy path thoroughly but often misses failure modes, edge cases, and common mistakes. These come from experience, not from observing a single successful run.
• Verification — the agent may omit or underspecify the step that confirms the workflow succeeded. Without a verification step, the skill produces output with no way to confirm it is correct.

Always treat a captured skill as a first draft. Before promoting it from Experiment to Validated status, run a review pass to add a Pitfalls section, strengthen the Verification step, and confirm the description accurately reflects what the skill actually does.

Decision Framework

Use this heuristic when a new skill is needed:

• Hand-write when the workflow encodes team conventions or policies; when the procedure branches significantly; when the skill is security-sensitive; or when no equivalent exists in the community.
• Capture when you just completed the workflow and the steps are fresh; when the procedure is linear and well-bounded; or when speed of authoring matters more than immediate polish.
• Install when the skill covers a common tool or standard workflow; when a maintained community version exists with a known author; and after you have reviewed the SKILL.md content before adding it to your library.