obra · gwpl · Feb 5, 2026 · Feb 5, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "superpowers-developing-for-claude-code",
-      "description": "Skills for developing Claude Code plugins, skills, and MCP servers. Includes complete official documentation with self-update.",
-      "version": "0.3.1",
+      "description": "Skills for developing Claude Code plugins, skills, and MCP servers. Includes complete official documentation with self-update and multi-provider architecture patterns.",
+      "version": "0.4.0",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,13 +1,13 @@
 {
   "name": "superpowers-developing-for-claude-code",
-  "version": "0.3.1",
-  "description": "Skills and resources for developing Claude Code plugins, skills, MCP servers, and extensions. Includes comprehensive official documentation and self-update mechanism.",
+  "version": "0.4.0",
+  "description": "Skills and resources for developing Claude Code plugins, skills, MCP servers, and extensions. Includes comprehensive official documentation, self-update mechanism, and multi-provider architecture patterns.",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"
   },
   "homepage": "https://github.com/obra/superpowers-developing-for-claude-code",
   "repository": "https://github.com/obra/superpowers-developing-for-claude-code",
   "license": "MIT",
-  "keywords": ["claude-code", "plugin-development", "skills", "mcp", "documentation", "development"]
+  "keywords": ["claude-code", "plugin-development", "skills", "mcp", "documentation", "development", "multi-provider", "cross-platform"]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,27 @@ All notable changes to the superpowers-developing-for-claude-code plugin will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-05
+
+### Added
+- New `multi-provider-plugins` skill for cross-provider plugin architecture
+  - Architecture overview with adapter pattern explanation
+  - Provider-specific adapters guide (Claude Code, Codex, OpenCode)
+  - Comprehensive tool mapping reference across providers
+  - Bootstrap injection patterns for session-start skill loading
+  - Shared skills library structure and best practices
+  - Skill shadowing and priority system documentation
+- Reference documentation in `skills/multi-provider-plugins/references/`:
+  - `architecture-overview.md` - Multi-provider design patterns
+  - `provider-adapters.md` - How to create adapters for each provider
+  - `tool-mapping.md` - Tool equivalents across Claude Code, Codex, OpenCode
+  - `bootstrap-patterns.md` - Session-start injection implementations
+  - `shared-skills-library.md` - Portable skill structure and discovery
+
+### Changed
+- Updated plugin description to mention multi-provider support
+- Added `multi-provider` and `cross-platform` keywords
+
 ## [0.3.1] - 2025-12-03
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -36,6 +36,23 @@ Streamlined workflows and patterns for creating Claude Code plugins.
 
 Use this skill to make plugin development faster and easier - it synthesizes official docs into actionable steps.
 
+#### multi-provider-plugins
+Architecture patterns for making Claude Code plugins work with other AI coding assistants.
+
+- **Cross-provider architecture** - Single skills library with provider-specific adapters
+- **Provider adapters** - How to create integrations for Codex, OpenCode, and others
+- **Tool mapping reference** - Translate Claude Code tools to provider equivalents
+- **Bootstrap patterns** - Session-start injection for each provider
+- **Shared skills library** - Structure portable skills that work everywhere
+
+Supported providers:
+
+- Claude Code (native plugin)
+- OpenAI Codex (CLI adapter + AGENTS.md)
+- OpenCode (plugin with symlinks)
+
+Use this skill when you want your plugin to work beyond Claude Code.
+
 ## Installation
 
 ### Development Mode
@@ -85,14 +102,18 @@ superpowers-developing-for-claude-code/
 │   │   ├── scripts/
 │   │   │   └── update_docs.js
 │   │   └── references/       # 42 documentation files
