feat(sdk): contributes.skills — skills IdeA-native déclarables par plugin — #282 (types IdeAPluginSkillContribution/IdeAPluginSkillKind: id/name/description/kind workflow|reference/path .md package-relative, validation manifeste, export public; docs manifest + codex-skills-and-idea-plugins recentrés skills IdeA-native vs .codex-plugin Codex, README; QA verte: npm run build)

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

@@ -1,12 +1,20 @@
 # Codex Skills And IdeA Plugins
 
-IdeA runtime plugins and Codex plugins are separate installation and discovery
-systems.
+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 IdeA runtime contributions available: menus, menu items, slash
-commands, layouts, MCP servers and runtime services declared by the IdeA plugin
-manifest.
+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
@@ -15,27 +23,29 @@ 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.
-- Installing or reloading an IdeA plugin does not automatically make bundled
-  Codex skills available to agents in the current project.
-- Installing or reloading an IdeA plugin does not automatically make bundled
-  Codex skills available to agents in other projects.
-- No `idea-plugin.json` manifest field currently declares Codex skills for IdeA
-  agent assignment.
-- Bundling `.codex-plugin/plugin.json` and `skills/*/SKILL.md` inside an IdeA
-  plugin package is allowed as distribution content, but it is inert for IdeA
-  runtime plugin loading unless a separate bridge explicitly consumes it.
+  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 Mechanism
+## Required Mechanisms
 
-If a plugin needs Codex skills to be available to agents, install the Codex
-plugin through the Codex plugin mechanism for the intended scope, then assign or
-enable those skills for the relevant agents according to Codex/IdeA agent
-configuration.
+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.
 
-Do not rely on IdeA plugin installation as a cross-project skill propagation
-mechanism. Cross-project skill availability needs an explicit product contract
-covering scope, provenance, permissions, uninstall behavior, hot reload,
-collisions and security. Until that bridge exists, document and perform Codex
-skill installation separately from IdeA runtime plugin installation.
+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.