Creating Your Own Bundle

Creating a bundle is straightforward - it's just a markdown file with YAML frontmatter. This guide walks you through creating your first bundle.

Quick Start: Minimal Bundle

Create a file called bundle.md:

---
bundle:
  name: my-first-bundle
  version: 1.0.0
  description: My custom Amplifier configuration

includes:
  - bundle: foundation
---

# My Custom Bundle

You are a helpful AI assistant customized for my workflow.

Run it:

amplifier run --bundle ./bundle.md "Hello!"

That's it! You've created a bundle that includes all foundation capabilities plus your custom instructions.

Step-by-Step: Building a Custom Bundle

1. Start with Foundation

Most bundles build on foundation:

---
bundle:
  name: my-bundle
  version: 1.0.0

includes:
  - bundle: foundation
---

This gives you all core tools (filesystem, bash, web, search), standard hooks (logging, streaming UI), and the basic orchestrator.

2. Add Custom Modules

Add your own tools, hooks, or providers:

tools:
  - module: tool-my-custom
    source: git+https://github.com/you/amplifier-module-tool-my-custom@main
    config:
      api_key: ${MY_API_KEY}  # Environment variable

hooks:
  - module: hooks-my-notifications
    source: file:///absolute/path/to/local/module

3. Override Provider

Change which AI provider to use:

providers:
  - module: provider-openai
    source: git+https://github.com/microsoft/amplifier-module-provider-openai@main
    config:
      default_model: gpt-5.1
      priority: 1

4. Add Custom Agents

Define specialized agents for your domain:

agents:
  - agent: my-domain-expert
    file: agents/domain-expert.md

Create agents/domain-expert.md:

---
meta:
  name: my-domain-expert
  description: Expert in my specific domain
---

You are a domain expert specializing in...

5. Add Context Resources

Include domain knowledge and instructions:

context:
  - file: context/domain-knowledge.md
  - file: context/coding-standards.md

Reference them in your system prompt with @mentions:

---
# (frontmatter above)
---

# My Bundle

@my-bundle:context/domain-knowledge.md

Follow these coding standards:
@my-bundle:context/coding-standards.md

Complete Example

---
bundle:
  name: data-science-bundle
  version: 2.1.0
  description: Data science workflow with Jupyter and plotting support

includes:
  - bundle: foundation

tools:
  - module: tool-jupyter
    source: git+https://github.com/microsoft/amplifier-module-tool-jupyter@main
  - module: tool-plotting
    source: git+https://github.com/you/amplifier-module-tool-plotting@main

providers:
  - module: provider-anthropic
    source: git+https://github.com/microsoft/amplifier-module-provider-anthropic@main
    config:
      default_model: claude-sonnet-4-5
      priority: 1

agents:
  - agent: data-analyst
    file: agents/data-analyst.md
  - agent: visualization-expert
    file: agents/viz-expert.md

context:
  - file: context/pandas-best-practices.md
  - file: context/visualization-guidelines.md
---

# Data Science Assistant

You are an expert data science assistant specializing in Python, pandas, and data visualization.

## Your Capabilities

@data-science-bundle:context/pandas-best-practices.md

@data-science-bundle:context/visualization-guidelines.md

## Your Approach

1. Understand the data first
2. Clean and validate
3. Analyze with clear explanations
4. Visualize insights effectively

Best Practices

Module Sources
Always specify explicit source: URLs for modules. This makes bundles self-contained and reproducible.
Versioning
Use semantic versioning (1.0.0) for your bundles. Increment when you make changes that might affect users.
Documentation
The markdown body is documentation for you (the bundle author) and system instructions for the agent. Write clearly for both audiences.

Testing Your Bundle

# Run locally
amplifier run --bundle ./bundle.md "Test prompt"

# Or add to registry
amplifier bundle add ./bundle.md
amplifier bundle use my-bundle
amplifier run "Test prompt"

Sharing Your Bundle

Once your bundle works, share it via Git:

# Push to GitHub
git init
git add bundle.md agents/ context/
git commit -m "Initial bundle"
git remote add origin https://github.com/you/my-amplifier-bundle
git push -u origin main

# Others can use it:
amplifier run --bundle git+https://github.com/you/my-amplifier-bundle@main

Advanced Topics

Examples to Study