How-To Guide
Create a Hermes Agent Skill That Triggers Reliably
Create a focused Hermes Agent skill with valid SKILL.md frontmatter, narrow triggers, supporting references or scripts, safety boundaries, and a repeatable acceptance test.
Quick answer
Create a Hermes skill as a focused folder under ~/.hermes/skills/ with a valid SKILL.md, a precise trigger description, ordered procedure, safety boundaries, and an acceptance test. Prove the workflow first, test ordinary/failure/unrelated cases, and keep secrets out of the skill.
A good Hermes skill is a narrow, tested operating procedure — not a giant prompt. It tells Hermes when the workflow applies, which steps and references to use, what it must not do, and what artifact proves success.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and one baseline task working
- ☑A repeated workflow with a known input and expected artifact
- ☑Basic Markdown and YAML frontmatter knowledge
- ☑A disposable project or restricted profile for risky tests
Steps
- 1
Prove the workflow manually
Complete the job once without a new skill. Save the input, output, failure modes, and acceptance checks so the skill captures evidence instead of guesses.
- 2
Create a narrow skill folder
Create a descriptive folder under
~/.hermes/skills/withSKILL.md. Use one skill for one class of task rather than a general project knowledge dump. - 3
Write valid frontmatter and a precise trigger
Add a name and class-level description that says exactly when the skill applies. Include negative boundaries so unrelated prompts do not load it.
- 4
Write the procedure and verification
Document prerequisites, ordered steps, safe defaults, failure recovery, and the artifact or command output that proves completion.
- 5
Add only necessary support files
Put long references, templates, scripts, or assets in dedicated subdirectories. Never embed secrets; treat helper scripts as code that requires review.
- 6
Test ordinary, failure, and unrelated cases
Run a fixed success case, a known failure case, and an unrelated prompt. The skill should improve the job and stay out of unrelated work.
- 7
Audit, version, and maintain
Record provenance, rerun tests after edits, inspect context cost with
/context, and remove the skill if it becomes stale or overlaps native tools, MCP, memory, or another skill.
Pro Tips
- 💡Search and inspect existing skills before building another one
- 💡Keep the trigger description specific enough to exclude unrelated tasks
- 💡Put durable facts in memory and project-specific rules in AGENTS.md instead of duplicating them in every skill
- 💡Keep secrets out of SKILL.md, scripts, examples, screenshots, and repositories
- 💡Use
/contextafter loading the skill to measure its real context footprint - 💡A skill is complete only when ordinary, failure, and unrelated-prompt tests pass
Troubleshooting
❌ Hermes does not trigger the skill
✅ Rewrite the frontmatter description around the user language and exact task class. Verify the skill is listed, then test with a prompt that clearly matches the trigger.
❌ The skill triggers on unrelated tasks
✅ Narrow the description, add explicit non-goals, split broad procedures, and move project-wide rules into AGENTS.md.
❌ A helper script fails or requests too much access
✅ Run it independently in a disposable environment, scope filesystem/network permissions, remove secret assumptions, and make the skill stop safely on failure.
❌ The skill increases token use or conflicts with another skill
✅ Inspect /context, remove duplicated background, link long references instead of inlining them, and keep one owner for each procedure.
FAQ
Where do Hermes skills live?
User skills live under ~/.hermes/skills/, with each skill centered on a SKILL.md file and optional references, templates, scripts, or assets.
What belongs in a Hermes skill?
A repeatable procedure: trigger, prerequisites, ordered steps, safe defaults, failure recovery, references, and a concrete acceptance check.
What should not go in a Hermes skill?
Do not store secrets, temporary task state, an entire project knowledge base, or one-off notes. Use memory for durable facts and project instructions for repository-wide rules.
How do I test a Hermes skill?
Run a fixed ordinary case, a known failure case, and an unrelated prompt. Verify the artifact or command output and confirm the skill stays out of unrelated work.