Repository navigation
Add backward-compatible Agent Plugins format support #34
Description
Summary
Adopt the vendor-neutral Agent Plugins format (formerly Open Plugins) for plugins/microsoft-managed-apps while preserving compatibility for existing consumers of the current Claude-specific layout.
Today, the managed-apps plugin exposes only:
plugins/microsoft-managed-apps/.claude-plugin/plugin.json- the existing
skills/,agents/,hooks/, and shared content
It does not expose a canonical .plugin/plugin.json manifest or other Agent Plugins entry points. As a result, clients that discover plugins through the portable Agent Plugins format—including Codex and other conforming hosts—cannot consume this plugin through their standard discovery/install path.
Why
Agent Plugins provides a vendor-neutral package layout backed by participants from Amazon, Cursor, Microsoft, OpenAI, and Vercel. Supporting it would:
- Make the managed-apps plugin discoverable and installable by more agent hosts, including Codex, without maintaining separate plugin implementations.
- Reduce coupling to a single client's
.claude-pluginconventions. - Reuse the existing skills and plugin assets through a standard package manifest.
- Provide a clearer interoperability contract for manifests, Agent Skills, MCP servers, and client-specific extensions.
- Improve portability for customers who use multiple coding agents or move between them.
- Align this repository with the compatibility approach already adopted by Microsoft's Power Platform skills repository.
Proposed approach
- Treat the Agent Plugins manifest as canonical:
- Add
plugins/microsoft-managed-apps/.plugin/plugin.jsonusing the Agent Plugins schema/layout. - Map the current plugin metadata and assets without changing skill behavior.
- Add other standard entry points such as
mcp.jsononly if required by the plugin's actual capabilities.
- Add
- Preserve the existing Claude path:
- Keep
plugins/microsoft-managed-apps/.claude-plugin/plugin.jsonas a real JSON compatibility mirror of the canonical manifest. - Do not use a symlink; symlink manifests caused parse failures for Windows clients in the Power Platform migration.
- Keep
- Add automated compatibility validation:
- Validate both manifests as JSON.
- Assert that canonical and legacy manifests remain semantically equivalent, allowing only intentional format-specific differences.
- Run validation in CI and/or the existing plugin validation workflow.
- Update plugin documentation:
- Document installation/discovery for Agent Plugins-compatible clients and existing Claude consumers.
- State which manifest is canonical and how mirrors must be updated.
- Verify existing customers are unaffected:
- Test the current Claude installation/update flow.
- Test discovery and installation with at least one Agent Plugins-compatible client, preferably Codex.
Prior art
microsoft/power-platform-skills completed this migration while preserving existing subscriptions:
- PR microsoft/power-platform-skills#188 moved canonical marketplace/plugin manifests to the vendor-neutral layout, retained legacy
.claude-pluginpaths, and converted MCP configuration to the standardmcpServersshape. - PR microsoft/power-platform-skills#203 replaced compatibility symlinks with real JSON mirrors after Windows clients parsed symlink contents as JSON and failed with
Unexpected token '.'. scripts/validate-legacy-compatibility.jsverifies that legacy manifests remain equivalent to the canonical Agent Plugins manifests.- Agent Plugins specification and governance
- Agent Plugins specification repository
The key implementation lesson is to use canonical Agent Plugins JSON plus validated legacy JSON mirrors—not filesystem symlinks—so existing consumers continue to auto-update across platforms.
Acceptance criteria
-
plugins/microsoft-managed-appshas a valid canonical Agent Plugins manifest. - Existing
.claude-plugininstallation and update flows continue to work without customer action. - Compatibility files are regular JSON files, not symlinks.
- Automated validation prevents canonical and legacy manifests from drifting.
- The plugin can be discovered/installed by a supported Agent Plugins client such as Codex.
- Existing plugin skills, hooks, and attribution behavior remain unchanged.
- Documentation covers both portable and legacy installation paths.
Activity
Anshulmsft commentedon Oct 15, 2026
This work has moved to bic/PowerPlatform-Managed-Host#1837. The enterprise Task preserves the original rationale and prior art, and adds the compatibility findings and fresh-install/in-place-upgrade test matrix identified while reviewing #37.