Introduction: The skill that teaches skills
The Skills Canvas is not just a library — it is a living system where every SKILL.md file is both a tool and a lesson. When an agent loads a skill, it pays for that skill’s description in every subsequent turn. A well-authored skill changes agent behavior predictably. A poorly authored one wastes tokens, confuses the model, or worse — does nothing at all.
This article is about the craft of writing those files. Not the theory of skill lifecycle management (that is S4.3), not the product strategy (S4.10), but the actual mechanics: what goes in the frontmatter, how to design triggers that fire reliably, and the pitfalls that separate a useful skill from dead weight.
Frontmatter: the contract between author and system
Every SKILL.md begins with YAML frontmatter — the metadata block between the opening --- and the first closing ---. This is not decorative. The Hermes skill validator enforces hard requirements:
Required fields:
name: lowercase, hyphens only, max 64 characters. The name is the skill’s identity inskill_view()andskills_list().description: max 1024 characters. But here is the critical constraint — the system prompt skill index truncates descriptions to the first 57 characters plus “…”. If your trigger phrase does not fit in that window, the agent will not know when to load your skill.
Peer-matched fields (not validator-enforced, but expected):
version: semantic versioning (1.0.0, 1.1.0).author: who wrote it.license: MIT is the convention.metadata.hermes.tags: short descriptive tags for categorization.metadata.hermes.related_skills: links to peer skills in the same or adjacent categories.
The frontmatter is the skill’s resume. It tells the system what the skill is, when to load it, and how it relates to other skills. Omit the metadata block and your skill looks half-finished. Omit the description trigger and the agent will never discover it.
Designing triggers: the first 57 characters
The trigger is the most important design decision in any skill. It answers: “When should the agent load this skill?” The answer must fit in 57 characters because that is where the system prompt truncates.
Good triggers start with “Use when” and complete the trigger class within the window:
Use when debugging Hermes skill discovery failures.— clear, specific, actionable.Use when authoring in-repo SKILL.md files.— tells the agent exactly when.Use when publishing lucidhive.com posts via docker-exec wp-cli.— narrows to a concrete workflow.
Bad triggers bury the signal past the cutoff:
This skill contains detailed guidance for agents working on Hermes skill discovery failures and related debugging workflows.— the agent sees “This skill contains detailed guidance for agents working on Hermes” and has no idea what to do with it.
The trigger is not a summary of the skill. It is a classification rule. The agent loads skills based on whether the current task matches the trigger class. Design it like a search query: specific enough to fire on relevant tasks, broad enough to catch the variations.
The body: process predictability over completeness
After frontmatter, the body is where the skill lives. The goal is not encyclopedic documentation — it is process predictability. A skill exists to make the agent’s process more predictable. Every line should change behavior.
Structure that works:
- Overview: one or two paragraphs — what and why.
- When to Use: bulleted triggers plus counter-triggers (“Don’t use for:”).
- Actionable body: commands, tables, code blocks, exact sequences.
- Common Pitfalls: numbered mistakes and their fixes.
- Verification Checklist: post-action items the agent can check.
Quality principles:
- Optimize for behavior change. If a line does not change what the agent does, cut it.
- Use strong leading words. “Tight loop,” “root cause,” “regression test” — compact concepts the model already knows. They save tokens and anchor behavior.
- End steps with completion criteria. Each ordered step should say how the agent knows it is done. “Verify every file modified” beats “summarize changes.”
- Co-locate rules with concepts. Keep definition, caveats, and examples near each other. Do not scatter one idea across the file.
- Progressively disclose. Put always-needed steps in SKILL.md. Put branch-specific reference in
references/,templates/, orscripts/and link to them.
Common pitfalls: the mistakes that waste tokens
After authoring hundreds of skills across the Hermes library, these are the patterns that consistently fail:
1. Description too generic. “This skill helps with various tasks related to agent configuration.” The agent has no trigger class. It will never load this skill.
2. Leading whitespace before ---. The validator checks content.startswith("---"). A blank line or BOM at the top breaks validation silently.
3. No-op prose. “Be careful,” “be thorough,” “use best practices.” These lines do not change model behavior. Replace them with checkable completion criteria or delete them.
4. Duplication. The same rule appears in three places and drifts. Keep each meaning in one source of truth.
5. Sprawl. Pushing 20,000+ characters into SKILL.md when 8–15k would do. The agent pays for this content every turn. Split bulky reference into linked files.
6. Expecting the current session to see new skills. The skill loader is cached at session start. A skill created this turn is invisible until the next session. This is not a bug — it is a design constraint.
7. Writing a skill that duplicates a peer. Before creating, check existing skills. A 71-skill library with five overlapping “debugging” skills is worse than one great one.
8. Forgetting related_skills. If your skill depends on or complements others, declare it. The metadata block is how the system builds a graph of capabilities.
9. Sediment. Stale lines remain because adding felt safer than deleting. A skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces.
The authoring workflow in practice
The concrete steps from the hermes-agent-skill-authoring skill:
- Survey peers in the target category. Read 2-3 existing SKILL.md files.
- Draft with frontmatter matching the peer pattern.
- Validate the frontmatter parses correctly, name and description fit constraints.
- Test by loading the skill in a fresh session and verifying the trigger fires.
- Commit to the appropriate location — user-local (
~/.hermes/skills/) or in-repo (skills/<category>/).
The distinction matters: skill_manage(action='create') writes to the user-local tree. In-repo skills use write_file directly. Mixing these up is the most common workflow mistake.
Conclusion: skills are living contracts
Every SKILL.md is a contract between the author and the system. The frontmatter declares what the skill does and when it fires. The body defines how the agent should behave. The pitfalls section documents what goes wrong when the contract is poorly written.
The Skills Canvas works because its skills are maintained with intention. The 71-skill library is not a dump of helpful hints — it is a curated collection where each file has been sharpened through use. The authoring craft is what makes that possible.
When you write a skill, you are not just documenting a workflow. You are programming an agent’s behavior. Treat the frontmatter as a search query, the body as a process specification, and the pitfalls as regression tests. The skill that survives contact with real usage is the one that was authored with care.