-│   └── developing-claude-code-plugins/
-│       └── SKILL.md          # Plugin development workflows
+│   ├── developing-claude-code-plugins/
+│   │   └── SKILL.md          # Plugin development workflows
+│   └── multi-provider-plugins/
+│       ├── SKILL.md          # Cross-provider architecture
+│       └── references/       # Provider adapters, tool mapping, etc.
 └── README.md
 ```
 
 ### Future Skills
 
 Skills to consider adding:
+
 - `testing-claude-code-plugins` - Testing strategies and validation
 - `distributing-plugins` - Publishing and marketplace guidelines
 - `writing-mcp-servers` - MCP server development guide

diff --git a/skills/multi-provider-plugins/SKILL.md b/skills/multi-provider-plugins/SKILL.md
@@ -0,0 +1,212 @@
+---
+name: multi-provider-plugins
+description: Use when making Claude Code plugins compatible with other AI coding assistants (Codex, OpenCode, Aider, etc.) - provides architecture patterns, tool mappings, and adapter strategies for cross-provider portability
+---
+
+# Multi-Provider Plugin Architecture
+
+## Overview
+
+This skill provides patterns for making your Claude Code plugins work across multiple AI coding assistants. Instead of maintaining separate codebases, you can create a **single shared skills library** with **provider-specific adapters**.
+
+**For Claude Code-specific plugin development**, use the `developing-claude-code-plugins` skill.
+
+## When to Use
+
+* You want your plugin/skills to work with Claude Code AND other AI assistants
+* You're targeting OpenAI Codex, OpenCode, Aider, or similar tools
+* You need to create provider-specific adapters for your skills
+* You want to understand tool mapping patterns across providers
+* You're designing a shared skills architecture
+
+## Quick Reference
+
+| Need to... | Read This |
+|-----------|-----------|
+| Understand the architecture | `references/architecture-overview.md` |
+| Create provider adapters | `references/provider-adapters.md` |
+| Map tools across providers | `references/tool-mapping.md` |
+| Implement bootstrap injection | `references/bootstrap-patterns.md` |
+| Structure shared skills | `references/shared-skills-library.md` |
+
+## Core Architecture Pattern
+
+```
+your-plugin/
+├── .claude-plugin/           # Claude Code native plugin
+│   ├── plugin.json
+│   └── marketplace.json
+├── .codex/                   # OpenAI Codex adapter
+│   ├── INSTALL.md
+│   ├── bootstrap.md
+│   └── cli-tool              # Node.js CLI for skill invocation
+├── .opencode/                # OpenCode adapter
+│   ├── INSTALL.md
+│   └── plugins/
+│       └── your-plugin.js
+├── lib/                      # Shared utilities
+│   └── skills-core.js        # Cross-provider skill discovery
+├── skills/                   # SHARED skills library
+│   ├── skill-one/
+│   │   └── SKILL.md
+│   └── skill-two/
+│       └── SKILL.md
+└── hooks/                    # Claude Code hooks
+    ├── hooks.json
+    └── session-start.sh
+```
+
+**Key Principle:** Single `/skills/` directory shared by ALL providers. Provider-specific code lives in adapter directories.
+
+## The Three Pillars
+
+### 1. Shared Skills Library
+
+Write skills once in `/skills/`. All providers read from this location.
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [benefit]
+---
+
+# My Skill
+
+[Content written for Claude Code tools]
+```
+
+### 2. Provider-Specific Adapters
+
+Each provider has its own integration layer:
+
+| Provider | Adapter Location | Bootstrap Method |
+|----------|-----------------|------------------|
+| Claude Code | `.claude-plugin/` | Hook: `session-start.sh` |
+| Codex | `.codex/` | Manual AGENTS.md + CLI tool |
+| OpenCode | `.opencode/plugins/` | Plugin with system prompt hook |
+
+### 3. Tool Mapping
+
+Skills reference Claude Code tools. Adapters provide mappings:
+
+| Claude Code Tool | Codex Equivalent | OpenCode Equivalent |
+|-----------------|------------------|---------------------|
+| `Skill` | Custom CLI: `your-cli use-skill` | Native `skill` tool |
+| `TodoWrite` | `update_plan` | `update_plan` |
+| `Task` (subagents) | Not available (do work directly) | `@mention` syntax |
+| `Read`, `Write`, `Edit` | Native file tools | Native file tools |
+
+## Quick Start: Adding Multi-Provider Support
+
+### Phase 1: Structure Your Plugin
+
+Ensure your Claude Code plugin has skills in a `/skills/` directory at the root.
+
+### Phase 2: Create Codex Adapter
+
+1. Create `.codex/INSTALL.md` with installation instructions
+2. Create `.codex/bootstrap.md` with tool mappings
+3. Create `.codex/your-cli` Node.js script for skill invocation
+
+### Phase 3: Create OpenCode Adapter
+
+1. Create `.opencode/INSTALL.md` with symlink instructions
+2. Create `.opencode/plugins/your-plugin.js` with system prompt hook
+
+### Phase 4: Add Shared Core Library
+
+Create `lib/skills-core.js` with:
+
+* `findSkillsInDir()` - Recursive skill discovery
+* `extractFrontmatter()` - YAML frontmatter parsing
+* `resolveSkillPath()` - Handle skill shadowing/overrides
+
+### Phase 5: Document Everything
+
+* Provider-specific READMEs in each adapter directory
+* Clear tool mapping tables
+* Installation instructions for each platform
+
+## Critical Rules
+
+1. **Never duplicate skills** - One canonical location in `/skills/`
+2. **Skills reference Claude Code tools** - Adapters handle mapping
+3. **Bootstrap always injects a "using" skill** - Teaches the agent about available skills
+4. **Support skill shadowing** - Personal/project skills override plugin skills
+5. **Use `${CLAUDE_PLUGIN_ROOT}`** - Portable paths in Claude Code hooks
+
+## Skill Shadowing Priority
+
+All providers should implement this override order:
+
+1. **Project skills** (`.opencode/skills/` or project-local) - Highest priority
+2. **Personal skills** (`~/.config/{provider}/skills/`) - Medium priority
+3. **Plugin skills** (from your repository) - Lowest priority
+
+This lets users customize behavior without modifying your plugin.
+
+## Bootstrap Pattern
+
+Every provider needs to inject a "meta-skill" at session start that:
+
+1. Explains the skills system to the agent
+2. Lists available skills with descriptions
+3. Provides tool mappings for that specific provider
+4. Sets mandatory rules (e.g., "If a skill applies, you MUST use it")
+
+See `references/bootstrap-patterns.md` for implementation details.
+
+## Resources in This Skill
+
+* `references/architecture-overview.md` - Detailed architecture explanation
+* `references/provider-adapters.md` - How to create each adapter type
+* `references/tool-mapping.md` - Comprehensive tool mapping reference
+* `references/bootstrap-patterns.md` - Bootstrap injection implementations
+* `references/shared-skills-library.md` - Structuring portable skills
+
+## Cross-References
+
+* `developing-claude-code-plugins` - Claude Code-specific plugin development
+* `working-with-claude-code` - Official Claude Code documentation
+
+## Best Practices
+
+**Do:**
+
+* Test your skills on each target provider
+* Document provider-specific limitations clearly
+* Use feature detection, not provider detection
+* Keep adapters thin - logic belongs in shared code
+
+**Don't:**
+
+* Embed provider-specific code in skills
+* Assume all tools exist on all providers
+* Skip the bootstrap injection step
+* Forget to update all adapters when adding skills
+
+## Workflow Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MULTI-PROVIDER WORKFLOW                  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. DESIGN         Plan shared skills architecture          │
+│        ↓                                                    │
+│  2. BUILD          Create Claude Code plugin first          │
+│        ↓                                                    │
+│  3. EXTRACT        Move shared logic to /lib/               │
+│        ↓                                                    │
+│  4. ADAPT          Create provider-specific adapters        │
+│        ↓                                                    │
+│  5. BOOTSTRAP      Implement session-start injection        │
+│        ↓                                                    │
+│  6. MAP            Document tool mappings per provider      │
+│        ↓                                                    │
+│  7. TEST           Verify on each target provider           │
+│        ↓                                                    │
+│  8. DOCUMENT       Clear installation for each provider     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```