xiaohei-info Writing Skills
Overview
A good skill captures a reusable method, not a one-off story. It should help future sessions recognize when to load it and exactly how to use it.
Core principle: write skills from proven workflows, then verify they are clear and reusable.
Use This When
Use when:
- creating a new Hermes skill
- updating a stale or incomplete skill
- converting a proven workflow into reusable procedural memory
- evaluating whether something should be a skill at all
What A Skill Is
A skill is:
- a reusable technique
- a repeatable workflow
- a reference guide for a recurring task
- a compact procedure that improves future execution
A skill is not:
- a diary of one session
- raw notes with no trigger conditions
- project-specific temporary state
- something that should instead be enforced mechanically in code or tests
Before Writing A Skill
Confirm all of these:
- the workflow actually worked
- it is likely to recur
- future-you would benefit from loading it
- the value comes from judgment/process, not just static data
Skill Design Rules
1. Optimize for discovery
The description should primarily answer: when should this skill be used?
Do not stuff the description with the full workflow.
Trigger conditions are more important than implementation summary.
2. Optimize for execution
The body should include:
- what the skill is for
- when to use it and when not to use it
- concrete steps in order
- commands or tool patterns when relevant
- pitfalls and verification steps
3. Keep the boundary clean
Prefer:
- one clear workflow per skill
- linked references only when they truly reduce clutter
- concise wording over narrative prose
Recommended Structure
A solid Hermes skill usually includes:
- YAML frontmatter
- Overview
- When to Use
- Steps / Process
- Pitfalls or Common Mistakes
- Verification / Expected Outcome
Hermes-Specific Guidance
When authoring skills for Hermes:
- use Hermes tool names and workflows, not Claude/Codex-specific ones
- reference
delegate_task,todo,skill_manage,search_files,read_file,patch,terminal, etc. where appropriate - avoid assumptions about non-Hermes runtime features unless clearly labeled
- keep instructions compatible with Hermes categories and naming style
Validation Checklist
Before saving or updating a skill, check:
- is the trigger condition clear?
- does the description describe when to use it?
- are the steps specific enough to follow?
- does it avoid session-specific temporary details?
- does it fit Hermes tools and conventions?
- is there any stale or platform-specific wording to remove?
Anti-Patterns
Avoid:
- copying a foreign skill verbatim without adapting tool names and assumptions
- writing a description that summarizes the whole process instead of the trigger
- recording one-off progress as a skill
- leaving ambiguous steps that require guessing
- creating a skill when a simple memory note would be enough
Remember
A skill should save future effort. If it won't reliably help future execution, do not turn it into a skill.