Skill Design Principles

Single Responsibility

The most common mistake in skill design is scope creep. A skill that does two things does neither well: the description cannot accurately summarize both, so the agent invokes it at the wrong moment or misses it when only one of the two tasks is needed.

Three signals that a skill needs to be split:

• The description requires the word and to capture both workflows the skill covers.
• The procedure contains a conditional branch — "if you are doing X, skip to step 4" — that serves a fundamentally different use case.
• The SKILL.md file exceeds 600 lines, often a sign that two workflows have silently merged.

When you split, keep each skill focused on one clear outcome. Supporting material — API references, example outputs, edge case notes — moves to a references/ subdirectory and loads only when explicitly fetched, not on every invocation.

Reference Skills vs. Task Skills

Two fundamental skill types serve different purposes and should not be mixed:

• Reference skills add knowledge that Claude applies automatically without step-by-step instructions. They load inline, stay in context, and shape Claude's behavior throughout the session. A coding style guide, an internal system architecture overview, or a glossary of project-specific terms are all reference skills.
• Task skills give step-by-step instructions for a specific workflow. They are often user-invoked. When the task requires isolation from session history, use context: fork to run the skill in a clean subagent that has full context about the task without distraction from prior conversation.

Mixing reference and task content in one skill degrades both: the reference material inflates every invocation cost, and the task instructions make the skill too specific to serve as ambient knowledge.

Composition Patterns

Claude Code skill stacking lets you combine up to six skills in one message: /write-tests /fix-issue 123 expands both skills, each receiving $ARGUMENTS (here, 123). The stack stops at the first skill with context: fork — that skill runs in isolation and ends the chain. Stacking is additive: each skill adds its instructions to the same turn without reloading prior conversation.

Hermes skill bundles group related skills under one slash command. A bundle is a YAML file in ~/.hermes/skill-bundles/ that lists skills and an instruction field that sequences them. Bundles let you build a multi-step workflow from focused, independently testable skill components without merging them into a single monolithic SKILL.md.

Constraint Design with Advanced Frontmatter

Frontmatter fields are not just metadata — they encode design intent as constraints the platform enforces. Claude Code extensions:

• model — run a cheap, fast model for a reference skill that does not need deep reasoning. The model switch applies for that skill's turn only, then the session model resumes.
• effort — low, medium, high, xhigh, or max. Overrides the session effort level for the duration of the skill invocation. Use effort: max for a deep research skill where thoroughness matters more than speed.
• disallowed-tools — remove tools that must not be available during this skill. Remove AskUserQuestion from a background loop skill that must never interrupt the user. Remove EditFile from a read-only audit skill to make the constraint explicit and enforceable.
• paths — limit auto-invocation to files matching a glob pattern. A Docker skill with paths: Dockerfile*,docker-compose.yml loads automatically only when those files are in scope — not on every session regardless of context.

Hermes-specific frontmatter for constraint design:

• requires_toolsets / fallback_for_toolsets — gate the skill behind a premium capability and declare a cheaper alternative when that capability is absent.
• metadata.hermes.config — declare non-secret preferences (output format, default branch, theme) that arrive as resolved facts in skill context via config.yaml, without embedding them in the skill body.
• Media delivery directives — [[as_document]] forces file-attachment delivery for long outputs; [[audio_as_voice]] promotes audio output to native voice bubbles on messaging platforms that support it.

The Token Budget Mindset

Every line of SKILL.md is a recurring cost. The discipline is straightforward:

• Keep SKILL.md under 500 lines on Claude Code. Move reference material, detailed examples, and edge case documentation to references/ subdirectory files that load only on demand.
• On Hermes, front-load the happy path. The Level 0 description is all many sessions ever read. The full body loads on activation; deeper reference sections load only via explicit skill_view calls.
• State what to do — not how or why at length. Narrative explanation belongs in training material, not in a skill that loads on every relevant session.