multi-provider-plugins

Files (6)

• SKILL.md
• architecture-overview.md · references/
• bootstrap-patterns.md · references/
• provider-adapters.md · references/
• shared-skills-library.md · references/
• tool-mapping.md · references/

SKILL.md (first lines)

# Multi-Provider Plugins

Route to the reference that matches your task.

## Task → Reference

| Task | Read |
|------|------|
| Understand the shared-skills + thin-adapter architecture | `references/architecture-overview.md` |
| Add or configure a provider-specific adapter (Claude Code, Codex, OpenCode, Cursor, Gemini) | `references/provider-adapters.md` |
| Map tool names across providers in skill content | `references/tool-mapping.md` |
| Implement session-start bootstrap injection for a provider | `references/bootstrap-patterns.md` |
| Structure or audit a portable shared skills library | `references/shared-skills-library.md` |

## Instruction File Conventions (CLAUDE.md / AGENTS.md)

**Non-obvious and commonly wrong** — apply whenever creating a new project or touching either file:

- **Claude Code** reads `CLAUDE.md`. Supports `@filename` import syntax (e.g. `@AGENTS.md` inlines it).
- **Codex CLI** reads `AGENTS.md` as plain Markdown — **no `@import` or include syntax exists**. `@CLAUDE.md` in AGENTS.md is a broken line, not an import.
- **Best pattern:** Write everything in `AGENTS.md`. Make `CLAUDE.md` contain only `@AGENTS.md`. All tools read AGENTS.md directly; Claude Code imports it inline via the `@` syntax.
- **Codex plugins:** `codex plugin marketplace add/upgrade/remove` only — no `install` subcommand.

## Universal Principles

1. **One `skills/` directory, many adapters.** Skills live once; provider adapters point to them. Never duplicate skill content per provider.

2. **Adapters are thin.** A provider adapter does the minimum: declare the plugin, point at `skills/`, and inject a bootstrap if the provider needs it. No business logic in adapters.

3. **Skills are portable markdown.** SKILL.md frontmatter format is identical across providers. Use clearly-labeled `### Claude Code` / `### Codex` subsections within skill bodies when tool names differ — don't branch in frontmatter.

4. **Bootstrap injection is a last resort.** Claude Code discovers skills natively. Only write bootstrap code when a provider lacks native skill discovery.

5. **Reference implementation.** [obra/superpowers](https://github.com/obra/superpowers) is the canonical example of this architecture running across Claude Code, Codex, OpenCode, Cursor, and Gemini CLI.

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills