Amplifier Module Builder Skill

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

What This Skill Provides

This skill teaches how to 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)

Installation

Quick install:

/plugin install https://github.com/michaeljabbour/amplifier-modulebuilder-skill

OpenAI Codex CLI (local):

# from the repo root
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills"
ln -s "$(pwd)/skills/amplifier-modulebuilder-skill" "$CODEX_HOME/skills/amplifier-modulebuilder-skill"
# restart Codex to pick up new skills

For detailed installation instructions, troubleshooting, and alternative methods, see INSTALLATION.md.

Once installed, Claude Code will automatically use this skill when you:

• Ask about building Amplifier modules
• Work with amplifier-foundation module development
• Need help with module architecture patterns
• Request guidance on testing and publishing modules

Repository Structure

amplifier-modulebuilder-skill/
├── .claude-plugin/
│   └── plugin.json                      # Plugin metadata
├── skills/
│   └── amplifier-modulebuilder-skill/
│       ├── SKILL.md                     # Main skill definition (47KB)
│       └── references/                  # Deep-dive documentation
│           ├── API_PATTERNS.md          # Common implementation patterns
│           ├── CONTRIBUTING.md          # Community guidelines
│           ├── DEVELOPMENT_WORKFLOW.md  # Step-by-step process
│           ├── EXAMPLES.md              # 4 complete working examples
│           ├── MODULAR_BUILDER.md       # AI-assisted development
│           ├── MODULE_TYPES.md          # Deep dive on all 5 types
│           ├── REPOSITORY_RULES.md      # Awareness constraints
│           ├── TESTING_GUIDE.md         # Comprehensive testing
│           └── README.md                # References navigation
├── LICENSE                               # MIT License
├── INSTALLATION.md                       # Installation guide
└── README.md                             # This file

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.

Quick Start Example

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

Documentation

Primary Documentation

• SKILL.md - Complete skill with 13 sections (~2000 lines)
  • 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 skills/amplifier-modulebuilder-skill/references/:

• 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)

Learning Paths

🌱 Beginner (60 minutes)

1. Read SKILL.md sections 1-3 (15 min)
2. Study EXAMPLES.md (15 min)
3. Follow 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 Projects

Sister Skills

• amplifier-cli-skill - Agent Skill for building CLI applications with amplifier-foundation
  • Learn how to compose modules into full applications
  • Session orchestration and execution patterns
  • Production patterns and best practices

Reference Implementations

• amplifier-simplecli - Production CLI application built with amplifier-foundation
  • See modules in action in a real application
  • Example of bundle composition
  • Memory system integration
  • Interactive terminal UI

Learning Path: Build modules with this skill → Compose them into apps with amplifier-cli-skill → See them in action in amplifier-simplecli

Amplifier Ecosystem

This skill is part of the broader Amplifier ecosystem:

Core Repositories

• amplifier - Main framework repository
• amplifier-core - Core library (execution engine)
• amplifier-foundation - Foundation library (configuration/composition layer)
• Amplifier Modules - Module catalog (36+ available modules)

Quick Reference

Create Module

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

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 Bundle

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

Community

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

Contributing

See CONTRIBUTING.md for guidelines on contributing to this skill or the module ecosystem.

License

MIT License - see LICENSE file for details.

Version

1.0.0 - Plugin-enabled skill with comprehensive "bricks and studs" module architecture documentation.

---

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