Skills as Packages: Why a Directory, Why a Contract

+15 Mana ✨
Skill Package Structure(DOCUMENTATION)

Introduction

The Skills format could have been a single Markdown file, or a JSON manifest, or a Python module. It is none of those. It is a directory with conventions. Each directory carries one SKILL.md plus optional subdirectories with predictable names. The shape exists because it makes skills easy to compose, share, and trust, and because it gives Hermes a place to put each kind of content without inventing one-off rules.

Key Concepts

  • Skill package: A directory whose name is the skill's identifier and whose SKILL.md is the entry point.
  • SKILL.md: Required. The Markdown file with frontmatter and instructions.
  • references/: Optional. Longer documentation the agent can load on demand.
  • templates/: Optional. Output formats the agent can emit (Jinja, raw text, fixtures). Hermes-recognized convention; the minimal agentskills.io spec folds templates under assets/.
  • scripts/: Optional. Executable helpers (Python, shell). Run via the agent's existing sandbox tools.
  • assets/: Optional. Supplementary files: images, sample data, fixtures.

Real World Context

A mlops skill called axolotl lives at ~/.hermes/skills/mlops/axolotl/. Inside: a SKILL.md with the procedure, a references/llama3-best-practices.md the agent reads when the user asks specifically about Llama 3, a templates/axolotl_config.yaml the agent fills in for the user, and a scripts/preflight_check.py the agent can run to verify the environment. All four are sibling files in the same directory. The user did not need to know any of this when they typed /axolotl.

Deep Dive

The canonical layout:

text
my-skill/
├── SKILL.md          # required: frontmatter + instructions
├── references/       # optional: long-form docs, loaded on demand
│   ├── deep-dive.md
│   └── api-notes.md
├── templates/        # optional: output formats the agent can emit
│   └── config.yaml.j2
├── scripts/          # optional: executable helpers (sandboxed at runtime)
│   └── preflight.py
└── assets/           # optional: supplementary files
    └── example-output.png

A few design choices fall out of this.

Why a directory and not a single file? Because real workflows often need more than instructions. They need example outputs, longer references, scripts. Bundling them with the SKILL.md keeps them together, version-controlled, and inspectable. The alternative (instructions in one file, scripts in ~/some/other/path) creates drift.

Why predictable subdirectory names? Because Hermes loads them at different levels of the progressive disclosure pattern. The SKILL.md is Level 1: the full instructions. Anything under references/ is Level 2: the agent fetches it only when it decides it needs it. Predictable names let the agent reason about what is in each directory without reading every file.

Why is SKILL.md the only mandatory file? Because the minimum useful skill is just instructions. A skill that just says when the user asks X, do Y, then Z is fully valid. You add subdirectories only when the skill outgrows a single file.

Why no compiled artifacts? Because skills should be readable. The body of the skill is the audit trail. If you ship a binary inside a skill, the security scanner cannot reason about it, and reviewers cannot inspect it. Scripts are fine; opaque binaries are not.

Hermes treats this layout as a contract. When it loads a skill, it knows where to look for what. Authors can rely on conventions instead of inventing per-skill structure. Users can read any skill and know roughly where each kind of content lives.

Common Pitfalls

  1. Putting scripts in the root next to SKILL.md: Hermes does not crash, but readers (and the agent's progressive disclosure logic) expect scripts under scripts/. Move them.
  2. Treating references/ as backup storage: References should be content the agent loads on demand. Random project files are noise.

Best Practices

  1. Start with just SKILL.md: Add subdirectories only when content earns its place. Most skills never need more.
  2. Mirror the canonical layout exactly: references/, templates/, scripts/, assets/. Custom names defeat the contract.

Summary

  • A skill is a directory with SKILL.md plus optional conventional subdirectories.
  • The directory shape supports composition, sharing, and progressive disclosure.
  • references/ and other subdirectories load on demand at Level 2.
  • Keep the layout canonical; resist inventing new top-level subdirectories.

Code Examples

bash
# A real-world mlops skill on disk
~/.hermes/skills/mlops/axolotl/
├── SKILL.md
├── references/
│   ├── llama3-best-practices.md
│   └── troubleshooting.md
├── templates/
│   └── axolotl_config.yaml.j2
├── scripts/
│   └── preflight_check.py
└── assets/
    └── sample-loss-curve.png

# A minimal skill: just instructions
~/.hermes/skills/ops/lunch-coordinator/
└── SKILL.md
✓ Completed