diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index dfb18a6..ec5bac9 100644
--- 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
index e3d63b8..61e6742 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "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"
@@ -9,5 +9,5 @@
   "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
index 16e78fa..2972175 100644
--- 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
index eada6f2..38579ce 100644
--- 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
new file mode 100644
index 0000000..563dbe7
--- /dev/null
+++ 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     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
diff --git a/skills/multi-provider-plugins/references/architecture-overview.md b/skills/multi-provider-plugins/references/architecture-overview.md
new file mode 100644
index 0000000..60bc81b
--- /dev/null
+++ b/skills/multi-provider-plugins/references/architecture-overview.md
@@ -0,0 +1,224 @@
+# Multi-Provider Architecture Overview
+
+## The Problem
+
+You've built a great Claude Code plugin with useful skills. But your team also uses:
+
+* OpenAI Codex for some workflows
+* OpenCode as an open-source alternative
+* Potentially other AI coding assistants
+
+Maintaining separate codebases is painful. You want ONE set of skills that works everywhere.
+
+## The Solution: Adapter Pattern
+
+```
+                    ┌─────────────────────────┐
+                    │     SHARED SKILLS       │
+                    │      /skills/           │
+                    │  (Write once, use many) │
+                    └───────────┬─────────────┘
+                                │
+            ┌───────────────────┼───────────────────┐
+            ▼                   ▼                   ▼
+    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+    │  Claude Code  │   │    Codex      │   │   OpenCode    │
+    │   Adapter     │   │   Adapter     │   │   Adapter     │
+    │ .claude-plugin│   │   .codex/     │   │  .opencode/   │
+    └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
+            │                   │                   │
+            ▼                   ▼                   ▼
+    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+    │  Claude Code  │   │    Codex      │   │   OpenCode    │
+    │    Agent      │   │    Agent      │   │    Agent      │
+    └───────────────┘   └───────────────┘   └───────────────┘
+```
+
+## Directory Structure
+
+```
+your-multi-provider-plugin/
+├── .claude-plugin/              # Claude Code native integration
+│   ├── plugin.json              # Plugin manifest
+│   └── marketplace.json         # Optional: for marketplace distribution
+│
+├── .codex/                      # OpenAI Codex integration
+│   ├── INSTALL.md               # Installation instructions
+│   ├── bootstrap.md             # Tool mappings & skill list
+│   └── your-plugin-codex        # Node.js CLI tool
+│
+├── .opencode/                   # OpenCode integration
+│   ├── INSTALL.md               # Installation with symlinks
+│   └── plugins/
+│       └── your-plugin.js       # OpenCode plugin file
+│
+├── hooks/                       # Claude Code event hooks
+│   ├── hooks.json               # Hook configuration
+│   ├── session-start.sh         # Bootstrap injection
+│   └── run-hook.cmd             # Cross-platform wrapper (if needed)
+│
+├── lib/                         # Shared JavaScript utilities
+│   └── skills-core.js           # Skill discovery & parsing
+│
+├── skills/                      # THE SHARED SKILLS LIBRARY
+│   ├── using-your-plugin/       # Meta-skill (bootstrap content)
+│   │   └── SKILL.md
+│   ├── skill-one/
+│   │   └── SKILL.md
+│   └── skill-two/
+│       ├── SKILL.md
+│       └── references/
+│           └── detailed-guide.md
+│
+├── docs/                        # Extended documentation
+│   ├── README.codex.md
+│   ├── README.opencode.md
+│   └── windows/
+│       └── polyglot-hooks.md
+│
+└── README.md                    # Main documentation
+```
+
+## What Each Component Does
+
+### `/skills/` - The Shared Library
+
+This is the heart of your multi-provider plugin. All skills live here.
+
+* Written using Claude Code tool conventions
+* Provider adapters translate tool references
+* Single source of truth for all platforms
+
+### `.claude-plugin/` - Native Claude Code
+
+Standard Claude Code plugin structure:
+
+* `plugin.json` - Manifest with metadata
+* Skills automatically discovered from `/skills/`
+* Hooks loaded from `/hooks/hooks.json`
+
+### `.codex/` - OpenAI Codex Adapter
+
+Codex doesn't have a plugin system, so you provide:
+
+* CLI tool that users invoke via AGENTS.md instructions
+* Bootstrap markdown that teaches Codex about your skills
+* Manual setup (user adds reference to their AGENTS.md)
+
+### `.opencode/` - OpenCode Adapter
+
+OpenCode has a plugin system with symlink-based skill discovery:
+
+* JavaScript plugin that hooks into system prompt
+* Symlinks connect to shared `/skills/` directory
+* Can leverage OpenCode's native `skill` tool
+
+### `/hooks/` - Event Handlers
+
+Claude Code hooks that power the bootstrap injection:
+
+* `session-start.sh` runs on every new session
+* Reads and injects the "using-your-plugin" meta-skill
+* Teaches Claude about available skills automatically
+
+### `/lib/` - Shared Utilities
+
+JavaScript/Node.js code used by multiple adapters:
+
+* Skill discovery (recursive directory scanning)
+* YAML frontmatter parsing
+* Skill path resolution with shadowing support
+* Update checking (git-based)
+
+## The Bootstrap Injection Pattern
+
+Every provider needs to "teach" the AI about your skills at session start:
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   SESSION START                        │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│  Claude Code:                                          │
+│    hooks/session-start.sh                              │
+│         ↓                                              │
+│    Reads: skills/using-your-plugin/SKILL.md            │
+│         ↓                                              │
+│    Outputs: JSON with skill content                    │
+│         ↓                                              │
+│    Agent sees: Full skill system documentation         │
+│                                                        │
+│  Codex:                                                │
+│    User's AGENTS.md references bootstrap.md            │
+│         ↓                                              │
+│    Codex reads: .codex/bootstrap.md                    │
+│         ↓                                              │
+│    Agent sees: Skills + Codex-specific tool mappings   │
+│                                                        │
+│  OpenCode:                                             │
+│    Plugin's system.transform hook fires                │
+│         ↓                                              │
+│    Reads: skills/using-your-plugin/SKILL.md            │
+│         ↓                                              │
+│    Agent sees: Skills + OpenCode-specific mappings     │
+│                                                        │
+└────────────────────────────────────────────────────────┘
+```
+
+## Why This Architecture Works
+
+### 1. Single Source of Truth
+
+Skills are maintained in one place. Updates automatically propagate to all providers.
+
+### 2. Provider Strengths Leveraged
+
+Each adapter uses native capabilities:
+
+* Claude Code: Native plugin system, hooks, MCP servers
+* Codex: CLI tools, AGENTS.md integration
+* OpenCode: Plugin system, symlinks, native skill tool
+
+### 3. Graceful Degradation
+
+If a provider lacks a feature:
+
+* Document the limitation in bootstrap
+* Provide alternative instructions
+* Skills still work with reduced functionality
+
+### 4. Easy to Extend
+
+Adding a new provider:
+
+1. Create `.{provider}/` directory
+2. Implement bootstrap injection
+3. Map tools to provider equivalents
+4. Write installation docs
+
+## Key Design Decisions
+
+### Skills Written for Claude Code
+
+Claude Code has the richest tool set. Write skills targeting Claude Code tools, then map down for other providers.
+
+### Adapters Are Thin
+
+Adapters should only:
+
+* Inject bootstrap content
+* Provide tool mappings
+* Handle provider-specific invocation
+
+Business logic stays in shared code.
+
+### Explicit Over Implicit
+
+Each provider's bootstrap explicitly lists:
+
+* Available skills
+* Tool mappings
+* Limitations
+* How to invoke skills
+
+No magic - the agent knows exactly what's available.
diff --git a/skills/multi-provider-plugins/references/bootstrap-patterns.md b/skills/multi-provider-plugins/references/bootstrap-patterns.md
new file mode 100644
index 0000000..688a05f
--- /dev/null
+++ b/skills/multi-provider-plugins/references/bootstrap-patterns.md
@@ -0,0 +1,368 @@
+# Bootstrap Patterns
+
+Bootstrap injection teaches the AI agent about your skills system at session start. This is the foundation of multi-provider support.
+
+## What Bootstrap Does
+
+1. **Introduces the skills system** - Explains that skills are available
+2. **Lists available skills** - With names and descriptions
+3. **Provides tool mappings** - Translates Claude Code tools to provider equivalents
+4. **Sets mandatory rules** - "If a skill applies, you MUST use it"
+5. **Explains invocation** - How to load and use skills
+
+## The Meta-Skill Pattern
+
+Create a skill that teaches about all other skills:
+
+```
+skills/
+├── using-your-plugin/           # THE META-SKILL
+│   └── SKILL.md
+├── skill-one/
+│   └── SKILL.md
+└── skill-two/
+    └── SKILL.md
+```
+
+### Example Meta-Skill (using-your-plugin/SKILL.md)
+
+```markdown
+---
+name: using-your-plugin
+description: Loaded automatically - teaches about the skills system
+---
+
+# Your Plugin Skills System
+
+## Available Skills
+
+You have access to the following skills:
+
+| Skill | Use When |
+|-------|----------|
+| `skill-one` | Working on [specific task type] |
+| `skill-two` | Dealing with [another task type] |
+
+## How to Use Skills
+
+When a task matches a skill's description:
+
+1. Load the skill using the Skill tool
+2. Follow the skill's instructions completely
+3. Don't skip steps or improvise
+
+## CRITICAL RULE
+
+**IF A SKILL APPLIES TO YOUR TASK, YOU MUST USE IT.**
+
+Skills contain tested workflows. Do not:
+- Ignore applicable skills
+- Partially follow skill instructions
+- Mix skill guidance with your own approach
+
+## Skill Priority
+
+1. **Project skills** - Highest priority (local customizations)
+2. **Personal skills** - User's personal overrides
+3. **Plugin skills** - This plugin's skills (lowest priority)
+```
+
+## Claude Code Bootstrap (Hooks)
+
+### hooks/session-start.sh
+
+```bash
+#!/bin/bash
+
+set -e
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
+META_SKILL="${PLUGIN_ROOT}/skills/using-your-plugin/SKILL.md"
+
+# Check for legacy installations and warn
+if [ -d "${HOME}/.claude/skills/your-plugin" ]; then
+    echo '{"message": "WARNING: Legacy skill directory found at ~/.claude/skills/your-plugin. Remove it to avoid conflicts."}' >&2
+fi
+
+# Read and inject the meta-skill
+if [ -f "$META_SKILL" ]; then
+    # Read content and escape for JSON
+    CONTENT=$(cat "$META_SKILL")
+
+    # Use jq for proper JSON escaping
+    JSON_CONTENT=$(echo "$CONTENT" | jq -Rs .)
+
+    # Output the hook response
+    cat << EOF
+{
+  "message": ${JSON_CONTENT}
+}
+EOF
+else
+    echo '{"message": "Warning: Meta-skill not found. Skills system may not work correctly."}' >&2
+fi
+```
+
+### hooks/hooks.json
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Cross-Platform Support
+
+For Windows compatibility, use the polyglot wrapper pattern:
+
+**hooks/run-hook.cmd:**
+
+```cmd
+: << 'CMDBLOCK'
+@echo off
+setlocal
+set "SCRIPT_NAME=%~1"
+"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u '%CLAUDE_PLUGIN_ROOT%')/hooks/%SCRIPT_NAME%\""
+exit /b
+CMDBLOCK
+
+# Unix execution (bash runs from here)
+SCRIPT_NAME="$1"
+"${CLAUDE_PLUGIN_ROOT}/hooks/${SCRIPT_NAME}"
+```
+
+**Updated hooks.json:**
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Codex Bootstrap (Manual AGENTS.md)
+
+Codex users must manually add bootstrap reference to their AGENTS.md.
+
+### .codex/bootstrap.md
+
+```markdown
+# Your Plugin for Codex
+
+## Skills System
+
+You have access to skills from the your-plugin system.
+
+### Available Skills
+
+- **skill-one** - Use when [condition]
+- **skill-two** - Use when [condition]
+
+### Loading Skills
+
+To use a skill, run:
+```bash
+~/.codex/your-plugin/.codex/your-plugin-codex use-skill <skill-name>
+```
+
+This outputs the skill content. Read and follow it completely.
+
+### Tool Mappings
+
+Skills reference Claude Code tools. Use these Codex equivalents:
+
+| In Skills | Use Instead |
+|-----------|-------------|
+| `Skill` | `~/.codex/your-plugin/.codex/your-plugin-codex use-skill` |
+| `TodoWrite` | `update_plan` |
+| `Task` (subagents) | Not available - do work yourself |
+| `Read` | `read_file` |
+| `Write` | `write_file` |
+| `Edit` | `edit_file` |
+| `Bash` | `shell` |
+| `WebFetch` | Not available - ask user |
+
+### MANDATORY RULES
+
+1. **Check for applicable skills** before starting any task
+2. **If a skill applies, USE IT** - no exceptions
+3. **Follow skills completely** - don't skip steps
+4. **Ask user for help** when tools aren't available
+
+### Finding Skills
+
+List all available skills:
+```bash
+~/.codex/your-plugin/.codex/your-plugin-codex find-skills
+```
+```
+
+### User's AGENTS.md Addition
+
+Users add this to their `~/.codex/AGENTS.md`:
+
+```markdown
+## Your Plugin
+
+For coding tasks, you have access to specialized skills.
+
+Read the bootstrap file for instructions:
+~/.codex/your-plugin/.codex/bootstrap.md
+
+Always check for applicable skills before starting work.
+```
+
+## OpenCode Bootstrap (Plugin Hook)
+
+OpenCode plugins can modify the system prompt directly.
+
+### .opencode/plugins/your-plugin.js
+
+```javascript
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = join(__dirname, '..', '..');
+
+function getMetaSkillContent() {
+  const metaSkillPath = join(PLUGIN_ROOT, 'skills', 'using-your-plugin', 'SKILL.md');
+
+  if (!existsSync(metaSkillPath)) {
+    console.error('Meta-skill not found:', metaSkillPath);
+    return null;
+  }
+
+  return readFileSync(metaSkillPath, 'utf8');
+}
+
+function getToolMappings() {
+  return `
+## OpenCode Tool Mappings
+
+When following skills, use these OpenCode equivalents:
+
+| In Skills | Use This |
+|-----------|----------|
+| \`Skill\` tool | Native \`skill\` tool with path \`your-plugin/<skill-name>\` |
+| \`TodoWrite\` | \`update_plan\` |
+| \`Task\` (subagents) | \`@mention\` syntax for specialized agents |
+| \`Read\` | \`read_file\` |
+| \`Write\` | \`write_file\` |
+| \`Edit\` | \`edit_file\` |
+| \`Bash\` | \`shell\` |
+| \`WebFetch\` | Not available - ask user |
+
+## Using Skills in OpenCode
+
+To load a skill:
+\`\`\`
+skill your-plugin/<skill-name>
+\`\`\`
+
+Example: \`skill your-plugin/skill-one\`
+`;
+}
+
+export default {
+  name: 'your-plugin',
+  version: '1.0.0',
+
+  hooks: {
+    // Use experimental.chat.system.transform to inject at session start
+    // This survives agent resets (unlike other hooks)
+    'experimental.chat.system.transform': (systemPrompt) => {
+      const metaSkill = getMetaSkillContent();
+
+      if (!metaSkill) {
+        return systemPrompt;
+      }
+
+      const toolMappings = getToolMappings();
+
+      // Append meta-skill and mappings to system prompt
+      return `${systemPrompt}
+
+---
+
+${metaSkill}
+
+${toolMappings}`;
+    }
+  }
+};
+```
+
+## Bootstrap Content Guidelines
+
+### Always Include
+
+1. **Skill list** with names and "use when" descriptions
+2. **Invocation instructions** specific to the provider
+3. **Tool mapping table** for all tools skills reference
+4. **Mandatory rule** about using applicable skills
+5. **Limitations** - what's NOT available
+
+### Keep It Concise
+
+Bootstrap content is injected into every session. Keep it:
+
+* Under 2000 tokens ideally
+* Scannable with tables and lists
+* Focused on actionable information
+
+### Version the Bootstrap
+
+If your skills change significantly, update the bootstrap:
+
+```markdown
+# Your Plugin Skills (v2.0)
+
+## What's New
+- Added skill-three for [new capability]
+- Removed deprecated skill-legacy
+```
+
+## Testing Bootstrap Injection
+
+### Claude Code
+
+1. Start new Claude Code session
+2. Ask: "What skills do you have access to?"
+3. Verify the meta-skill content appears in context
+
+### Codex
+
+1. Ensure AGENTS.md references bootstrap
+2. Start new session
+3. Ask: "What does your-plugin provide?"
+4. Verify it describes the skills system
+
+### OpenCode
+
+1. Install plugin via symlinks
+2. Start new session
+3. Ask: "List your available skills"
+4. Verify your-plugin skills appear
diff --git a/skills/multi-provider-plugins/references/provider-adapters.md b/skills/multi-provider-plugins/references/provider-adapters.md
new file mode 100644
index 0000000..f4eb88a
--- /dev/null
+++ b/skills/multi-provider-plugins/references/provider-adapters.md
@@ -0,0 +1,363 @@
+# Provider Adapters
+
+This document explains how to create adapters for each supported AI coding assistant.
+
+## Claude Code Adapter
+
+Claude Code is the primary target. Your plugin is a native Claude Code plugin.
+
+### Required Files
+
+```
+.claude-plugin/
+├── plugin.json              # Plugin manifest (required)
+└── marketplace.json         # For marketplace distribution (optional)
+```
+
+### plugin.json
+
+```json
+{
+  "name": "your-plugin-name",
+  "version": "1.0.0",
+  "description": "Brief description of your plugin",
+  "author": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  },
+  "homepage": "https://github.com/you/your-plugin",
+  "repository": "https://github.com/you/your-plugin",
+  "license": "MIT",
+  "keywords": ["skills", "multi-provider", "your-keywords"]
+}
+```
+
+### Bootstrap via Hooks
+
+Create `hooks/session-start.sh`:
+
+```bash
+#!/bin/bash
+
+# Read the meta-skill that teaches about the skills system
+SKILL_FILE="${CLAUDE_PLUGIN_ROOT}/skills/using-your-plugin/SKILL.md"
+
+if [ -f "$SKILL_FILE" ]; then
+    # Escape content for JSON
+    CONTENT=$(cat "$SKILL_FILE" | jq -Rs .)
+
+    # Output hook response
+    cat << EOF
+{
+  "message": $CONTENT
+}
+EOF
+fi
+```
+
+Create `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Important:** On Windows, use a polyglot wrapper. See `polyglot-hooks.md` in the developing-claude-code-plugins skill.
+
+---
+
+## Codex Adapter
+
+OpenAI's Codex doesn't have a native plugin system. You provide:
+
+1. A CLI tool for skill invocation
+2. Bootstrap content added to user's AGENTS.md
+3. Installation instructions
+
+### Required Files
+
+```
+.codex/
+├── INSTALL.md               # Step-by-step setup
+├── bootstrap.md             # Skill system docs + tool mappings
+└── your-plugin-codex        # Node.js CLI script
+```
+
+### INSTALL.md
+
+```markdown
+# Installing for Codex
+
+## Prerequisites
+
+- Node.js 18+
+- Git
+
+## Steps
+
+1. Clone the repository:
+   ```bash
+   mkdir -p ~/.codex/your-plugin
+   git clone https://github.com/you/your-plugin.git ~/.codex/your-plugin
+   ```
+
+2. Add to your AGENTS.md:
+
+   Open `~/.codex/AGENTS.md` and add:
+   ```markdown
+   ## Your Plugin Skills
+
+   Read ~/.codex/your-plugin/.codex/bootstrap.md for available skills.
+
+   To use a skill:
+   ```bash
+   ~/.codex/your-plugin/.codex/your-plugin-codex use-skill <skill-name>
+   ```
+   ```
+
+3. Verify installation:
+   ```bash
+   ~/.codex/your-plugin/.codex/your-plugin-codex find-skills
+   ```
+```
+
+### bootstrap.md
+
+```markdown
+# Your Plugin - Codex Integration
+
+## Available Skills
+
+<!-- List all skills with descriptions -->
+- **skill-one** - Use when [condition] - [what it does]
+- **skill-two** - Use when [condition] - [what it does]
+
+## Using Skills
+
+To load a skill's instructions:
+```bash
+~/.codex/your-plugin/.codex/your-plugin-codex use-skill <skill-name>
+```
+
+## Tool Mappings
+
+Skills reference Claude Code tools. Here are the Codex equivalents:
+
+| In Skills | Use This Instead |
+|-----------|------------------|
+| `Skill` tool | `~/.codex/your-plugin/.codex/your-plugin-codex use-skill` |
+| `TodoWrite` | `update_plan` |
+| `Task` (subagents) | Do the work yourself; subagents not available |
+| `Read`, `Write`, `Edit`, `Bash` | Same names, native tools |
+
+## Mandatory Rules
+
+1. If a skill applies to your task, USE IT
+2. Always check for applicable skills before starting work
+3. Skills provide tested workflows - follow them
+```
+
+### CLI Tool (your-plugin-codex)
+
+```javascript
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = join(__dirname, '..');
+
+// Import shared skill discovery
+const { findSkillsInDir, extractFrontmatter } = await import(
+  join(PLUGIN_ROOT, 'lib', 'skills-core.js')
+);
+
+const command = process.argv[2];
+const arg = process.argv[3];
+
+switch (command) {
+  case 'find-skills':
+    const skills = findSkillsInDir(join(PLUGIN_ROOT, 'skills'));
+    console.log('Available skills:');
+    skills.forEach(s => console.log(`  - ${s.name}: ${s.description}`));
+    break;
+
+  case 'use-skill':
+    if (!arg) {
+      console.error('Usage: your-plugin-codex use-skill <skill-name>');
+      process.exit(1);
+    }
+    const skillPath = join(PLUGIN_ROOT, 'skills', arg, 'SKILL.md');
+    if (!existsSync(skillPath)) {
+      console.error(`Skill not found: ${arg}`);
+      process.exit(1);
+    }
+    console.log(readFileSync(skillPath, 'utf8'));
+    break;
+
+  case 'bootstrap':
+    const bootstrapPath = join(__dirname, 'bootstrap.md');
+    console.log(readFileSync(bootstrapPath, 'utf8'));
+    break;
+
+  default:
+    console.log('Commands: find-skills, use-skill <name>, bootstrap');
+}
+```
+
+Make it executable:
+
+```bash
+chmod +x .codex/your-plugin-codex
+```
+
+---
+
+## OpenCode Adapter
+
+OpenCode has a plugin system similar to Claude Code, using symlinks for skill discovery.
+
+### Required Files
+
+```
+.opencode/
+├── INSTALL.md               # Setup with symlinks
+└── plugins/
+    └── your-plugin.js       # OpenCode plugin
+```
+
+### INSTALL.md
+
+```markdown
+# Installing for OpenCode
+
+## Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/you/your-plugin.git \
+       ~/.config/opencode/your-plugin
+   ```
+
+2. Symlink the plugin:
+   ```bash
+   ln -s ~/.config/opencode/your-plugin/.opencode/plugins/your-plugin.js \
+         ~/.config/opencode/plugins/your-plugin.js
+   ```
+
+3. Symlink the skills:
+   ```bash
+   ln -s ~/.config/opencode/your-plugin/skills \
+         ~/.config/opencode/skills/your-plugin
+   ```
+
+4. Restart OpenCode
+
+## Windows Users
+
+Replace symlinks with directory junctions:
+```cmd
+mklink /J "%USERPROFILE%\.config\opencode\skills\your-plugin" ^
+          "%USERPROFILE%\.config\opencode\your-plugin\skills"
+```
+
+## Verify Installation
+
+In OpenCode, run: `/skill your-plugin/using-your-plugin`
+```
+
+### OpenCode Plugin (your-plugin.js)
+
+```javascript
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = join(__dirname, '..', '..');
+const META_SKILL = join(PLUGIN_ROOT, 'skills', 'using-your-plugin', 'SKILL.md');
+
+export default {
+  name: 'your-plugin',
+  version: '1.0.0',
+
+  hooks: {
+    // Inject bootstrap at session start
+    'experimental.chat.system.transform': (systemPrompt) => {
+      if (!existsSync(META_SKILL)) {
+        return systemPrompt;
+      }
+
+      const bootstrap = readFileSync(META_SKILL, 'utf8');
+      const toolMappings = `
+## OpenCode Tool Mappings
+
+| In Skills | Use This |
+|-----------|----------|
+| \`Skill\` tool | Native \`skill\` tool |
+| \`TodoWrite\` | \`update_plan\` |
+| \`Task\` (subagents) | \`@mention\` syntax |
+| File tools | Native equivalents |
+`;
+
+      return `${systemPrompt}\n\n${bootstrap}\n\n${toolMappings}`;
+    }
+  }
+};
+```
+
+---
+
+## Adding New Providers
+
+When a new AI coding assistant emerges:
+
+### 1. Assess Capabilities
+
+* Does it have a plugin system?
+* How does it inject system prompts?
+* What tools are available?
+* How do users customize behavior?
+
+### 2. Create Adapter Directory
+
+```
+.{provider}/
+├── INSTALL.md
+└── [provider-specific files]
+```
+
+### 3. Implement Bootstrap Injection
+
+Find the mechanism to inject your meta-skill content:
+
+* Plugin hook (like OpenCode)
+* Configuration file (like Codex AGENTS.md)
+* System prompt modification
+* CLI wrapper
+
+### 4. Document Tool Mappings
+
+Create a mapping table from Claude Code tools to provider equivalents.
+
+### 5. Write Installation Docs
+
+Clear, step-by-step instructions specific to that provider.
+
+### 6. Test Thoroughly
+
+Verify skills work correctly with the new provider's tool set.
diff --git a/skills/multi-provider-plugins/references/shared-skills-library.md b/skills/multi-provider-plugins/references/shared-skills-library.md
new file mode 100644
index 0000000..bd4dd09
--- /dev/null
+++ b/skills/multi-provider-plugins/references/shared-skills-library.md
@@ -0,0 +1,439 @@
+# Shared Skills Library
+
+The shared skills library is the core of multi-provider support. One canonical set of skills, used by all providers.
+
+## Directory Structure
+
+```
+skills/
+├── using-your-plugin/           # Meta-skill (bootstrap content)
+│   └── SKILL.md
+├── skill-one/
+│   ├── SKILL.md                 # Main skill file
+│   └── references/              # Optional supporting docs
+│       └── detailed-guide.md
+├── skill-two/
+│   ├── SKILL.md
+│   └── templates/               # Optional templates
+│       └── config-template.yaml
+└── skill-three/
+    └── SKILL.md
+```
+
+## SKILL.md Format
+
+Every skill needs a SKILL.md file with YAML frontmatter:
+
+```markdown
+---
+name: skill-name
+description: Use when [trigger condition] - [what it provides]
+---
+
+# Skill Title
+
+## Overview
+Brief description of what this skill does.
+
+## When to Use
+- Condition 1
+- Condition 2
+
+## Workflow
+1. Step one
+2. Step two
+3. Step three
+
+## Best Practices
+- Do this
+- Don't do that
+```
+
+### Frontmatter Requirements
+
+**name** (required): Kebab-case identifier matching directory name
+
+```yaml
+name: my-skill-name
+```
+
+**description** (required): Follows the pattern "Use when [X] - [Y]"
+
+```yaml
+description: Use when writing tests - provides TDD workflow and patterns
+```
+
+This description helps AI agents decide when to apply the skill.
+
+## Writing Portable Skills
+
+### Use Intent-Based Language
+
+```markdown
+# Good - describes what to achieve
+Find all configuration files in the project.
+Read the main configuration to understand current settings.
+Create a backup before making changes.
+```
+
+```markdown
+# Avoid - prescribes specific tools
+Use Glob with pattern "**/config.*"
+Use Read tool on each file
+Use Write to create backup file
+```
+
+### Reference Tools Generically
+
+When you must reference tools, use generic terms:
+
+```markdown
+# Acceptable
+Use the file reading tool to examine the contents.
+Search the codebase for all references to this function.
+Run the test suite to verify changes.
+```
+
+### Document Provider Differences
+
+If behavior differs across providers, note it:
+
+```markdown
+## Notes
+
+**Subagent Support**: This workflow uses parallel subagents for faster
+analysis. On providers without subagent support, perform these steps
+sequentially instead.
+```
+
+## Skill Categories
+
+Organize skills by function:
+
+### Process Skills
+
+Guide multi-step workflows:
+
+```markdown
+---
+name: code-review
+description: Use when reviewing code changes - provides systematic review process
+---
+
+# Code Review Process
+
+## Workflow
+
+### Phase 1: Context Gathering
+1. Identify changed files
+2. Understand the purpose of changes
+3. Note the scope of modifications
+
+### Phase 2: Analysis
+1. Check for correctness
+2. Verify test coverage
+3. Review error handling
+
+### Phase 3: Feedback
+1. Summarize findings
+2. Prioritize issues
+3. Provide actionable suggestions
+```
+
+### Reference Skills
+
+Provide information access:
+
+```markdown
+---
+name: api-reference
+description: Use when working with the XYZ API - provides endpoint documentation
+---
+
+# XYZ API Reference
+
+## Endpoints
+
+### GET /users
+Returns list of users.
+
+### POST /users
+Creates a new user.
+
+[etc.]
+```
+
+### Template Skills
+
+Provide boilerplate:
+
+```markdown
+---
+name: component-template
+description: Use when creating React components - provides standard patterns
+---
+
+# React Component Template
+
+## Standard Component
+
+```tsx
+interface Props {
+  // Define props
+}
+
+export function ComponentName({ }: Props) {
+  return (
+    <div>
+      {/* Implementation */}
+    </div>
+  );
+}
+```
+
+## With State
+
+[More templates...]
+```
+
+## Supporting Files
+
+### references/ Directory
+
+Put detailed documentation in `references/`:
+
+```
+skill-name/
+├── SKILL.md                    # Main skill (loaded by Skill tool)
+└── references/
+    ├── detailed-guide.md       # In-depth explanations
+    ├── examples.md             # Worked examples
+    └── troubleshooting.md      # Common issues
+```
+
+Reference them from SKILL.md:
+
+```markdown
+## Deep Dive
+
+For detailed implementation guidance, see `references/detailed-guide.md`.
+```
+
+### templates/ Directory
+
+Store reusable templates:
+
+```
+skill-name/
+├── SKILL.md
+└── templates/
+    ├── config.yaml.template
+    └── component.tsx.template
+```
+
+### scripts/ Directory
+
+Executable utilities:
+
+```
+skill-name/
+├── SKILL.md
+└── scripts/
+    ├── validate.sh
+    └── generate.js
+```
+
+## Skill Discovery
+
+### lib/skills-core.js
+
+Shared code for finding and parsing skills:
+
+```javascript
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
+import { join, basename } from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Extract YAML frontmatter from a skill file
+ */
+export function extractFrontmatter(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+  if (!match) {
+    return { name: basename(filePath, '.md'), description: '' };
+  }
+
+  const frontmatter = {};
+  match[1].split('\n').forEach(line => {
+    const [key, ...valueParts] = line.split(':');
+    if (key && valueParts.length) {
+      frontmatter[key.trim()] = valueParts.join(':').trim();
+    }
+  });
+
+  return frontmatter;
+}
+
+/**
+ * Find all skills in a directory
+ */
+export function findSkillsInDir(dir, maxDepth = 3) {
+  const skills = [];
+
+  function scan(currentDir, depth) {
+    if (depth > maxDepth) return;
+
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const skillFile = join(fullPath, 'SKILL.md');
+        if (existsSync(skillFile)) {
+          const frontmatter = extractFrontmatter(skillFile);
+          skills.push({
+            name: frontmatter.name || entry.name,
+            description: frontmatter.description || '',
+            path: skillFile,
+            directory: fullPath
+          });
+        }
+        scan(fullPath, depth + 1);
+      }
+    }
+  }
+
+  scan(dir, 0);
+  return skills;
+}
+
+/**
+ * Resolve skill path with shadowing support
+ */
+export function resolveSkillPath(skillName, pluginDir, personalDir, projectDir) {
+  // Check project first (highest priority)
+  if (projectDir) {
+    const projectPath = join(projectDir, skillName, 'SKILL.md');
+    if (existsSync(projectPath)) return projectPath;
+  }
+
+  // Check personal directory
+  if (personalDir) {
+    const personalPath = join(personalDir, skillName, 'SKILL.md');
+    if (existsSync(personalPath)) return personalPath;
+  }
+
+  // Fall back to plugin directory
+  const pluginPath = join(pluginDir, skillName, 'SKILL.md');
+  if (existsSync(pluginPath)) return pluginPath;
+
+  return null;
+}
+
+/**
+ * Strip frontmatter from skill content
+ */
+export function stripFrontmatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+}
+
+/**
+ * Check for updates via git
+ */
+export function checkForUpdates(repoDir) {
+  try {
+    execSync('git fetch', { cwd: repoDir, stdio: 'ignore' });
+    const status = execSync('git status -uno', { cwd: repoDir, encoding: 'utf8' });
+    return status.includes('behind');
+  } catch {
+    return false;
+  }
+}
+```
+
+## Skill Shadowing
+
+Allow users to override plugin skills without modifying your repository.
+
+### Priority Order
+
+1. **Project skills** - `./.your-plugin/skills/` or `./skills/`
+2. **Personal skills** - `~/.config/{provider}/skills/your-plugin/`
+3. **Plugin skills** - Your repository's `/skills/`
+
+### Implementation
+
+Each adapter implements shadowing:
+
+**Claude Code** - Not directly supported, but users can create project-level CLAUDE.md
+
+**Codex** - CLI checks multiple directories:
+
+```javascript
+export function resolveSkill(name) {
+  const locations = [
+    join(process.cwd(), '.codex', 'skills', name),
+    join(homedir(), '.codex', 'skills', name),
+    join(PLUGIN_ROOT, 'skills', name)
+  ];
+
+  for (const loc of locations) {
+    if (existsSync(join(loc, 'SKILL.md'))) {
+      return join(loc, 'SKILL.md');
+    }
+  }
+  return null;
+}
+```
+
+**OpenCode** - Symlink hierarchy handles this naturally
+
+### User Override Example
+
+User wants to customize `skill-one`:
+
+```bash
+# Create personal override
+mkdir -p ~/.config/opencode/skills/your-plugin/skill-one
+cp /path/to/original/SKILL.md ~/.config/opencode/skills/your-plugin/skill-one/
+# Edit the copy
+vim ~/.config/opencode/skills/your-plugin/skill-one/SKILL.md
+```
+
+Now the customized version takes precedence.
+
+## Versioning Skills
+
+### Semantic Skill Versions
+
+Track skill changes in your CHANGELOG:
+
+```markdown
+## [2.0.0] - 2025-01-15
+
+### Skills
+- **skill-one** - Complete rewrite for new workflow
+- **skill-two** - Added Phase 3 for validation
+- **BREAKING** - Removed deprecated skill-legacy
+```
+
+### Backward Compatibility
+
+When changing skills significantly:
+
+1. Keep old skill with `-legacy` suffix temporarily
+2. Document migration in the new skill
+3. Remove legacy after transition period
+
+```
+skills/
+├── code-review/              # New version
+│   └── SKILL.md
+└── code-review-legacy/       # Deprecated, remove in v3.0
+    └── SKILL.md
+```
diff --git a/skills/multi-provider-plugins/references/tool-mapping.md b/skills/multi-provider-plugins/references/tool-mapping.md
new file mode 100644
index 0000000..fc58169
--- /dev/null
+++ b/skills/multi-provider-plugins/references/tool-mapping.md
@@ -0,0 +1,256 @@
+# Tool Mapping Reference
+
+Skills are written using Claude Code tool names. Each provider adapter must map these to equivalent functionality.
+
+## Master Tool Mapping Table
+
+| Claude Code Tool | Codex | OpenCode | Notes |
+|-----------------|-------|----------|-------|
+| `Skill` | Custom CLI | Native `skill` | Skill invocation |
+| `TodoWrite` | `update_plan` | `update_plan` | Task tracking |
+| `Task` (subagents) | Not available | `@mention` | Parallel work |
+| `Read` | `read_file` | `read_file` | Read files |
+| `Write` | `write_file` | `write_file` | Create files |
+| `Edit` | `edit_file` | `edit_file` | Modify files |
+| `Bash` | `shell` | `shell` | Run commands |
+| `Glob` | `list_files` | `list_files` | Find files |
+| `Grep` | `search` | `search` | Search content |
+| `WebFetch` | Not available | Not available | Fetch URLs |
+| `WebSearch` | Not available | Not available | Search web |
+
+## Detailed Tool Mappings
+
+### Skill Invocation
+
+**Claude Code:**
+```
+Use the Skill tool with skill: "my-skill"
+```
+
+**Codex:**
+```bash
+~/.codex/your-plugin/.codex/your-plugin-codex use-skill my-skill
+```
+
+**OpenCode:**
+```
+Use the skill tool with: your-plugin/my-skill
+```
+
+### Task Tracking (TodoWrite)
+
+**Claude Code:**
+```
+Use TodoWrite to track progress
+```
+
+**Codex & OpenCode:**
+```
+Use update_plan to track progress
+```
+
+The functionality is identical - just a different tool name.
+
+### Subagents (Task Tool)
+
+**Claude Code:**
+```
+Launch a Task subagent with:
+- subagent_type: "Explore"
+- prompt: "Find all configuration files"
+```
+
+**Codex:**
+Subagents are NOT available. The bootstrap should instruct:
+```
+When skills mention using Task/subagents for parallel work,
+do the work yourself sequentially instead. Subagents are not
+available in Codex.
+```
+
+**OpenCode:**
+```
+Use @mention syntax to invoke specialized agents:
+@explorer Find all configuration files
+```
+
+### File Operations
+
+All providers support similar file operations:
+
+**Reading Files:**
+| Provider | Tool | Example |
+|----------|------|---------|
+| Claude Code | `Read` | Read file_path="/path/to/file" |
+| Codex | `read_file` | read_file("/path/to/file") |
+| OpenCode | `read_file` | read_file path="/path/to/file" |
+
+**Writing Files:**
+| Provider | Tool | Example |
+|----------|------|---------|
+| Claude Code | `Write` | Write file_path="/path" content="..." |
+| Codex | `write_file` | write_file("/path", "content") |
+| OpenCode | `write_file` | write_file path="/path" content="..." |
+
+**Editing Files:**
+| Provider | Tool | Example |
+|----------|------|---------|
+| Claude Code | `Edit` | Edit file_path="/path" old_string="x" new_string="y" |
+| Codex | `edit_file` | edit_file("/path", "old", "new") |
+| OpenCode | `edit_file` | edit_file path="/path" old="x" new="y" |
+
+### Shell Commands
+
+**Claude Code:**
+```
+Use Bash with command: "npm install"
+```
+
+**Codex:**
+```
+Use shell with command: "npm install"
+```
+
+**OpenCode:**
+```
+Use shell with: npm install
+```
+
+### File Search
+
+**Claude Code:**
+```
+Use Glob with pattern: "**/*.ts"
+```
+
+**Codex:**
+```
+Use list_files with pattern "**/*.ts"
+```
+
+**OpenCode:**
+```
+Use list_files pattern="**/*.ts"
+```
+
+### Content Search
+
+**Claude Code:**
+```
+Use Grep with pattern: "TODO" and path: "src/"
+```
+
+**Codex:**
+```
+Use search with query "TODO" in "src/"
+```
+
+**OpenCode:**
+```
+Use search pattern="TODO" path="src/"
+```
+
+## Handling Missing Tools
+
+### WebFetch / WebSearch
+
+Most providers besides Claude Code lack web access. Handle this in bootstrap:
+
+```markdown
+## Tool Limitations
+
+The following Claude Code tools are NOT available:
+- `WebFetch` - Cannot fetch URLs
+- `WebSearch` - Cannot search the web
+
+When skills mention using these tools, inform the user that
+you cannot access web resources and ask them to provide the
+information manually.
+```
+
+### Subagents
+
+When subagents aren't available, provide alternative instructions:
+
+```markdown
+## Subagent Alternatives
+
+Claude Code's Task tool (subagents) is not available in Codex.
+
+When skills mention:
+- "Launch a subagent to..." → Do the work yourself
+- "Use Task with Explore agent..." → Use search tools manually
+- "Run agents in parallel..." → Work sequentially instead
+```
+
+## Writing Portable Skills
+
+### Do: Use Generic Descriptions
+
+```markdown
+# Good - tool-agnostic language
+Read the configuration file to understand the current settings.
+Search for all TypeScript files in the project.
+Create a new file with the implementation.
+```
+
+### Don't: Reference Specific Tool Names in Instructions
+
+```markdown
+# Bad - Claude Code specific
+Use the Read tool with file_path="config.json"
+Use Glob with pattern="**/*.ts"
+Use Write with file_path="new-file.ts"
+```
+
+### Do: Describe Intent, Not Implementation
+
+```markdown
+# Good - describes what to do
+1. Find all test files in the project
+2. Read each test file to understand the testing patterns
+3. Create a new test file following the same patterns
+```
+
+### Don't: Prescribe Exact Tool Usage
+
+```markdown
+# Bad - prescribes specific tools
+1. Use Glob with pattern="**/*.test.ts"
+2. Use Read on each matched file
+3. Use Write to create "new.test.ts"
+```
+
+## Bootstrap Template for Tool Mappings
+
+Include this pattern in each provider's bootstrap:
+
+```markdown
+## Tool Reference
+
+When following skills, translate Claude Code tools as follows:
+
+### Available Tools
+| Skill Says | You Should Use |
+|------------|----------------|
+| Read, read file | [provider tool] |
+| Write, create file | [provider tool] |
+| Edit, modify file | [provider tool] |
+| Bash, run command | [provider tool] |
+| Glob, find files | [provider tool] |
+| Grep, search content | [provider tool] |
+| Skill | [provider mechanism] |
+| TodoWrite | [provider tool] |
+
+### Unavailable Tools
+The following are NOT available - ask user for help:
+| Skill Says | Alternative |
+|------------|-------------|
+| WebFetch | Ask user to provide content |
+| WebSearch | Ask user for information |
+| Task (subagents) | Do work yourself |
+
+### When Uncertain
+If a skill references a tool not listed above, use your best judgment
+to find an equivalent, or ask the user for guidance.
+```