Creating Bundles — OMNISKILL Documentation

📦 What's a Bundle?

A bundle is a domain kit — a collection of related skills packaged together with a meta-skill that orchestrates them. Bundles solve the problem of overlapping skills by defining clear routing and priority.

💡

Why Use Bundles?

Atomic operations: Install, update, or remove entire domain kits at once
Conflict resolution: Meta-skill intelligently routes between overlapping skills
Shared resources: All skills in a bundle can access common reference materials
Cohesive experience: Skills work together seamlessly instead of competing

🏗️ Bundle Structure

📁 bundles/my-kit/

📄 bundle.yaml — Bundle manifest

📁 meta-skill/ — Composition skill

📄 SKILL.md — Routing logic

📄 manifest.yaml — Meta-skill metadata

📁 shared-resources/ — Resources for all skills

🚀 Creating a Bundle

Step 1: Define bundle.yaml

The bundle manifest declares which skills are included and how conflicts are resolved:

bundle.yaml

name: my-domain-kit
version: 1.0.0
description: "Complete toolkit for [domain]"
author: your-name

skills:
  - skill-a
  - skill-b
  - skill-c

meta-skill: my-domain-expert

dependencies: []

conflict-resolution:
  - when: "skill-a AND skill-b both match"
    prefer: skill-a
    reason: "skill-a is more specific for this case"
  
  - when: "skill-b AND skill-c both match"
    prefer: skill-c
    reason: "skill-c has higher accuracy for this scenario"

⚠️

Skill Names Must Match

The skills listed in skills: must match directory names in the skills/ folder. The validator will check this.

🧠 Step 2: Create the Meta-Skill

The meta-skill is the orchestrator. Its SKILL.md defines how to route between constituent skills:

meta-skill/SKILL.md

# My Domain Expert

You are a **meta-skill** that composes and routes between these skills:

- **skill-a**: Use for [specific scenario A]
- **skill-b**: Use for [specific scenario B]
- **skill-c**: Use for [specific scenario C]

## Core Identity

You are an expert orchestrator for [domain]. Your job is to:
1. Understand the user's request
2. Determine which constituent skill(s) to invoke
3. Coordinate between skills if multiple are needed
4. Ensure coherent output

## Routing Rules

### Primary Routing
1. If the request is about [X] → invoke **skill-a**
2. If the request is about [Y] → invoke **skill-b**
3. If the request is about [Z] → invoke **skill-c**

### Composite Routing
- If request requires both [X] and [Y] → invoke **skill-a** then **skill-b**
- If ambiguous → ask user for clarification

### Fallback
- If no specific skill matches → use general knowledge with domain context

## Conflict Resolution

When multiple skills could handle a request:
- Prefer **skill-a** for [specific condition]
- Prefer **skill-b** for [different condition]
- If truly ambiguous, present options to user

## Shared Context

All skills in this bundle have access to:
- Shared resources in `shared-resources/`
- Common style guide: [reference]
- Domain standards: [reference]

✓

Meta-Skill Best Practices

Be explicit about routing conditions
Handle ambiguous cases gracefully
Document why certain skills are preferred
Provide fallback behavior

Meta-Skill Manifest

The meta-skill also needs its own manifest:

meta-skill/manifest.yaml

name: my-domain-expert
version: 1.0.0
description: "Meta-skill that orchestrates the my-domain-kit bundle"
author: your-name
license: MIT

platforms: [claude-code, copilot-cli, cursor, windsurf, antigravity]

tags: [meta-skill, domain, orchestration]

triggers:
  keywords: ["domain task", "domain help"]
  patterns: ["* for domain", "domain *"]

priority: P1  # Meta-skills typically have high priority

is-meta-skill: true
bundle: my-domain-kit

📚 Step 3: Add Shared Resources

Resources in shared-resources/ are available to all skills in the bundle:

📁 shared-resources/

📄 domain-reference.md — Core domain knowledge

📄 common-patterns.md — Reusable patterns

📄 style-guide.md — Output standards

📄 glossary.md — Domain terminology

shared-resources/domain-reference.md

# Domain Reference

## Core Concepts
- **Concept A**: Definition and usage
- **Concept B**: Definition and usage

