feat(plugins): cursor & refactor

.cursor-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "readme",
+  "owner": {
+    "name": "ReadMe",
+    "email": "support@readme.io"
+  },
+  "metadata": {
+    "description": "ReadMe plugins for AI coding agents"
+  },
+  "plugins": [
+    {
+      "name": "readme",
+      "source": "cursor",
+      "description": "Search, read, and update your ReadMe docs, API reference, and changelog.",
+      "minClientVersions": {
+        "cursor": "3.13.0"
+      }
+    }
+  ]
+}

.github/workflows/validate.yml

@@ -0,0 +1,33 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Skills are identical across clients
+        run: node scripts/sync-skills.mjs --check
+
+      - name: Skill frontmatter and size
+        run: node scripts/validate-skills.mjs
+
+      - run: npm install -g @anthropic-ai/claude-code
+
+      - name: Claude plugin manifest
+        run: claude plugin validate --strict claude
+
+      - name: Claude marketplace manifest
+        run: claude plugin validate --strict .claude-plugin/marketplace.json

README.md

@@ -1,84 +1,87 @@
-# ReadMe
+# ReadMe agent plugins
 
-Search, read, and update your ReadMe documentation from your editor.
+Official [ReadMe](https://readme.com) plugins that connect AI coding agents to ReadMe's
+[MCP server](https://docs.readme.com/main/docs/readmes-mcp-server), so agents can search your
+guides and API reference, inspect OpenAPI specs, draft changelog entries, and open documentation
+updates for review.
 
-## Overview
+One plugin per client, because each client has its own manifest format and its own way of handling
+credentials.
 
-This plugin connects compatible AI assistants to [ReadMe](https://readme.com) through ReadMe's
-[MCP](https://modelcontextprotocol.io/) server at `https://docs.readme.com/mcp`.
+| Client              | Plugin                | Marketplace manifest                | Install                                                                   |
+| ------------------- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
+| Cursor              | [`cursor/`](cursor/)  | `.cursor-plugin/marketplace.json`   | `/add-plugin readme`, or **Cursor Settings → Plugins**                    |
+| Claude              | [`claude/`](claude/)  | `.claude-plugin/marketplace.json`   | `/plugin marketplace add readmeio/agent-plugins`                          |
+| ChatGPT and Codex   | [`codex/`](codex/)    | `.agents/plugins/marketplace.json`  | `codex plugin marketplace add readmeio/agent-plugins`                     |
 
-Once connected, your assistant can search your guides and API reference, inspect your OpenAPI specs,
-draft changelog entries, and open documentation updates for review — without leaving the editor.
+Each plugin directory has its own README with install steps and auth setup.
 
-## Installation
+Claude and Codex take the repository itself as a marketplace from the command line, as above. Cursor
+has no CLI equivalent: teams add this repository under **Dashboard → Plugins → Team Marketplaces →
+Add Marketplace → Import from Repo**, and Cursor indexes it from the root manifest.
 
-### Cursor
+## Repository structure
 
-1. Open **Customize** in Cursor's sidebar.
-2. Find **ReadMe** in the marketplace.
-3. Select **Install** and choose project or user scope.
-4. Set your **ReadMe API key** when prompted (see below).
+The repository root is a marketplace for all three clients — it is not itself a plugin. Each client
+reads only its own marketplace manifest and ignores the others.
 
-### API key
-
-The server authenticates with a ReadMe API key. Open **Account Settings → API Keys** in ReadMe and
-create a key. Paste it into **Plugins → Configure** as **ReadMe API key**.
-
-The key decides which projects the assistant can reach, and grants read and write access to them.
-Rotate it from Account Settings if it is ever exposed.
-
-Once connected, ask Cursor to work with your docs, for example: "Find our authentication guide and
-add a section on refresh tokens."
-
-## MCP
-
-```json
-{
-  "mcpServers": {
-    "readme": {
-      "url": "https://docs.readme.com/mcp",
-      "headers": {
-        "Authorization": "Bearer ${README_API_KEY}"
-      }
-    }
-  }
-}
+```
+agent-plugins/
+├── .cursor-plugin/marketplace.json   # Cursor marketplace  → cursor
+├── .claude-plugin/marketplace.json   # Claude marketplace  → ./claude
+├── .agents/plugins/marketplace.json  # Codex marketplace   → ./codex
+├── skills/                           # Canonical skills — edit these
+├── cursor/
+│   ├── .cursor-plugin/plugin.json
+│   ├── mcp.json
+│   ├── skills/                       # Generated from ../skills
+│   ├── assets/logo.svg
+│   ├── README.md
+│   ├── CHANGELOG.md
+│   └── LICENSE
+├── claude/
+│   ├── .claude-plugin/plugin.json
+│   ├── .mcp.json
+│   ├── skills/                       # Generated from ../skills
+│   └── README.md
+├── codex/
+│   ├── plugin.json                   # Agent Plugins 1.0.0 manifest
+│   ├── mcp.json
+│   ├── skills/                       # Generated from ../skills
+│   └── README.md
+├── scripts/
+├── README.md
+└── LICENSE
 ```
 
-## Tools
-
-| Tool               | What it does                                                         |
-| ------------------ | -------------------------------------------------------------------- |
-| `search`           | Search guide pages, reference pages, and docs content by keyword     |
-| `fetch`            | Retrieve a specific guide or reference page by ID                    |
-| `update-docs`      | Open a documentation update on a new branch and return a review link |
-| `list-specs`       | List the OpenAPI specs available in the project                      |
-| `search-endpoints` | Search paths, operations, and parameters                             |
-| `list-endpoints`   | List all API paths and HTTP methods with summaries                   |
-| `get-endpoint`     | Get detail on one endpoint, including security schemes and servers   |
-| `execute-request`  | Execute an API request from a HAR request object                     |
-| `draft-changelog`  | Generate a changelog draft from merged GitHub PRs                    |
+## Skills
 
-`update-docs` writes to a new branch and returns a review link, so your published docs are never
-edited in place. `execute-request` sends a real request to the API in the spec.
+The three skills are agent-agnostic: anything a client does differently — registering an API key,
+driving a browser, installing the plugin by hand — is a per-client table inside the shared file, so
+there is one copy of every fact. They carry only what the MCP server cannot tell an agent at
+runtime; route maps come from `list-endpoints` and `get-endpoint`, not from a skill.
 
-## Which ReadMe MCP server is this?
+Edit `skills/` and nothing else, then regenerate the three published copies:
 
-ReadMe has two kinds of MCP server, and this plugin is the first one.
+```
+node scripts/sync-skills.mjs
+```
 
-**ReadMe's MCP server** (`https://docs.readme.com/mcp`) is what this plugin installs. You use it to
-manage the documentation in your own ReadMe project.
+CI runs `node scripts/sync-skills.mjs --check` and fails if a client copy has drifted. Each client
+ships its own directory because each marketplace submission reads only that directory.
 
-**Your project's MCP server** (`https://your-project.readme.io/mcp`) is the one ReadMe generates
-from your API spec for _your_ users. Every project has its own URL, so it cannot be installed from
-the marketplace. To connect to one, use the instructions published on that project's hub. See
-[your project's MCP server](https://docs.readme.com/main/docs/your-projects-mcp-server).
+## Authentication
 
-## Support
+All three plugins talk to the same endpoint, `https://docs.readme.com/mcp`, and all three ship
+anonymous. Without a key you get read-only access to public docs, which is enough for searching and
+reading, and none of the plugins prompt for anything on install.
 
-- **ReadMe’s MCP server:** https://docs.readme.com/main/docs/readmes-mcp-server
-- **Report issues:** https://github.com/readmeio/agent-plugins/issues
-- **Contact support:** support@readme.io
+Write tools such as `update-docs` need a ReadMe API key. That step is the user's, not the package's,
+because each client wires credentials differently and the Agent Plugins spec forbids putting them in
+a plugin at all: it requires headers to be literal package data with no secrets in them, and Codex
+strips `Authorization` from plugin MCP configs regardless. In every client the shape is the same,
+register the server yourself with the key and your entry replaces the plugin's anonymous one. Each
+plugin README has the exact snippet.
 
 ## License
 

claude/README.md

@@ -59,4 +59,14 @@ Keep the single quotes so Claude Code expands the variable at startup instead of
 
 One key maps to one project. To switch projects, change the exported key and restart.
 
-Claude Desktop Chat, Cowork and claude.ai cannot take an API key, so the plugin stays read-only there.
+Claude Desktop Chat, Cowork and claude.ai cannot take an API key, so the plugin stays read-only there.
+
+---
+
+## Skills
+
+| Skill | What it does |
+| ----- | ------------ |
+| `mcp-server` | Keeps the agent straight on which project and which spec a call lands in: this server reads ReadMe's own docs, while `execute-request` plus your key acts on yours |
+| `mcp-auth` | Establishes which key is in play and diagnoses the failures a missing or unresolved one produces |
+| `onboarding` | Walks a new customer from signup to a published hub and a working API key |