blomios/IdeaSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6eb8db3791b4377dd0ede89410fc540835c5d4d1
IdeaSDK/docs/codex-skills-and-idea-plugins.md

2.6 KiB
Raw Blame History

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.