[works but do not merge] Refactor plugin layout for cross-agent compatibility

.agents/plugins/marketplace.json

@@ -1,14 +1,14 @@
 {
-  "name": "microsoftdocs-local",
+  "name": "microsoft-docs-marketplace",
   "interface": {
-    "displayName": "Microsoft Docs Local Plugins Marketplace"
+    "displayName": "Microsoft Docs"
   },
   "plugins": [
     {
       "name": "microsoft-docs",
       "source": {
         "source": "local",
-        "path": "./"
+        "path": "./plugins/microsoft-docs"
       },
       "policy": {
         "installation": "AVAILABLE",

.claude-plugin/marketplace.json

@@ -6,8 +6,9 @@
   "plugins": [
     {
       "name": "microsoft-docs",
-      "source": "./",
-      "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more."
+      "source": "./plugins/microsoft-docs",
+      "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
+      "version": "0.4.0"
     }
   ]
 }

.github/plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "microsoft-docs-marketplace",
+  "owner": {
+    "name": "Microsoft"
+  },
+  "metadata": {
+    "description": "Microsoft Learn documentation plugins for coding agents",
+    "version": "0.4.0"
+  },
+  "plugins": [
+    {
+      "name": "microsoft-docs",
+      "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
+      "version": "0.4.0",
+      "source": "./plugins/microsoft-docs"
+    }
+  ]
+}

.github/plugin/plugin.json

@@ -1,11 +1,14 @@
 {
   "name": "microsoft-docs",
   "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "Microsoft"
   },
   "homepage": "https://learn.microsoft.com",
   "repository": "https://github.com/microsoftdocs/mcp",
-  "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"]
+  "license": "MIT",
+  "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"],
+  "skills": ["plugins/microsoft-docs/skills/"],
+  "mcpServers": "plugins/microsoft-docs/.mcp.json"
 }

AGENTS.md

@@ -1,24 +1,25 @@
 # AGENTS.md
 
-This repo is the community-facing repo for **Microsoft Learn MCP Server** — a remote MCP endpoint (`https://learn.microsoft.com/api/mcp`) that gives AI agents access to official Microsoft documentation. The repo also contains a CLI (`cli/`), agent skills (`skills/`), and plugin manifests for three ecosystems.
+This repo is the community-facing repo for **Microsoft Learn MCP Server** — a remote MCP endpoint (`https://learn.microsoft.com/api/mcp`) that gives AI agents access to official Microsoft documentation. The repo also contains a CLI (`cli/`), agent skills, and plugin manifests for three ecosystems.
 
 ## Plugin ecosystems
 
-The repo publishes plugin metadata for three ecosystems. `.claude-plugin/plugin.json` is the **source of truth** for shared plugin fields (name, description, version, author, etc.).
+The repo publishes plugin metadata for three ecosystems. The shared plugin package lives at `plugins/microsoft-docs/`; root-level files are marketplace catalogs or compatibility shims.
 
 **Shared assets** used across ecosystems:
-- `skills/` — agent skill packages (each subfolder has a `SKILL.md`)
-- `.mcp.json` — MCP server endpoint config
+- `plugins/microsoft-docs/skills/` — agent skill packages (each subfolder has a `SKILL.md`)
+- `plugins/microsoft-docs/.mcp.json` — MCP server endpoint config for Claude Code and GitHub Copilot CLI
+- `plugins/microsoft-docs/.codex.mcp.json` — Codex MCP server endpoint config, using Codex's documented direct server map shape
 
-**Claude** — `.claude-plugin/plugin.json` (source of truth) + `.claude-plugin/marketplace.json`
+**Claude** — `.claude-plugin/marketplace.json` points to `plugins/microsoft-docs/`; `plugins/microsoft-docs/.claude-plugin/plugin.json` defines the Claude package.
 
-**GitHub Copilot** — `.github/plugin/plugin.json` — must be an **exact copy** of `.claude-plugin/plugin.json`.
+**GitHub Copilot** — `.github/plugin/marketplace.json` points to `plugins/microsoft-docs/`; `plugins/microsoft-docs/plugin.json` defines the marketplace package; `.github/plugin/plugin.json` is a direct-install shim for `/plugin install microsoftdocs/mcp` and points to the shared package assets.
 
-**Codex** — `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json`. The plugin.json shares fields with Claude but adds Codex-only fields (`skills`, `mcpServers`, `interface`, `license`) that wire it to the shared assets. Keep asset paths relative to repo root (`./skills/`, `./.mcp.json`) — never use `..` paths. The marketplace file must point at `./`.
+**Codex** — `.agents/plugins/marketplace.json` points to `plugins/microsoft-docs/`; `plugins/microsoft-docs/.codex-plugin/plugin.json` defines the Codex package. Codex marketplace entries must point to a plugin subfolder such as `./plugins/microsoft-docs`; do not use `./`.
 
 ## Sync rules
 
