IdeaSDK/docs/codex-skills-and-idea-plugins.md

Codex Skills And IdeA Plugins

IdeA runtime plugins, IdeA-native plugin skills and Codex plugins are distinct installation and discovery systems.

An IdeA runtime plugin is described by idea-plugin.json. Installing it through IdeA makes its global runtime package available. Project settings then decide which installed plugins are enabled for a project, and agent settings decide which plugin skills and plugin MCP tools are assigned to each agent.

An IdeA-native plugin skill is declared in idea-plugin.json under contributes.skills. Its body is a package-relative Markdown file such as skills/<name>/SKILL.md. When the plugin is enabled for a project and the skill is assigned to an agent, IdeA injects the skill affordance into that agent's skill catalogue and serves the body through idea_skill_read. This is not Codex-specific; it is projected by IdeA for every harness that supports IdeA capabilities, including Claude Code, Codex, OpenCode local and OpenCode cloud.

A Codex plugin is described by .codex-plugin/plugin.json. Its skills entry points Codex at skill directories such as skills/*/SKILL.md. This metadata is for Codex plugin installation and skill discovery, not for IdeA runtime plugin loading.

Normative Behavior

• Installing or reloading an IdeA plugin makes the package available globally, but does not automatically enable it in every project.
• Enabling a plugin for a project does not automatically assign every skill or MCP tool to every agent.
• A plugin skill becomes visible to an agent only when the plugin is enabled for the project and that skill is assigned to that agent.
• Installing or reloading an IdeA plugin does not automatically install a bundled Codex plugin, and .codex-plugin/plugin.json remains inert for IdeA-native plugin loading unless a separate bridge explicitly consumes it.
• Bundling .codex-plugin/plugin.json is still allowed as distribution content for Codex-specific workflows, but it is not the multi-harness IdeA contract.

Required Mechanisms

For multi-harness IdeA agent skills, declare contributes.skills in idea-plugin.json, ship the referenced Markdown files inside the package, install the plugin in IdeA, enable it in the target project, and assign the skills to the target agents. See Project Plugin Assignments for the project settings schema and the complete install, enable, assign, and relaunch workflow.

For Codex-specific plugin skills, install the Codex plugin through the Codex plugin mechanism for the intended scope, then assign or enable those skills according to Codex/IdeA agent configuration.

Do not rely on .codex-plugin/plugin.json as a cross-harness skill propagation mechanism. Cross-harness plugin skill availability is driven by idea-plugin.json and IdeA project/agent assignments.