54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# 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](project-plugin-assignments.md) 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.
|