Bundles: Grouping Skills Into Workflows

The Workflow Problem Skills Cannot Solve Alone

A skill codifies a procedure. A bundle composes procedures into a workflow. The distinction matters because many real tasks require not one procedure but a coordinated sequence of several. Code review requires reviewing the code, running the test suite, and submitting a PR — three separate skills, each covering one area, better kept separate because each is also useful independently.

Without bundles, invoking all three skills means a three-command sequence or a stacked slash command with three entries. Every time you do the same kind of work, you repeat that invocation. A bundle compresses the entire composition into a single slash command, and adds optional workflow guidance that helps the agent sequence the procedures correctly.

Bundle Anatomy: The YAML Format

Bundles live in ~/.hermes/skill-bundles/ as YAML files. The filename becomes the bundle's slug, which becomes its slash command. A file named backend-dev.yaml creates the /backend-dev command.

The bundle YAML format has four fields:

name (optional) — a human-readable display name shown in /bundles listings. If omitted, Hermes normalizes the filename slug into a display name. The slash command always comes from the filename, not this field.

description (optional) — a summary shown in /bundles and the hermes bundles list command. Helps team members understand what the bundle is for at a glance.

skills (required) — a non-empty array of skill names to load when the bundle is invoked. These must match the name fields of installed skills exactly. Skills are loaded in parallel — the order in the array does not determine execution order.

instruction (optional) — a block of guidance text prepended to the loaded skill content. This is where you encode workflow sequencing advice: which skill's procedure to start with, how to handle handoffs between procedures, and what the overall success criteria look like for the combined workflow.

A complete example:

name: Backend Feature Work description: Backend feature work — review, test, PR workflow. skills: - github-code-review - test-driven-development - github-pr-workflow instruction: | Always start by writing failing tests, then implement. Only submit the PR after all tests pass.

Creating Bundles with hermes bundles create

You can create a bundle from the CLI without writing the YAML file manually:

hermes bundles create backend-dev --skill github-code-review --skill test-driven-development --skill github-pr-workflow -d "Backend feature work — review, test, PR workflow"

This command creates ~/.hermes/skill-bundles/backend-dev.yaml with the specified skills and description. The -d flag sets the description; the --skill flag can be repeated for each skill to include.

The instruction field is not available via hermes bundles create — if you want instruction guidance, edit the generated YAML file and add the instruction block manually. The CLI command is for fast bundle creation from known skills; the YAML file is for fine-tuned workflow guidance.

The Instruction Field: Embedding Workflow Guidance

The instruction field is what separates a bundle from a simple skill stack. A skill stack loads multiple procedures and lets the agent synthesize an approach from them. A bundle with an instruction field loads multiple procedures and gives the agent explicit guidance about how to sequence and prioritize them.

Good instruction content includes:

• Which skill's procedure to begin with (especially when a natural ordering exists)
• How to handle the transition between procedures (what signal marks the end of one and the start of the next)
• Overall success criteria for the bundle as a workflow unit
• Edge cases that require a different path through the combined procedures

The instruction field is also a good place to capture team-specific conventions that apply across multiple procedures. If your team requires a specific PR title format, a specific test coverage threshold, and a specific code review comment style, the instruction field lets you encode all of that in one place rather than embedding it in three separate skills.

Bundle vs Single Skill: When Each Fits

The choice between creating a new combined skill and creating a bundle of existing skills depends on whether the component procedures are independently useful.

Create a bundle when: each skill in the bundle is genuinely useful on its own; the task being bundled is a regular workflow that always requires the same combination; you want the agent to have explicit sequencing guidance for a multi-procedure task.

Create a single skill instead when: the procedure is always executed as a unit and no part of it is useful independently; or when the steps are so tightly interdependent that loading them as separate skills would produce confusing, overlapping context.

Bundles favor composability. Single combined skills favor simplicity. In general, prefer bundles when the components already exist as separate skills — do not duplicate procedure content just to have it in one file.

Sharing Bundles Across a Team

Like skills, bundles can live in team-shared directories. The external_dirs configuration in config.yaml applies to skill bundles as well as skills. A shared bundle repository lets every team member invoke the same workflow compositions without each person maintaining their own YAML files.

Team bundles are especially valuable for onboarding. New team members who configure the external_dirs entry immediately have access to the team's full library of workflow compositions — not just individual skills, but the high-level workflows that combine them correctly. A bundle called /first-pr that loads the code review, test, and PR workflow skills with an instruction explaining your team's specific conventions can guide a new developer through their first contribution without a senior developer having to walk them through the process manually.