README.md

Amplifier Module Builder Skill

Agent Skill for building production-ready amplifier-foundation modules

This skill teaches the "bricks and studs" architecture for creating self-contained, regeneratable modules that extend AI agent capabilities.

What You'll Learn

Build five types of amplifier-foundation modules:

• Tool modules - Extend agent capabilities (file systems, APIs, calculations)
• Hook modules - Observe lifecycle events (logging, metrics, approval gates)
• Provider modules - Connect to AI model APIs (Anthropic, OpenAI, custom models)
• Context modules - Manage conversation state (memory, persistence, injection)
• Orchestrator modules - Control execution flow (streaming, turn-taking, tool calls)

Quick Start

Prerequisites

• Python 3.11 or higher
• uv package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
• git for version control
• amplifier-foundation installed

Build Your First Module (5 Minutes)

Follow the guide in SKILL.md to create a simple tool module:

# Create structure
mkdir amplifier-module-tool-uppercase
cd amplifier-module-tool-uppercase

# Follow SKILL.md guide to implement mount() and get_schema()

# Test locally
export AMPLIFIER_MODULE_TOOL_UPPERCASE=$(pwd)
uv run pytest tests/

Next Steps

1. Read SKILL.md for complete guide (~2000 lines)
2. Study references/EXAMPLES.md for working code
3. Follow references/DEVELOPMENT_WORKFLOW.md step-by-step

Contents

Primary Documentation

• SKILL.md - Complete skill with 13 sections
  • Introduction and philosophy
  • Module types overview
  • Quick start guide
  • Core development workflow
  • Testing requirements (60/30/10 pyramid)
  • Repository awareness rules
  • Common patterns
  • Complete example walkthrough

Deep-Dive References

All in references/ directory:

• MODULE_TYPES.md - Deep dive on all 5 module types (~800 lines)
• DEVELOPMENT_WORKFLOW.md - Step-by-step process (~600 lines)
• TESTING_GUIDE.md - Comprehensive testing (~700 lines)
• REPOSITORY_RULES.md - Awareness constraints (~500 lines)
• EXAMPLES.md - 4 complete working examples (~1000 lines)
• API_PATTERNS.md - Common implementation patterns (~400 lines)
• MODULAR_BUILDER.md - AI-assisted development (~600 lines)
• CONTRIBUTING.md - Community guidelines (~300 lines)

See references/README.md for navigation guide.

Key Concepts

"Bricks and Studs" Architecture

Like LEGO bricks:

• Studs (public): mount() function, get_schema(), README.md
• Bricks (private): Implementation details, internal classes

Modules are:

• Self-contained: No hidden dependencies
• Regeneratable: Can be rebuilt from README
• Composable: Connect through coordinator
• Predictable: Same inputs → same outputs

Repository Awareness

The Golden Rule: "Only reference declared dependencies"

✅ Can reference: Python stdlib, declared dependencies, coordinator ❌ Cannot reference: Other modules directly, undeclared dependencies

Testing Pyramid

        /\
       /  \
      / E2E \    10%
     /------\
    /        \
   / Integrn  \  30%
  /------------\
 /              \
/   Unit Tests   \ 60%
------------------

Target: 85% coverage overall, 100% for critical paths.

Examples

Tool Module

async def mount(coordinator, config):
    async def uppercase(text: str) -> str:
        """Convert text to uppercase."""
        return text.upper()

    return {"uppercase": uppercase}

def get_schema() -> dict:
    return {
        "uppercase": {
            "description": "Convert text to uppercase",
            "parameters": {
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to convert"}
                },
                "required": ["text"]
            }
        }
    }

See references/EXAMPLES.md for 4 complete examples.

Module Types Comparison

Type	Purpose	Entry Point	Example
Orchestrator	Control execution loop	amplifier.orchestrators	loop-streaming
Provider	Connect to AI models	amplifier.providers	anthropic
Tool	Extend capabilities	amplifier.tools	filesystem
Context	Manage state	amplifier.contexts	memory
Hook	Observe events	amplifier.hooks	logging

Learning Paths

🌱 Beginner (60 minutes)

1. Read SKILL.md sections 1-3 (15 min)
2. Study references/EXAMPLES.md (15 min)
3. Follow references/DEVELOPMENT_WORKFLOW.md (20 min)
4. Build your first module (10 min)

🌿 Intermediate

1. Deep dive on your module type in MODULE_TYPES.md
2. Apply patterns from API_PATTERNS.md
3. Achieve 85% coverage with TESTING_GUIDE.md
4. Publish following CONTRIBUTING.md

🌳 Advanced

1. Master REPOSITORY_RULES.md constraints
2. Use MODULAR_BUILDER.md for AI assistance
3. Design complex architectures
4. Contribute to ecosystem

Related Skills

• amplifier-cli-skill - Build CLI applications with amplifier-foundation

External Resources

• amplifier-foundation - Core modules framework
• amplifier-core - Kernel and coordinator
• Agent Skills - Skills specification
• Community Modules - Browse published modules

Community

• Discussions - Ask questions
• Issues - Report bugs
• Module Registry - Discover modules

License

MIT License - See skill content for details.

---

Quick Reference

Create Module

mkdir amplifier-module-{type}-{name}
cd amplifier-module-{type}-{name}
# Follow SKILL.md section 5

Test Locally

export AMPLIFIER_MODULE_{TYPE}_{NAME}=$(pwd)
uv run pytest tests/ --cov

Publish

git init && git add . && git commit -m "feat: initial module"
gh repo create amplifier-module-{type}-{name} --public
git push -u origin main
git tag v0.1.0 && git push origin v0.1.0

Use in Profile

---
tools:
  - git+https://github.com/you/amplifier-module-tool-name.git@v0.1.0
---

---

Start building: Open SKILL.md and begin your journey! 🚀