-When editing shared plugin metadata, edit `.claude-plugin/plugin.json` first, then copy it verbatim to `.github/plugin/plugin.json` and update shared fields in `.codex-plugin/plugin.json` to match.
+When editing shared plugin metadata, keep identity fields aligned across all plugin manifests: `plugins/microsoft-docs/plugin.json`, `plugins/microsoft-docs/.claude-plugin/plugin.json`, `plugins/microsoft-docs/.codex-plugin/plugin.json`, and `.github/plugin/plugin.json`. The direct-install shim has repo-root-relative asset paths, so it must not be an exact copy of the package manifests.
 
 ## CLI
 
@@ -38,5 +39,5 @@ It enforces sync rules, skill structure, file existence, and marketplace wiring.
 
 - `README.md` is the primary user-facing document. Update it in the same change whenever install steps, plugin layout, skills, or CLI behavior change.
 - Make the smallest synchronized set of edits that keeps all three ecosystems coherent.
-- Do not reintroduce a nested `plugins/microsoft-docs` copy for Codex packaging.
+- Keep plugin runtime assets under `plugins/microsoft-docs/`; root-level plugin files are marketplace catalogs or compatibility shims only.
 - Prefer fixing drift immediately over documenting known inconsistency.

README.md

@@ -116,27 +116,44 @@ See [`cli/README.md`](cli/README.md) for the full command reference.
 
 | Skill | Purpose | Best For |
 |-------|---------|----------|
-| [`microsoft-docs`](skills/microsoft-docs/SKILL.md) | Understanding concepts, tutorials, architecture, limits | "How does X work?", learning, configuration guides |
-| [`microsoft-code-reference`](skills/microsoft-code-reference/SKILL.md) | API lookups, code samples, verification, error fixing | Implementing code, finding correct methods, troubleshooting |
-| [`microsoft-skill-creator`](skills/microsoft-skill-creator/SKILL.md) | Meta-skill that generates custom agent skills for any Microsoft technology | Creating a skill to teach agents about a new Azure library, .NET feature, or other Microsoft tech |
+| [`microsoft-docs`](plugins/microsoft-docs/skills/microsoft-docs/SKILL.md) | Understanding concepts, tutorials, architecture, limits | "How does X work?", learning, configuration guides |
+| [`microsoft-code-reference`](plugins/microsoft-docs/skills/microsoft-code-reference/SKILL.md) | API lookups, code samples, verification, error fixing | Implementing code, finding correct methods, troubleshooting |
+| [`microsoft-skill-creator`](plugins/microsoft-docs/skills/microsoft-skill-creator/SKILL.md) | Meta-skill that generates custom agent skills for any Microsoft technology | Creating a skill to teach agents about a new Azure library, .NET feature, or other Microsoft tech |
 
 ### Quick Setup
 
-These agent skills are packed in a `microsoft-docs` plugin together with the Learn MCP server itself. If you use Claude Code, run the following command and restart Claude Code:
+These agent skills are packed in a `microsoft-docs` plugin together with the Learn MCP server itself.
+
+If you use GitHub Copilot CLI, run:
 ```
-/plugin install microsoft-docs@claude-plugins-official
+/plugin install microsoftdocs/mcp
 ```
 
-Or if you use GitHub Copilot CLI, run this command:
+If you use Claude Code, add this repository as a marketplace and install the plugin:
 ```
-/plugin install microsoftdocs/mcp
+/plugin marketplace add microsoftdocs/mcp
+/plugin install microsoft-docs@microsoft-docs-marketplace
+```
+
+If you use Codex CLI, add this repository as a marketplace, then install `microsoft-docs` from the Microsoft Docs marketplace in the plugin directory:
+```
+codex plugin marketplace add microsoftdocs/mcp
+codex plugin install microsoft-docs@microsoft-docs-marketplace
 ```
