> ## Documentation Index > Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt > Use this file to discover all available pages before exploring further. # Core-Four Primitive Matrix This page defines how the Pluxx authoring model should map across the core four hosts: * Claude Code * Cursor * Codex * OpenCode The goal is not to copy one host's files into the others. The goal is to normalize author intent once, then compile it into the best native surface each host exposes. ## Compiler Buckets These are the eight buckets Pluxx should compile from: | Bucket | Includes | | -------------- | -------------------------------------------------------------------------------------- | | `instructions` | shared host guidance and routing rules | | `skills` | reusable workflows plus taxonomy-derived workflow metadata | | `commands` | explicit slash-command style entrypoints | | `agents` | specialist or delegated execution surfaces | | `hooks` | deterministic lifecycle automation | | `permissions` | portable `allow` / `ask` / `deny` intent | | `runtime` | MCP, runtime auth, runtime readiness, local runtimes, passthrough dirs, helper scripts | | `distribution` | user config, brand, packaging, install, publish, and install-surface metadata | `taxonomy` remains an internal compiler input. It drives how skills, commands, instructions, and agents are rendered, but it is not itself a host-facing extension primitive. ## Canonical Shape ```ts theme={null} interface PluxxPrimitiveModel { instructions?: InstructionsSpec skills?: SkillSpec[] commands?: CommandSpec[] agents?: AgentSpec[] hooks?: HookSpec[] permissions?: PermissionSpec[] runtime?: { mcp?: { servers?: McpSpec auth?: RuntimeAuthSpec[] } readiness?: RuntimeReadinessSpec[] payload?: { passthrough?: string[] scripts?: string[] assets?: string[] } } distribution?: { identity?: IdentitySpec branding?: BrandSpec install?: { userConfig?: UserConfigSpec[] surface?: InstallSurfaceSpec } output?: { targets?: TargetPlatform[] outDir?: string } publish?: PublishSurfaceSpec } taxonomy: TaxonomySpec } ``` This is a compiler-facing model. It is not a claim that each host has one identical manifest or one identical config file. Two public buckets already need finer internal seams: * `runtime` is MCP/auth, readiness, and generic bundled payload support * `distribution` is identity/branding, install-time config surface, and build/output surface ## Mapping Rules | Bucket | Claude Code | Cursor | Codex | OpenCode | Pluxx mapping rule | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `instructions` | `CLAUDE.md` plus plugin-level guidance surfaces | `rules/` plus `AGENTS.md` support | `AGENTS.md`, `AGENTS.override.md`, and config fallback instruction files | `AGENTS.md`, `CLAUDE.md` fallback, and config-driven instruction files | Keep one instruction source of truth and compile it into the host-native guidance surface rather than duplicating prose by hand. Also keep host-specific caveats explicit, like Cursor rules not affecting Tab. | | `skills` | `skills//SKILL.md` with the richest documented frontmatter | `skills//SKILL.md` with a narrower documented frontmatter set and compatibility dirs | `skills//SKILL.md`, optionally bundled through plugins or discovered through `.agents/skills` | `skills//SKILL.md` plus compatibility dirs inside host config space | Skills stay the semantic center. Preserve shared metadata and strip or downgrade host-only frontmatter during migration and build. | | `commands` | native `commands/` markdown command files, with increasing convergence toward skills | native command and slash-command surfaces | no documented plugin-packaged command directory today | native command system through markdown or config definitions | Treat commands as first-class where the host exposes them. For Codex, degrade commands into skills and instruction routing instead of pretending parity exists. | | `agents` | plugin `agents/` with rich frontmatter and isolation settings | plugin agents plus Cursor subagents | custom agents in `.codex/agents/*.toml` and subagent workflows | primary agents and subagents with model and permission config | Treat agents as specialist execution surfaces. Compile one specialist concept into each host's native agent or subagent format, even when the storage location differs. | | `hooks` | `hooks/hooks.json`, inline plugin hooks, settings hooks, and skill or agent frontmatter hooks | `hooks/hooks.json` plus project and user hook locations | `hooks/hooks.json` in the plugin bundle gated by `[features].plugin_hooks = true`, with `.codex/hooks.json` and `~/.codex/hooks.json` still documented for broader project/user hook config where `[features].hooks` is the general flag and `codex_hooks` is deprecated | JS or TS plugin event handlers | Normalize hook intent and compile per host. Do not assume event names or return contracts are portable 1:1. | | `permissions` | tool scoping and approval controls live in Claude-specific agent, hook, and runtime surfaces | hook allow or deny decisions, CLI permission config, and subagent tool access | approvals, sandbox policy, hook matchers, and custom-agent config | first-class permission config plus per-agent overrides | Keep `allow` / `ask` / `deny` as the canonical authoring model. When one host lacks a per-skill field, move the policy to its native agent, hook, or runtime control plane. | | `runtime` | `.mcp.json` or inline MCP config, plus plugin support files | `mcp.json`, host `mcp.json` config, plugin support files, and richer auth surfaces | `.mcp.json` in plugins plus active MCP state in `config.toml`, with optional `.app.json` | config-driven MCP plus JS or TS plugin runtime | Runtime owns MCP, auth, readiness/env wiring, helper code, local runtimes, and passthrough dirs. Compile into bundle-local files when possible and external host config when required. | | `distribution` | `.claude-plugin/plugin.json`, marketplaces, install scopes, user configuration, reload surface, and adjacent plugin assets | `.cursor-plugin/plugin.json`, marketplace metadata, publish surface, local install path, reload-window flow | `.codex-plugin/plugin.json`, marketplace catalogs, cache install path, interface metadata, restart-after-update flow | npm or local JS plugin distribution plus config-based loading rather than one shared manifest | Distribution owns `userConfig`, brand, legal links, icons, screenshots, install metadata, and publish metadata. Emit rich manifest fields where supported and install shims where they are not. | ## Practical Consequences This matrix implies a few hard rules for Pluxx: 1. Migration should be semantic, not syntactic. Import the source host's intent, not its exact file format. 2. Skills are the stable workflow layer. Commands and agents should compile from the same workflow model rather than forking meaning. 3. Permissions are portable intent, not portable syntax. A Claude-only field such as `allowed-tools` should become a host-agnostic policy that Pluxx re-expresses for Cursor, Codex, and OpenCode in their native control planes. 4. Codex is not command-parity with Claude, Cursor, or OpenCode today. That is a translation problem for Pluxx, not a reason to leak host differences into the authoring model. 5. OpenCode is code-first for plugins. Hooks, runtime extensions, and some distribution behavior need real JS or TS generation rather than manifest-only generation. 6. Install and update behavior are part of compatibility truth, not just packaging trivia. The host story includes reload behavior, restart requirements, cache semantics, and marketplace or local install paths. ## Official Docs Basis ### Claude Code * [Extend Claude Code](https://code.claude.com/docs/en/features-overview) * [Create plugins](https://code.claude.com/docs/en/plugins) * [Plugins reference](https://code.claude.com/docs/en/plugins-reference) * [Hooks](https://code.claude.com/docs/en/hooks) * [Create custom subagents](https://code.claude.com/docs/en/sub-agents) * [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works) ### Cursor * [Plugins](https://cursor.com/docs/plugins) * [Agent Skills](https://cursor.com/docs/skills) * [Subagents](https://cursor.com/docs/subagents) * [Hooks](https://cursor.com/docs/hooks) * [Rules](https://cursor.com/docs/rules) * [MCP](https://cursor.com/docs/mcp) * [Slash commands](https://cursor.com/docs/cli/reference/slash-commands) * [Permissions](https://cursor.com/docs/cli/reference/permissions) ### Codex * [Build plugins](https://developers.openai.com/codex/plugins/build) * [Agent Skills](https://developers.openai.com/codex/skills) * [Subagents](https://developers.openai.com/codex/subagents) * [Hooks](https://developers.openai.com/codex/hooks) * [Model Context Protocol](https://developers.openai.com/codex/mcp) * [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) ### OpenCode * [Config](https://opencode.ai/docs/config/) * [Plugins](https://opencode.ai/docs/plugins/) * [Skills](https://opencode.ai/docs/skills/) * [Commands](https://opencode.ai/docs/commands/) * [Agents](https://opencode.ai/docs/agents/)