Custom Skills

Custom Skills are for creating your own skills from your own documentation and procedures. If Community Catalog was “reusing what others did”, then Custom Skills is “turning what you know into a skill without sitting down to write SKILL.md by hand”. The central tool here is the /learn command.

Basic usage

/learn is an open command — point it at anything describable and the agent will gather the material itself using its existing tools, then write it up as a skill following the house standard (description ≤ 60 characters, standard section order, no invented commands that don’t exist):

# An SDK or an internal docs folder — the agent reads it with read_file / search_files
/learn the REST client in ~/projects/acme-sdk, focus on auth + pagination

# An online docs page — the agent fetches it itself
/learn https://docs.stripe.com/api/webhooks

# The procedure you just walked the agent through in this very conversation
/learn how I just deployed the staging server

# Loose notes or a procedure described in words
/learn the expense approval process: open the portal, choose New > Expense, attach the invoice, submit

The nice part: /learn does not require you to structure the content first — describe it however feels natural, and the agent normalizes it into a properly templated SKILL.md.

With large sources — don’t cram into one file, build a library

This is the part worth discussing in depth: if you /learn a book, a stack of papers, or a whole large docs folder, the agent does not compress everything into a single file (details would be lost), nor does it skim through a shallow summary. Instead, it builds a knowledge-base skill: a lean SKILL.md containing the core mental model + a table of contents, while the details of each chapter/topic live in separate files under references/.

For example, /learn ~/books/designing-data-intensive-applications.pdf produces a structure like:

skills/ddia/
├── SKILL.md                    # core mental model + index
└── references/
    ├── ch01-reliability.md
    ├── ch05-replication.md
    └── ch07-transactions.md

The practical benefit: the references/ files cost zero tokens until a question actually needs them — the agent only loads a file when a question touches exactly that topic, so query cost scales with the answer, not with the size of the source.

One important point for copyright/quality compliance: this process synthesizes into a conceptual framework, definitions, and decision rules — it does not copy any passage verbatim from the original source.

Learning more on the same topic — no duplicates created

If you /learn new material about a topic that already has a skill, Hermes merges it into the existing skill instead of creating a new copy — so you can gradually thicken a knowledge-base skill over many runs, like nurturing a living notebook.

Project-specific custom skills

For a repo shared by the team, you can place skills directly in that repo’s .hermes/skills/ — they only activate while working inside that project. But since a skill is action-guiding documentation, Hermes does not automatically trust skills from a freshly cloned repo — you have to act explicitly:

hermes skills trust        # trust the current repo
hermes skills untrust      # revoke

On every git pull, the skill content in the repo is security-scanned again — if dangerous signs are detected (injected prompt-injection commands, credential-exfiltration commands…), that skill is immediately quarantined from the index, without waiting for you to notice.

Notes

• Don’t be afraid to /learn large sources — the knowledge-base skill mechanism is designed exactly for that; there is no “too big to load” problem.
• For internal documentation that changes often (API docs, company playbooks), re-run /learn on a schedule so the skill updates itself, instead of letting it quietly go stale.
• For project-local skills coming from someone else’s cloned repo — always inspect the content before hermes skills trust, because that is the only defensive mechanism against a repo that may carry a malicious skill.