SKILL.md Deep Dive: Authoring from Scratch

Why a Formal File Format Matters

A skill is only as useful as the agent's ability to understand and execute it. Loosely formatted instructions might work for a human reader, but the agent needs predictable structure to load skills efficiently, filter by relevance, and compose multiple skills together without confusion. The SKILL.md format exists to enforce that structure while remaining human-readable and easy to author.

Every SKILL.md file lives in a named directory inside ~/.hermes/skills/. The directory becomes the skill's identity. A skill for running your test suite might live at ~/.hermes/skills/devops/run-tests/SKILL.md. The category directory (devops/) is optional but helps organize large libraries.

The Frontmatter Fields: What They Do and Why

The YAML frontmatter at the top of every SKILL.md contains two types of fields: identity fields that describe the skill, and activation fields that control when it appears.

Core identity fields:

• name — the kebab-case identifier used to invoke the skill as a slash command (/run-tests) and referenced by bundles. Required.
• description — the text the agent reads at Level 0. Maximum 60 characters. This is the single most important field for agent usability: it must tell the agent exactly when this skill is relevant, not what it generally does.
• version — semantic version string for tracking changes. Recommended but optional.
• platforms — optional list restricting the skill to specific operating systems: macos, linux, or windows. Skills without this field are platform-universal.

Metadata fields (nested under metadata.hermes):

• tags — array of keywords for Hub search indexing.
• category — the grouping shown in skill browsers: devops, productivity, development, etc.
• fallback_for_toolsets — array of toolset names. This skill appears in the agent's list only when those toolsets are unavailable. Covered in depth in Lesson 6.
• requires_toolsets — array of toolset names. This skill appears only when those toolsets are available.
• config — array of non-secret configuration values the skill needs from config.yaml. Each entry declares a key, description, default value, and setup prompt.

The required_environment_variables field handles secrets and API keys that the skill needs. Each entry declares the variable name, a user-facing prompt explaining what it is, a help URL, and whether it is required or optional for full functionality. On the CLI, the agent prompts the user securely to supply these values. On messaging platforms, the agent instead directs the user to run hermes setup.

The Four Required Body Sections

Every well-formed SKILL.md body contains exactly four sections in this order. The standard section names are enforced: deviation breaks compatibility with tools that parse skills programmatically.

When to Use describes the trigger conditions that should lead the agent to invoke this skill. Write this as a list of situations, not a list of features. Bad: "A skill for git operations." Good: "Use this when creating a pull request against the main branch after completing a feature."

Procedure contains numbered steps describing what to do. Each step must be expressed in terms of tools available to Hermes: terminal, execute_code, web_extract, read_file, write_file, and so on. Do not invent hypothetical commands or reference tools that do not exist in Hermes. The agent takes these steps literally — invented commands produce errors.

Pitfalls lists known failure modes and how to handle them. This section is what separates a skill built from experience from a skill built from documentation alone. Document the edge cases you have actually encountered: what breaks, why it breaks, and what the recovery path looks like.

Verification describes how to confirm the procedure succeeded. This might be a specific command to run and its expected output, a file to check, or a state to confirm. Good verification steps make the agent self-correcting — it can detect failure and retry without user intervention.

Authoring Standards That Separate Good Skills from Bad

Several authoring rules are enforced by the /learn command and checked during hub security scanning. Apply them consistently when writing skills by hand.

The 60-character description rule is strict. Count the characters. If your description runs longer, the Level 0 scan returns truncated text and the agent cannot make a reliable relevance decision. Compress, do not summarize — pack the most specific trigger signal into 60 characters.

Hermes tool framing means every action in the Procedure section must use a real Hermes tool. Write "Use the terminal tool to run npm test" not "Run npm test in the terminal." The framing matters because the agent parses these steps as tool invocation instructions, not prose.

No invented commands — the most common authoring mistake is describing commands that do not exist. Every CLI command referenced in a skill must be a real command available in the execution environment, not a placeholder like "run the deployment script."

Directory Structure: When One File Is Not Enough

Complex skills benefit from supporting files organized in subdirectories alongside SKILL.md.

Reference files are especially important for skills that wrap complex APIs or have large lookup tables. Instead of embedding a 500-line API reference in the SKILL.md body (which would be loaded at Level 1 for every relevant task), put it in references/api-reference.md and let the agent fetch it at Level 2 only when it needs that detail.

Creating, Patching, and Editing Skills with skill_manage

The agent authors and modifies skills using the skill_manage tool. Three actions cover most situations.

create writes a new skill directory and SKILL.md from scratch. The agent uses this after completing a novel workflow it wants to remember.

patch applies targeted updates to specific sections of an existing skill — adding a pitfall, correcting a procedure step, or updating a version number. Prefer patch over edit for small, focused changes: it is more efficient and produces a cleaner diff for review when write_approval is enabled.

edit rewrites the skill entirely. Use edit only when the procedure has changed significantly enough that a patch would touch most of the file anyway.

Two additional actions manage supporting files: write_file creates or overwrites a file in the skill directory (useful for updating reference files or templates), and remove_file deletes a supporting file that is no longer needed.

All skill_manage operations respect the write_approval gate. When the gate is enabled, the agent's writes go to a staging area rather than being committed directly — giving you a chance to review, diff, and approve or reject each change. Lesson 10 covers this workflow in detail.