Skill Bundle Design

Skill Bundle Design

Trigger: Use when you find yourself using the same 2-5 skills together repeatedly and want a single-command shortcut.

When to Create a Bundle

CREATE a bundle when:
- Same 3+ skills used together 3+ times
- The combination defines a distinct "task type"
- A single slash command would save 5+ seconds of typing
- You want to share a workflow template with your team

DON'T CREATE a bundle when:
- Skills are never used together
- The bundle would have only 1 skill (just use the skill)
- The combination is accidental (won't repeat)

Bundle Anatomy

# ~/.hermes/skill-bundles/backend-dev.yaml
name: backend-dev
description: Backend feature work — review, test, PR.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests, then implement.
  Open the PR through the standard workflow with co-author tags.

Fields

Design Principles

1. Task-Oriented, Not Topic-Oriented

GOOD: "Build a new API endpoint" bundle
  → github-code-review, test-driven-development, fastapi-api-development

BAD: "Python" bundle
  → python-advanced-patterns, python-testing-advanced, python-async-patterns
  (Too broad — these are rarely all needed at once)

2. Progressive Depth

LAYERED BUNDLES:

/dev-backend    → code-review + tdd + fastapi (slim — everyday use)
/dev-backend+   → above + database-design + caching (full — complex features)

Start with core, create variants for depth.

3. Dependency Order

Skills should be listed in execution order, not importance order:

# WRONG — testing before code exists
skills: [python-testing, python-coding, python-deploy]

# RIGHT — chronological order
skills: [python-coding, python-testing, python-deploy]

Bundle Patterns

Full Stack Feature

name: fullstack-feature
description: Ship a full-stack feature — frontend to deploy.
skills:
  - frontend-bootstrap
  - fastapi-api-development
  - test-driven-development
  - dockerfile-optimization
  - github-pr-workflow

Incident Response

name: incident-response
description: Debug, fix, and deploy a hotfix in production.
skills:
  - systematic-debugging
  - git-bisect-debugging
  - github-pr-workflow
  - git-tag-release
instruction: |
  This is a production incident. Work fast but carefully.
  Document everything in the PR. Add monitoring after fix.

DevOps Pipeline

name: devops-pipeline
description: Set up CI/CD pipeline with monitoring.
skills:
  - github-actions-workflows
  - dockerfile-optimization
  - kubernetes-deployment
  - prometheus-metrics-collection
  - grafana-dashboard-design

Managing Bundles

# Create
hermes bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work"

# List
hermes bundles list

# Show details
hermes bundles show backend-dev

# Edit (recreate with --force)
hermes bundles create backend-dev --skill new-skill --force

# Delete
hermes bundles delete backend-dev

Pitfalls

• Bundle divergence: Skills in a bundle evolve independently — a skill might become irrelevant to the bundle over time
• Over-bundling: 20 bundles when 5 would do — each bundle should cover a distinct task type
• Missing skills: Bundle references a skill that doesn't exist — it's silently skipped
• Bundle vs automatic stacking: /skill1 /skill2 /skill3 does the same thing — bundles just save typing
• Team sharing: Bundle YAML can be checked into a dotfiles repo — ~/.hermes/skill-bundles/ is the path

Verification

hermes bundles list                    # All bundles
hermes bundles show my-bundle          # Verify contents
# In chat:
/bundles                               # List all bundles
/my-bundle test the auth endpoint      # Test it