https://github.com/michaeljabbour/amplifier-modulebuilder-skill
Agent Skill for building production-ready amplifier-foundation modules
https://github.com/michaeljabbour/amplifier-modulebuilder-skill
agent-skills amplifier-foundation amplifier-modules claude-code module-development python
Last synced: about 2 months ago
JSON representation
Agent Skill for building production-ready amplifier-foundation modules
- Host: GitHub
- URL: https://github.com/michaeljabbour/amplifier-modulebuilder-skill
- Owner: michaeljabbour
- License: mit
- Created: 2025-12-22T03:55:37.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T04:31:46.000Z (about 2 months ago)
- Last Synced: 2025-12-23T14:59:25.644Z (about 2 months ago)
- Topics: agent-skills, amplifier-foundation, amplifier-modules, claude-code, module-development, python
- Size: 75.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:**
```bash
/plugin install https://github.com/michaeljabbour/amplifier-modulebuilder-skill
```
**OpenAI Codex CLI (local):**
```bash
# 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](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
```python
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](skills/amplifier-modulebuilder-skill/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](skills/amplifier-modulebuilder-skill/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/](skills/amplifier-modulebuilder-skill/references/):
- **[MODULE_TYPES.md](skills/amplifier-modulebuilder-skill/references/MODULE_TYPES.md)** - Deep dive on all 5 module types (~800 lines)
- **[DEVELOPMENT_WORKFLOW.md](skills/amplifier-modulebuilder-skill/references/DEVELOPMENT_WORKFLOW.md)** - Step-by-step process (~600 lines)
- **[TESTING_GUIDE.md](skills/amplifier-modulebuilder-skill/references/TESTING_GUIDE.md)** - Comprehensive testing (~700 lines)
- **[REPOSITORY_RULES.md](skills/amplifier-modulebuilder-skill/references/REPOSITORY_RULES.md)** - Awareness constraints (~500 lines)
- **[EXAMPLES.md](skills/amplifier-modulebuilder-skill/references/EXAMPLES.md)** - 4 complete working examples (~1000 lines)
- **[API_PATTERNS.md](skills/amplifier-modulebuilder-skill/references/API_PATTERNS.md)** - Common implementation patterns (~400 lines)
- **[MODULAR_BUILDER.md](skills/amplifier-modulebuilder-skill/references/MODULAR_BUILDER.md)** - AI-assisted development (~600 lines)
- **[CONTRIBUTING.md](skills/amplifier-modulebuilder-skill/references/CONTRIBUTING.md)** - Community guidelines (~300 lines)
## Learning Paths
### 🌱 Beginner (60 minutes)
1. Read [SKILL.md](skills/amplifier-modulebuilder-skill/SKILL.md) sections 1-3 (15 min)
2. Study [EXAMPLES.md](skills/amplifier-modulebuilder-skill/references/EXAMPLES.md) (15 min)
3. Follow [DEVELOPMENT_WORKFLOW.md](skills/amplifier-modulebuilder-skill/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](skills/amplifier-modulebuilder-skill/references/MODULE_TYPES.md)
2. Apply patterns from [API_PATTERNS.md](skills/amplifier-modulebuilder-skill/references/API_PATTERNS.md)
3. Achieve 85% coverage with [TESTING_GUIDE.md](skills/amplifier-modulebuilder-skill/references/TESTING_GUIDE.md)
4. Publish following [CONTRIBUTING.md](skills/amplifier-modulebuilder-skill/references/CONTRIBUTING.md)
### 🌳 Advanced
1. Master [REPOSITORY_RULES.md](skills/amplifier-modulebuilder-skill/references/REPOSITORY_RULES.md) constraints
2. Use [MODULAR_BUILDER.md](skills/amplifier-modulebuilder-skill/references/MODULAR_BUILDER.md) for AI assistance
3. Design complex architectures
4. Contribute to ecosystem
## Related Projects
### Sister Skills
- **[amplifier-cli-skill](https://github.com/michaeljabbour/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](https://github.com/michaeljabbour/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](https://github.com/microsoft/amplifier)** - Main framework repository
- **[amplifier-core](https://github.com/microsoft/amplifier-core)** - Core library (execution engine)
- **[amplifier-foundation](https://github.com/microsoft/amplifier-foundation)** - Foundation library (configuration/composition layer)
- **[Amplifier Modules](https://github.com/microsoft/amplifier/blob/main/docs/MODULES.md)** - Module catalog (36+ available modules)
## Quick Reference
### Create Module
```bash
mkdir amplifier-module-{type}-{name}
cd amplifier-module-{type}-{name}
# Follow SKILL.md section 5 for structure
```
### Test Locally
```bash
export AMPLIFIER_MODULE_{TYPE}_{NAME}=$(pwd)
uv run pytest tests/ --cov
```
### Publish
```bash
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
```yaml
---
tools:
- git+https://github.com/you/amplifier-module-tool-name.git@v0.1.0
---
```
## Community
- **[Discussions](https://github.com/microsoft/amplifier-foundation/discussions)** - Ask questions
- **[Issues](https://github.com/microsoft/amplifier-foundation/issues)** - Report bugs
- **[Module Registry](https://github.com/topics/amplifier-module)** - Discover modules
## Contributing
See [CONTRIBUTING.md](skills/amplifier-modulebuilder-skill/references/CONTRIBUTING.md) for guidelines on contributing to this skill or the module ecosystem.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Version
**1.0.0** - Plugin-enabled skill with comprehensive "bricks and studs" module architecture documentation.
---
**Start building**: Open [SKILL.md](skills/amplifier-modulebuilder-skill/SKILL.md) and begin your journey! 🚀