## Best Practices
1. Always [practice 1]
2. Never [anti-pattern]
3. Prefer [approach] over [alternative]

## Common Pitfalls
- **Pitfall 1**: Why it's bad and how to avoid
- **Pitfall 2**: Why it's bad and how to avoid

Skills can reference shared resources in their manifest:

skills/skill-a/manifest.yaml

resources:
  - path: ../../bundles/my-domain-kit/shared-resources/domain-reference.md
    type: reference
    load: always

✅ Step 4: Validate

Run the validation script to ensure your bundle is well-formed:

$ python scripts/validate.py bundles/my-domain-kit

The validator checks:

Bundle manifest completeness
All referenced skills exist in skills/ directory
Meta-skill is properly defined
No circular dependencies between bundles
Conflict resolution rules reference valid skills
Shared resources are accessible

🎯 Example: Web Dev Kit

Let's look at a real example from OMNISKILL:

bundles/web-dev-kit/bundle.yaml

name: web-dev-kit
version: 1.0.0
description: "Complete web development toolkit"
author: omniskill

skills:
  - frontend-design
  - react-best-practices
  - vercel-react-best-practices
  - web-design-guidelines
  - backend-development

meta-skill: web-fullstack-expert

conflict-resolution:
  - when: "react-best-practices AND vercel-react-best-practices both match"
    prefer: vercel-react-best-practices
    reason: "Vercel-specific practices override general React practices"
  
  - when: "frontend-design AND web-design-guidelines both match"
    prefer: web-design-guidelines
    reason: "web-design-guidelines is more comprehensive"

💡

Routing Logic

The web-fullstack-expert meta-skill knows when to use frontend-design for UI work, react-best-practices for React code, and backend-development for API work—and how to coordinate them for full-stack features.

🔧 Installing Your Bundle

Once validated, install your bundle to all detected platforms:

$ # Install the bundle
$ python scripts/install.py --bundle my-domain-kit

# This installs:
# - All constituent skills (skill-a, skill-b, skill-c)
# - The meta-skill (my-domain-expert)
# - Shared resources (accessible to all skills)

Bundle Operations

# Update an existing bundle
python scripts/install.py --bundle my-domain-kit --update

# Uninstall a bundle (removes all constituent skills)
python scripts/install.py --bundle my-domain-kit --uninstall

# List all available bundles
python scripts/list-bundles.py

✨ Bundle Best Practices

1. Cohesive Grouping

Bundle skills that belong to the same domain and naturally work together. Don't create "kitchen sink" bundles.

2. Clear Meta-Skill Routing

The meta-skill's routing logic should be explicit and unambiguous. Document edge cases.

3. Comprehensive Shared Resources

Put domain knowledge that ALL skills need in shared-resources. Avoid duplicating content across individual skill resources.

4. Explicit Conflict Resolution

If skills have overlapping triggers, define clear precedence rules in conflict-resolution.

5. Version Coordination

When updating a bundle, ensure all constituent skills are compatible versions.

6. Test as a Unit

Test the bundle as a whole, not just individual skills. Verify routing works correctly.

📦 Existing Bundles

OMNISKILL includes several pre-built bundles you can use as references:

Bundle	Skills	Use Case
`web-dev-kit`	5 skills	Full-stack web development
`godot-kit`	4 skills	Godot game development
`data-science-kit`	6 skills	Data analysis and ML
`devops-kit`	5 skills	Infrastructure and deployment
`meta-kit`	5 skills	Self-customization skills (add-skill, add-bundle, add-agent, add-adapter, rename-project)

💡

Meta-Kit Bundle

The meta-kit bundle includes the self-customization skills (add-skill, add-bundle, add-agent, add-adapter, rename-project) for extending OMNISKILL itself.

See the bundles directory for all available bundles and their source code.

🤖 Self-Customization

Instead of manually creating bundles, use the AI-guided approach:

💡

Prompt: "Follow the add-bundle skill to create a bundle for [domain]"

The add-bundle skill guides you through:

Identifying constituent skills
Creating the bundle structure
Writing the meta-skill
Defining conflict resolution rules
Validation and installation

✓

Guided Process

The add-bundle skill provides interactive checklists and validation at each stage, making bundle creation straightforward even for complex domain kits.