# 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.

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.