From e9246d6c81a9ec7bcee205c1b24c639006afc8e4 Mon Sep 17 00:00:00 2001 From: minhthanhdang <150941282+minhthanhdang@users.noreply.github.com> Date: Mon, 14 Sep 2026 11:47:31 +1000 Subject: [PATCH 1/6] ci: validate the Claude plugin on pull requests and main Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01ASm4dwg1vsKZ2jaecPi1zi --- .github/workflows/validate-claude-plugin.yml | 24 ++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .github/workflows/validate-claude-plugin.yml diff --git a/.github/workflows/validate-claude-plugin.yml b/.github/workflows/validate-claude-plugin.yml new file mode 100644 index 0000000..080a69b --- /dev/null +++ b/.github/workflows/validate-claude-plugin.yml @@ -0,0 +1,24 @@ +name: Validate Claude plugin + +on: + pull_request: + paths: + - 'claude/**' + - '.github/workflows/validate-claude-plugin.yml' + push: + branches: [main] + paths: + - 'claude/**' + - '.github/workflows/validate-claude-plugin.yml' + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: npm install -g @anthropic-ai/claude-code + - run: claude plugin validate --strict claude + - run: claude plugin validate --strict claude/.claude-plugin/plugin.json From 8a4e0daa15ba6fbeb72d182c0c3eae1bfda6fad5 Mon Sep 17 00:00:00 2001 From: minhthanhdang <150941282+minhthanhdang@users.noreply.github.com> Date: Tue, 15 Sep 2026 07:56:33 +1000 Subject: [PATCH 2/6] ci: validate the root marketplace too Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KDoRbmzuRVJ6Ev9MPEmLm5 --- .github/workflows/validate-claude-plugin.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/validate-claude-plugin.yml b/.github/workflows/validate-claude-plugin.yml index 080a69b..abf4450 100644 --- a/.github/workflows/validate-claude-plugin.yml +++ b/.github/workflows/validate-claude-plugin.yml @@ -4,11 +4,13 @@ on: pull_request: paths: - 'claude/**' + - '.claude-plugin/**' - '.github/workflows/validate-claude-plugin.yml' push: branches: [main] paths: - 'claude/**' + - '.claude-plugin/**' - '.github/workflows/validate-claude-plugin.yml' jobs: @@ -21,4 +23,4 @@ jobs: node-version: 22 - run: npm install -g @anthropic-ai/claude-code - run: claude plugin validate --strict claude - - run: claude plugin validate --strict claude/.claude-plugin/plugin.json + - run: claude plugin validate --strict .claude-plugin/marketplace.json From 985dd4dbd2603dfddd1a0e899646eae8437627ec Mon Sep 17 00:00:00 2001 From: minhthanhdang <150941282+minhthanhdang@users.noreply.github.com> Date: Tue, 15 Sep 2026 08:09:29 +1000 Subject: [PATCH 3/6] ci: run validation on every pull request Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KDoRbmzuRVJ6Ev9MPEmLm5 --- .github/workflows/validate-claude-plugin.yml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/.github/workflows/validate-claude-plugin.yml b/.github/workflows/validate-claude-plugin.yml index abf4450..d2b86fb 100644 --- a/.github/workflows/validate-claude-plugin.yml +++ b/.github/workflows/validate-claude-plugin.yml @@ -2,16 +2,8 @@ name: Validate Claude plugin on: pull_request: - paths: - - 'claude/**' - - '.claude-plugin/**' - - '.github/workflows/validate-claude-plugin.yml' push: branches: [main] - paths: - - 'claude/**' - - '.claude-plugin/**' - - '.github/workflows/validate-claude-plugin.yml' jobs: validate: From e8e8803bd66b62401a24270a9e774b4f63bb5c76 Mon Sep 17 00:00:00 2001 From: minhthanhdang <150941282+minhthanhdang@users.noreply.github.com> Date: Tue, 15 Sep 2026 08:58:40 +1000 Subject: [PATCH 4/6] ci: drop the workflow token to read-only Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KDoRbmzuRVJ6Ev9MPEmLm5 --- .github/workflows/validate-claude-plugin.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/validate-claude-plugin.yml b/.github/workflows/validate-claude-plugin.yml index d2b86fb..3c02353 100644 --- a/.github/workflows/validate-claude-plugin.yml +++ b/.github/workflows/validate-claude-plugin.yml @@ -5,6 +5,9 @@ on: push: branches: [main] +permissions: + contents: read + jobs: validate: runs-on: ubuntu-latest From 7299656529198f5260022575ab1a4d5bb9aa4ac2 Mon Sep 17 00:00:00 2001 From: minh <150941282+minhthanhdang@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:11:33 +1000 Subject: [PATCH 5/6] feat(codex): add codex plugin and root marketplace (#3) --- .agents/plugins/marketplace.json | 12 ++++++ codex/README.md | 27 +++++++++++++ codex/assets/icon.svg | 3 ++ codex/assets/logo.svg | 4 ++ codex/mcp.json | 9 +++++ codex/plugin.json | 32 +++++++++++++++ codex/skills/onboarding/SKILL.md | 69 ++++++++++++++++++++++++++++++++ 7 files changed, 156 insertions(+) create mode 100644 .agents/plugins/marketplace.json create mode 100644 codex/README.md create mode 100644 codex/assets/icon.svg create mode 100644 codex/assets/logo.svg create mode 100644 codex/mcp.json create mode 100644 codex/plugin.json create mode 100644 codex/skills/onboarding/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..800546b --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "readme", + "interface": { "displayName": "ReadMe" }, + "plugins": [ + { + "name": "readme", + "source": { "source": "local", "path": "./codex" }, + "policy": { "installation": "AVAILABLE" }, + "category": "Productivity" + } + ] +} diff --git a/codex/README.md b/codex/README.md new file mode 100644 index 0000000..e9aa817 --- /dev/null +++ b/codex/README.md @@ -0,0 +1,27 @@ +# ReadMe plugin for ChatGPT and Codex + +Connects ChatGPT and Codex to the [ReadMe MCP server](https://docs.readme.com/main/docs/readmes-mcp-server) so the model can search, read, and update your ReadMe docs and API reference. + +## Install + +The repository root is a Codex plugin marketplace. Add it, then install the plugin: + +``` +codex plugin marketplace add readmeio/agent-plugins +codex plugin add readme@readme +``` + +For a local checkout, pass the checkout path to `codex plugin marketplace add` instead. Start a new Codex session after installing so the skills and MCP server load. + +## Authentication + +Public read access works without any setup. + +Write tools such as `update-docs` need your ReadMe API key. Codex strips `Authorization` headers from plugin MCP configs, so register the server yourself once with the key read from an environment variable: + +``` +export README_API_KEY=rdme_… +codex mcp add readme --url https://docs.readme.com/mcp --bearer-token-env-var README_API_KEY +``` + +Your `readme` entry replaces the plugin's anonymous one. The skills keep working because the server name is unchanged. Find your key under **Configuration → API Keys** in your ReadMe project dashboard. diff --git a/codex/assets/icon.svg b/codex/assets/icon.svg new file mode 100644 index 0000000..7a9fa26 --- /dev/null +++ b/codex/assets/icon.svg @@ -0,0 +1,3 @@ + + + diff --git a/codex/assets/logo.svg b/codex/assets/logo.svg new file mode 100644 index 0000000..d9b19dd --- /dev/null +++ b/codex/assets/logo.svg @@ -0,0 +1,4 @@ + + + + diff --git a/codex/mcp.json b/codex/mcp.json new file mode 100644 index 0000000..7abb4ee --- /dev/null +++ b/codex/mcp.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "readme": { + "type": "streamable-http", + "url": "https://docs.readme.com/mcp" + } + } +} diff --git a/codex/plugin.json b/codex/plugin.json new file mode 100644 index 0000000..ed75dd6 --- /dev/null +++ b/codex/plugin.json @@ -0,0 +1,32 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "readme", + "version": "1.0.0", + "description": "ReadMe MCP server packaged as a plugin. Search, read, and update your ReadMe docs and API reference from your editor.", + "author": { "name": "ReadMe", "url": "https://readme.com" }, + "homepage": "https://docs.readme.com/main/docs/readmes-mcp-server", + "repository": "https://github.com/readmeio/agent-plugins", + "license": "MIT", + "keywords": ["readme", "documentation", "mcp", "openapi"], + "extensions": { + "com.openai": { + "interface": { + "displayName": "ReadMe", + "shortDescription": "Search, read, and update your ReadMe docs and API reference.", + "longDescription": "Connects ChatGPT and Codex to the ReadMe MCP server so the model can list API specs, inspect endpoints, search documentation, and follow ReadMe's documentation workflows.", + "developerName": "ReadMe", + "category": "Productivity", + "logo": "./assets/logo.svg", + "composerIcon": "./assets/icon.svg", + "capabilities": ["Read", "Write"], + "websiteURL": "https://readme.com", + "privacyPolicyURL": "https://readme.com/privacy", + "termsOfServiceURL": "https://readme.com/tos", + "defaultPrompt": [ + "Use ReadMe to list the endpoints in the ReadMe API.", + "Use ReadMe to explain how to create a docs branch." + ] + } + } + } +} diff --git a/codex/skills/onboarding/SKILL.md b/codex/skills/onboarding/SKILL.md new file mode 100644 index 0000000..3643e13 --- /dev/null +++ b/codex/skills/onboarding/SKILL.md @@ -0,0 +1,69 @@ +--- +name: onboarding +description: Get a new customer from zero to a live ReadMe developer hub. Use when someone is new to ReadMe, asks what ReadMe is, wants to sign up, create a project, publish their first API reference or guide, or needs an API key for this plugin. Explains the product and walks the web-UI setup flow. +--- + +# ReadMe onboarding + +> Onboarding endpoints are coming soon. Until then this skill only covers the web-UI flow and ReadMe basics. + +## What ReadMe is + +ReadMe hosts a developer hub for your API at `{subdomain}.readme.io` or a custom domain. One hub contains: + +| Section | Content | +| --- | --- | +| Guides | Markdown pages in categories, with a sidebar | +| API Reference | Interactive docs generated from an OpenAPI or Swagger definition, with a Try It console | +| Recipes | Step-by-step code walkthroughs | +| Changelog | Release notes, shared across versions | +| Custom Pages | Free-form Markdown or HTML pages | + +Guides, reference, recipes and custom pages live on a **branch** (a version such as `1.0` or `stable`). The changelog does not. Ask AI and the project's MCP server answer questions from the hub content. Metrics track page views, search, page quality, and, with SDK setup, API calls. + +Plans: Starter (free), Pro, Enterprise. Enterprise supports child projects and Developer Metrics API reads. + +## Quick Start + +1. Sign up at `https://dash.readme.com/signup`. +2. Click **Create New Project**. Set a name, upload a logo (ReadMe picks brand colors from it), and choose the subdomain. +3. Add the API definition under **API Reference**: upload an OpenAPI file, import a URL, build one from scratch, or run `npx rdme openapi upload ` from a terminal. ReadMe validates the file and renders every endpoint. +4. Write the first guide under **Guides**. Use the AI Agent for a draft or the editor for a blank page. A "Getting Started" page is the usual first one. +5. Generate an API key at **Configuration → API Keys**, URL `https://dash.readme.com/project/{subdomain}/v{version}/api-key`. +6. Attach the key. The plugin's own `readme` server is anonymous and cannot read the key. The user registers a server with the same name, which replaces the plugin's one, then exports the key in the shell that starts Codex and starts a new session. In Codex: + + ``` + export README_API_KEY=rdme_… + codex mcp add readme --url https://docs.readme.com/mcp --bearer-token-env-var README_API_KEY + ``` + + Codex reads the variable at startup, so the key never lands in a config file. The ChatGPT desktop app shares Codex's config, so this registration also covers Codex sessions there. In Claude Code the equivalent is `claude mcp add --scope user --transport http readme https://docs.readme.com/mcp --header 'Authorization: Bearer ${README_API_KEY}'`. Not possible in ChatGPT web; see the section below. +7. Verify: `readme:execute-request` with spec title `ReadMe API`, `GET https://api.readme.com/v2/projects/me`. A 200 with the project name means the plugin is wired to the right project. A 500 titled `An unknown error has occurred.` means the key is missing or wrong; go back to step 5. + +After step 7, load the `readme-api` skill for anything else in the project. + +## Doing it with the ChatGPT browser + +Steps 1 to 5 are all browser work. In the ChatGPT desktop app or ChatGPT web, offer to drive them with `@Browser` instead of only listing the steps: open the signup page, create the project, and open the API Keys page. The built-in browser has its own profile, so the user signs in to ReadMe there and types credentials and payment details themselves; ChatGPT asks before submitting forms. It cannot upload files, so for step 3 import the OpenAPI definition by URL or run `npx rdme openapi upload ` from Codex. Codex CLI and the IDE extension have no browser; list the steps there. Steps 6 and 7 stay in the terminal. + +## When you cannot install anything yourself + +In a ChatGPT chat, desktop or web, you have no shell and cannot add a marketplace, install a plugin or edit MCP config. Do not attempt it and do not ask the user to run commands in the chat. If the `readme:*` tools are missing, the user has to install the plugin by hand. Give them these steps exactly: + +- ChatGPT desktop app: open the **Plugins** tab and click **Add marketplace**. Enter `readmeio/agent-plugins` as the source, leave the Git ref as `main` and the sparse paths empty, then click **Add marketplace**. Install **readme** from the new marketplace and start a new chat so the tools load. +- ChatGPT web: there is no marketplace option, only the plugin directory. Until the ReadMe plugin is listed there, the user can still add the MCP server on its own: turn on **Developer mode** under **Settings → Security and login**, open **Plugins**, click **+** next to the search box, and in the **New Plugin** form set the name to `readme`, the server URL to `https://docs.readme.com/mcp`, and authentication to **No Auth**. That gives the `readme:*` tools but not the skills, so keep this skill's content in the conversation yourself. + +Once installed, the ReadMe connector in a chat is read-only: `readme:search`, `readme:fetch` and the endpoint tools work on public projects, but ChatGPT cannot take an API key, so steps 6 and 7 of the Quick Start do not apply and write tools such as `readme:update-docs` fail. Say so before the user tries. For creating or updating pages, offer to continue in Codex with the server registered as in step 6. + +## Reading the docs meanwhile + +Use `readme:search` for a question, then `readme:fetch` with the returned id. Useful pages: + +| Id | Page | +| --- | --- | +| `main/quickstart` | Three-step setup | +| `main/creating-a-project` | Project settings on creation | +| `main/openapi-upload-and-management` | Upload, sync, and re-sync an OpenAPI file | +| `main/branches` | How branches and versions work | +| `ref:main/intro-to-the-readme-api` | API v2 overview and auth | +| `main/sdks` | Metrics SDKs for API logs | From 7437ce9a89c41209f7ca1b2e844cc72fcbe3d0b2 Mon Sep 17 00:00:00 2001 From: minhthanhdang <150941282+minhthanhdang@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:17:14 +1000 Subject: [PATCH 6/6] docs(onboarding): drop the pointer to a skill this plugin does not ship Co-Authored-By: Claude Opus 5 --- codex/skills/onboarding/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/codex/skills/onboarding/SKILL.md b/codex/skills/onboarding/SKILL.md index 3643e13..bdc5718 100644 --- a/codex/skills/onboarding/SKILL.md +++ b/codex/skills/onboarding/SKILL.md @@ -40,8 +40,6 @@ Plans: Starter (free), Pro, Enterprise. Enterprise supports child projects and D Codex reads the variable at startup, so the key never lands in a config file. The ChatGPT desktop app shares Codex's config, so this registration also covers Codex sessions there. In Claude Code the equivalent is `claude mcp add --scope user --transport http readme https://docs.readme.com/mcp --header 'Authorization: Bearer ${README_API_KEY}'`. Not possible in ChatGPT web; see the section below. 7. Verify: `readme:execute-request` with spec title `ReadMe API`, `GET https://api.readme.com/v2/projects/me`. A 200 with the project name means the plugin is wired to the right project. A 500 titled `An unknown error has occurred.` means the key is missing or wrong; go back to step 5. -After step 7, load the `readme-api` skill for anything else in the project. - ## Doing it with the ChatGPT browser Steps 1 to 5 are all browser work. In the ChatGPT desktop app or ChatGPT web, offer to drive them with `@Browser` instead of only listing the steps: open the signup page, create the project, and open the API Keys page. The built-in browser has its own profile, so the user signs in to ReadMe there and types credentials and payment details themselves; ChatGPT asks before submitting forms. It cannot upload files, so for step 3 import the OpenAPI definition by URL or run `npx rdme openapi upload ` from Codex. Codex CLI and the IDE extension have no browser; list the steps there. Steps 6 and 7 stay in the terminal.