+
+The plugin package lives under `plugins/microsoft-docs/` so all three coding agents can share the same skills and MCP configuration.
+
+Claude Code users can also install from the official Claude marketplace:
+```
+/plugin install microsoft-docs@claude-plugins-official
+```
+
 Otherwise:
 1. **Install the MCP Server first** — See [Installation](#-installation--getting-started) below
 2. **Copy the skill folders** to your project's `.github/skills/` or `.claude/skills/` directory:
-   - [`microsoft-docs`](skills/microsoft-docs/) — for concepts, tutorials, and factual lookups
-   - [`microsoft-code-reference`](skills/microsoft-code-reference/) — for API lookups, code samples, and troubleshooting
-   - [`microsoft-skill-creator`](skills/microsoft-skill-creator/) — meta-skill for generating custom skills about Microsoft technologies
+   - [`microsoft-docs`](plugins/microsoft-docs/skills/microsoft-docs/) — for concepts, tutorials, and factual lookups
+   - [`microsoft-code-reference`](plugins/microsoft-docs/skills/microsoft-code-reference/) — for API lookups, code samples, and troubleshooting
+   - [`microsoft-skill-creator`](plugins/microsoft-docs/skills/microsoft-skill-creator/) — meta-skill for generating custom skills about Microsoft technologies
 
 ### Supported Agents
 
@@ -164,10 +181,10 @@ The Microsoft Learn MCP Server supports quick installation across multiple devel
 | **VS Code** | [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=microsoft-learn&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flearn.microsoft.com%2Fapi%2Fmcp%22%7D) <br/> or search "@mcp learn" in Extensions to show "Microsoft Learn" MCP | [VS Code MCP Official Guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
 | **GitHub Copilot CLI** | `/plugin install microsoftdocs/mcp` | |
 | **Claude Desktop** | Follow "Add custom connector" instructions in official guide. | [Claude Desktop Remote MCP Guide](https://modelcontextprotocol.io/docs/develop/connect-remote-servers) |
-| **Claude Code** | `/plugin install microsoft-docs@claude-plugins-official` (includes MCP server + skills) | [Claude Code Remote MCP Guide](https://code.claude.com/docs/en/mcp) |
+| **Claude Code** | `/plugin marketplace add microsoftdocs/mcp` then `/plugin install microsoft-docs@microsoft-docs-marketplace` (includes MCP server + skills) | [Claude Code Remote MCP Guide](https://code.claude.com/docs/en/mcp) |
 | **Visual Studio** | Upgrade to latest VS 2022 or 2026, "Microsoft Learn" MCP is already built-in | [Visual Studio MCP Official Guide](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) |
 | **Cursor IDE** | [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=microsoft-learn&config=eyJuYW1lIjoibWljcm9zb2Z0LWxlYXJuIiwidHlwZSI6Imh0dHAiLCJ1cmwiOiJodHRwczovL2xlYXJuLm1pY3Jvc29mdC5jb20vYXBpL21jcCJ9) | [Cursor MCP Official Guide](https://docs.cursor.com/context/model-context-protocol) |
-| **Codex** | `codex mcp add "microsoft-learn" --url "https://learn.microsoft.com/api/mcp"`| [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers) |
+| **Codex** | `codex plugin marketplace add microsoftdocs/mcp`, then install `microsoft-docs` from the Microsoft Docs marketplace. For MCP-only setup, use `codex mcp add "microsoft-learn" --url "https://learn.microsoft.com/api/mcp"` | [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers) |
 | **Roo Code** | Open [Roo Code Marketplace](https://docs.roocode.com/features/marketplace), search for `Microsoft Learn`, and click `Install` | [Roo Code MCP Official Guide](https://docs.roocode.com/features/mcp/using-mcp-in-roo) |
 | **Cline** | Manual configuration required<br/>Use `"type": "streamableHttp"` | [Cline MCP Official Guide](https://docs.cline.bot/mcp/connecting-to-a-remote-server) |
 | **Gemini CLI** | Manual configuration required<br/> <details><summary>View Config</summary>**Note**: Add an `mcpServer` object to `.gemini/settings.json` file<br/><pre>{<br/>  "Microsoft Learn MCP Server": {<br/>     "httpUrl": "https://learn.microsoft.com/api/mcp" <br/>   }<br/>}</pre></details>  | [How to set up your MCP server](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server)|

plugins/microsoft-docs/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "microsoft-docs",
+  "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Microsoft"
+  },
+  "homepage": "https://learn.microsoft.com",
+  "repository": "https://github.com/microsoftdocs/mcp",
+  "license": "MIT",
+  "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}

.codex-plugin/plugin.json → plugins/microsoft-docs/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "microsoft-docs",
   "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "Microsoft"
   },
@@ -10,7 +10,7 @@
   "license": "MIT",
   "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"],
   "skills": "./skills/",
-  "mcpServers": "./.mcp.json",
+  "mcpServers": "./.codex.mcp.json",
   "interface": {
     "displayName": "Microsoft Docs",
     "shortDescription": "Search official Microsoft docs and code samples.",

plugins/microsoft-docs/.codex.mcp.json

@@ -0,0 +1,6 @@
+{
+  "microsoft-learn": {
+    "type": "http",
+    "url": "https://learn.microsoft.com/api/mcp"
+  }
+}

.claude-plugin/plugin.json → plugins/microsoft-docs/plugin.json

@@ -1,11 +1,14 @@
 {
   "name": "microsoft-docs",
   "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "Microsoft"
   },
   "homepage": "https://learn.microsoft.com",
   "repository": "https://github.com/microsoftdocs/mcp",
-  "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"]
+  "license": "MIT",
+  "keywords": ["microsoft", "docs", "azure", ".net", "windows", "api", "documentation", "rag", "dynamics", "powerbi", "office"],
+  "skills": ["skills/"],
+  "mcpServers": ".mcp.json"
 }