Writing a Skill from Scratch

Introduction

There are two paths to a new skill: write the SKILL.md by hand, or let the agent draft one for you with the skill_manage tool. Either path produces the same kind of artifact (a directory under ~/.hermes/skills/ with a SKILL.md inside). The choice is about whether you have a clear procedure already or are codifying something you have just figured out with the agent.

Key Concepts

• Manual authoring: You open an editor, write SKILL.md, drop it in ~/.hermes/skills/<category>/<name>/.
• Agent authoring (skill_manage): The agent creates, patches, edits, or deletes skills on your behalf from inside a session.
• Procedural memory pattern: Treat skills as the agent's external memory. After solving a multi-step problem once, capture the solution as a skill.
• Iteration loop: First draft, activate, observe, refine, persist.

Real World Context

A developer spends an afternoon walking the agent through a tricky Postgres migration: dump, transform, restore, validate. It works. At the end, they tell the agent save this as a skill so we can run it again next quarter. The agent calls skill_manage(action='create', name='pg-quarterly-migration', content='---\n...') and writes a SKILL.md capturing the steps. The next quarter the same person types /pg-quarterly-migration and the same procedure runs without rediscovery. The skill is procedural memory.

Deep Dive

Manual authoring is the simpler shape. You write a file, drop it in the right directory, and Hermes picks it up next session (no install step needed for local skills).

bash
mkdir -p ~/.hermes/skills/workflows/git-commit-style
cat > ~/.hermes/skills/workflows/git-commit-style/SKILL.md <<'EOF'
---
name: git-commit-style
description: Draft a conventional-commits message from staged changes.
---
# Git Commit Style
## When to Use
User asks to commit or write a commit message with staged changes.
## Procedure
1. Run `git diff --staged` via the terminal tool.
2. Classify: feat / fix / chore / docs / refactor / test / perf.
3. Format the subject as <type>(<scope>): <imperative summary>.
4. Show the result. Wait for confirmation before committing.
EOF

Agent authoring uses the skill_manage tool. From the user's side it looks like a conversation:

text
User:  We just figured out a clean way to debug slow Postgres queries.
        Save this as a skill called pg-slow-query-debug.

Agent: (calls skill_manage with action='create', name='pg-slow-query-debug',
        content='---\nname: pg-slow-query-debug\n...')
        Saved pg-slow-query-debug. Use /pg-slow-query-debug next time.

Under the hood the agent has the same actions you do:

The patch action is preferred over edit for small changes because only the diff appears in the tool call (saving tokens) and the rest of the file is untouched.

Which path should you pick? A few rules of thumb:

• You already know the procedure cold: Manual is faster. Edit SKILL.md directly, done.
• You just solved something new with the agent: Agent authoring captures the live context. Tell the agent to save the working procedure.
• You are editing a community skill: Manual, because the file already exists and you are mostly tweaking. If you change a bundled skill, remember it flips to user-modified.
• You want consistent style across many team skills: A custom GitHub tap with hand-written skills gives you the most review control.

Common Pitfalls

1. Editing inside Hermes without copying back to your tap: If you write a skill locally and want to share it, copy it into your GitHub tap repo. Otherwise it lives only on one machine.
2. Letting the agent author skills without review: Procedural memory is great, but a stale or wrong agent-created skill is worse than no skill. Treat agent-authored content like a PR.

Best Practices

1. Author small, refine often: A draft skill that captures 70% of the procedure is enough to start. Refine on the next use.
2. Anchor the skill to a real session: After the agent helps you solve a problem, ask it to summarize the steps as a SKILL.md. Review and persist.

Summary

• Two authoring paths: manual (you write the file) and agent-driven (the agent uses skill_manage).
• Local manual skills are picked up next session, no install step needed.
• The agent has create, patch, edit, delete, write_file, remove_file actions; patch is preferred for small changes.
• Pick the path that matches your starting state and review agent-authored content.

# Manual: create a brand-new local skill
mkdir -p ~/.hermes/skills/workflows/release-notes
cat > ~/.hermes/skills/workflows/release-notes/SKILL.md <<'EOF'
---
name: release-notes
description: Draft release notes from the commits between two tags.
---
# Release Notes
## When to Use
User asks to write release notes between two tags or since a date.
## Procedure
1. Run `git log <prev_tag>..<new_tag> --pretty=format:'%h %s'` via the terminal tool.
2. Group commits by conventional-commit type.
3. Render a Markdown changelog with sections: Features / Fixes / Chores.
EOF

# Agent path (the user just types this in a session):
# "Save these steps as a skill called release-notes"
# The agent calls skill_manage(action='create', name='release-notes', content='...')