ReadMe

View saved version →

---
name: edit-page-content
description: Create or edit documentation pages in ReadMe, including guides, API reference prose, changelogs, discussions, recipes, and custom pages.
---

# Edit ReadMe page content

## Workflow

1. **Target + Method.** Unless the user has specified directly to you, use the `managing-readme-docs` skill to understand whether you are using MCP or BiDi Sync to make changes, ensure you are working on the right project and targeting the right branch. Identify the page type and whether this is a new page or an edit; use the page-type table below for paths and scope.
   **Done:** The project, write surface, section, page identity, and applicable branch are explicit.
2. **Locate and read.** For updates, read relevant files by searching and finding.
   For MCP use the `/v2/search` endpoint via `execute-request` and if search is insufficient, retrieve categories for the section (`v2/branches/{branch}/categories/{section}`) then pages within categories (`/v2/branches/{branch}/categories/{section}/{title}/pages`)
   **Done:** The exact page and full current body/metadata are available, or the new page's category and slug are agreed.
3. **Draft** Ensure that you have a strong idea of what the user wants, and what you can use in the page. Refer to the [ReadMe docs mdx page](https://docs.readme.com/main/docs/mdx.md) to understand how to write valid MDX. A good page uses components wherever they make the content easier to read: look for places each one fits, but never force one onto content that doesn't suit it. Follow [COMPONENTS.md](COMPONENTS.md) for when to use each built-in component and how to format it, and use reusable content where it fits (see below). Apply the page-type concerns below.
4. **Write**:
   - Use available tools to update content
   - For MCP when creating MDX you MUST apply your changes in full
   **Done:** changes successfully applied
5. **Verify.** Fetch content if using MCP, or check git status for local documentation
   **Done:** The saved result match your applied changes.

## Components and reusable content

| Type | What it is | Docs |
| --- | --- | --- |
| Built-in components | Available in every project: Tabs, Accordion, Cards, and Columns, plus callouts, tabbed code blocks, images, and embeds | [Built-in components](https://docs.readme.com/main/docs/built-in-components.md); best practices in [COMPONENTS.md](COMPONENTS.md) |
| Custom components | JSX components a project defines under **Settings → Custom Components**, or adds from the component marketplace. Used in pages by tag name, like built-ins. Pro and Enterprise plans only | [Custom components](https://docs.readme.com/main/docs/building-custom-mdx-components.md) |
| Reusable content | Named Markdown blocks managed under **Editor → Reusable Content**. Editing a block updates every page that uses it. Pro and Enterprise plans only | [Reusable content](https://docs.readme.com/main/docs/reusable-content.md) |

- Prefer an existing component or reusable block over raw HTML or content copied between pages.
- There is no way for you as an agent to make custom components/reusable components yet - the user must make them on their ReadMe docs site.
- Never invent custom component or reusable block names. Only use ones already present in the project's pages, or ones the user names. If unsure, ask.
- Editing a page that contains a reusable block does not change the block. Changes to the block itself happen in the Reusable Content editor in the user's docs site.
- If the user wants a new custom component or reusable block, give them instructions for how to do this and direct them to their ReadMe docs site.

## Page Types and linking

Unless the site already uses an alternative linking style for intra-project links (same subdomain), prefer root-relative `/section/{slug}` links with descriptive text: `[Authentication](/docs/authentication)`. Use full URLs for external sites or canonical page URLs.

| Page type | Authoring concern | Preferred path | URI alternative |
| --- | --- | --- | --- |
| Guides | Narrative docs organized into categories | `/docs/{slug}` | `doc:{slug}` |
| API reference | Prose pages or endpoint descriptions; distinguish from spec changes | `/reference/{slug}` | `ref:{slug}` |
| Changelogs | Release notes and publication state | `/changelog/{slug}` | `changelog:{slug}` |
| Custom pages | Standalone content that does not fit well into other sections - ie marketing content, announcement pages | `/page/{slug}` | — |
| Recipes | Step-by-step code walkthroughs | `/recipes/{slug}` | — |
| Discussions | Discussions and replies | `/discuss/{id}` | — |

Recipes and discussions use path links, not URI shorthand; `discuss:{id}` does not work. Discussion paths use the topic ID, e.g. `/discuss/6a869f581a29b3127d3ab2d2`.

Slugs are flat: parent/child sidebar relationships never add URL segments. Prefer the slug used in URLs returned by ReadMe when available.

Heading anchors derive from heading text using GitHub-style rules, e.g. `Creating your first guide` → `#creating-your-first-guide`. You will not be able to see anchors on pages by reading them - so apply github-style rules on any headings you see to create anchor links.

For endpoint definition changes, identify the authoritative OpenAPI source and follow [OpenAPI management](https://docs.readme.com/main/docs/openapi-upload-and-management.md); keep these separate from prose edits.

## Documentation Best Practices (helpful resources)

ReadMe's docs on [creating and managing guides](https://docs.readme.com/main/docs/creating-and-managing-guides.md
) contains useful information and best practices for all documentation types.
ReadMe's docs on [BiDi sync](https://docs.readme.com/main/docs/bi-directional-sync)

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: manage-navigation
description: Organize docs side navigation in ReadMe including category management, page management, changing page titles and urls and more.
---

# Manage ReadMe navigation

## Workflow

1. **Target + Method.** Unless the user has specified directly to you, use the `managing-readme-docs` skill to understand whether you are using MCP or BiDi Sync to make changes, ensure you are working on the right project and targeting the right branch. Identify the page type and whether this is a new page or an edit; use the page-type table below for paths and scope.
   **Done:** The project, write surface, section, page identity, and applicable branch are explicit.
2. **Understand How to Manage ReadMe Navigation.** Read through the #readme-navigation-hierarchy section to understand mechanically how ReadMe's site navigation works. To understand best practices around site structure and navigation refer to Readme's [Structuring your docs](https://docs.readme.com/main/docs/structuring-your-docs.md) page.
   **Done:** The affected navigation and its project/branch are known.
3. **Plan.** Show the proposed before/after structure, including page identities, destination categories, order, title versus slug changes, and removals. This should be in a simple to read structure for the user - you don't need to get bogged down in ReadMe's technical concepts. Tree-esque views work well. Check inbound links when URLs change. Explain destructive effects and obtain explicit approval for deletion.
   **Done:** The desired structure and any destructive/URL-changing actions are approved.
4. **Apply.** Depending on the method (local via BiDi Sync or via MCP), make edits.
   **Done:** Every approved structural change has a result, with any partially completed sequence recorded.
5. **Verify.** Re-read over changes and verify against the plan that the user agreed to.
   **Done:** The resulting structure matches the plan or every discrepancy is reported.

## ReadMe Navigation Hierarchy

ReadMe's navigation style is section-dependent. In BiDi synced repositories sections are the folders at root level - ie `docs/` and `reference/`. Refer to the [documentation structure page](https://docs.readme.com/main/docs/documentation-structure) to understand how to structure BiDi git repositories.

### Categories

Categories are not pages - but are the top-level containers that exist in the UI for certain sections. In BiDi synced repositories these correspond to the folders that exist within section folders.

Categories only exist in the guides and API reference sections - and only have a name, no description.

#### Key MCP Operations

- Get all categories in a section - GET https://api.readme.com/v2/branches/{branch}/categories/{section}
- Get all pages in a category - GET https://api.readme.com/v2/branches/{branch}/categories/{section}/{title}/pages

### Guides & API Reference

In the guides (under /docs/{slug}) and API reference (under /reference/{slug}) section all pages must exist under a category. Existing under a category does not mean that it is at the root-level of the category, because pages within these sections can have parent pages.

Parent pages (#empty-vs-non-empty-parent-pages) are normal pages within that category, and to assign a page as the parent of a page set the `parent` on the page as the slug of that page (note that parents must be from the same section) via the create/update endpoint of that section type.

Pages with no `parent` are at the root of the category.

To order pages under a parent page/category:

- For MCP: set the `position` of the page. This is 0-based, and setting to an index that already has a page will push that page, and all pages with a greater index lower.
- For BiDi sync: each folder in `docs/` and `reference/` contains an `order.yml` file that dictates the order. Each .mdx page in the folder must be present in the `order.yml` file without its file extension, in the order you want to show it in:
   ```yml
   - fileNameA
   - fileNameC
   - fileNameB
   ```
   To have the pages in that be ordered A, C, B.

#### Empty vs Non-empty Parent Pages

Empty parent pages, being those with a null/empty `content` in them, act as a dropdown in the UI rather than a page. Clicking them will expand the dropdown and auto-select the first child page under it.

Non-empty parent pages, on click, will select the page and reveal the pages underneath it.

- Guides
- API References

#### Key MCP operations

- Update the position of a guide page (setting its `parent`, `position`, `category`): PATCH https://api.readme.com/v2/branches/{branch}/guides/{slug}
- Update the position of an API reference page (setting its `parent`, `position`, `category`): PATCH https://api.readme.com/v2/branches/{branch}/reference/{slug}
- Create an empty parent guides page (providing no `content`): POST https://api.readme.com/v2/branches/{branch}/guides
- Create an empty parent API Reference page (providing no `content`): POST https://api.readme.com/v2/branches/{branch}/reference

### Recipes

Recipes have a single landing page, and all recipes have a `position` on that page. This is a 0-based position that the recipe appears on the page as.

A single recipe can be set to be the "featured" recipe on the home page, which is shown in a preview, however this must be set in the ReadMe UI.

#### Key MCP Operations

- Update the position of a recipe (setting its `position` attribute) - PATCH https://api.readme.com/v2/branches/{branch}/recipes/{slug}

### Changelogs

Changelogs appear in chronological order, and can only have their order changed by updating the `created_at` date - this is considered the published time.

#### Key MCP Operations

- Update the position of a changelog (setting its `created_at` which is its published datetime) - PATCH https://api.readme.com/v2/changelogs/{identifier}

### Discussions

Discussions are in chronological order and cannot have their position updated.

## Hiding Content

Guides, changelogs, API references and recipes can all be hidden from users by setting `hidden` on the content.

Note that even with a page being hidden, users with the exact URL can still read the content provided they can access the website. Therefore, hiding content is more about hiding the content from the visible side navigation rather than entirely hiding the content.

#### Key MCP Operations

- Any create/update endpoint for relevant sections

### Hiding Categories

To hide a category, it must be empty, or all of its immediate children must have `hidden` of true. Child pages of those pages can be public, and that will still not expose the category in the navigation.

### If a Parent Page is Hidden

If a page has a parent page that is hidden, regardless of whether the child page is public, it will be hidden as well.

## Page Navigation Titles and Icons

The text that is shown in navigation UI for all page sections are the titles of the content themselves (for discussions this is the title that the user sets when asking their question). Therefore it is recommended for all page titles are kept brief for ease of navigation.

Guides and API Reference are the only sections that allow for icons to be set. These icons are any valid "regular" or "duotone" font-awesome icons, or unicode emoji, and appear to the left of the page title in the side navigation. Recipes can have an Emoji that shows at the recipe homepage.

Generally, it is recommended that:

- Guides: pages at category-level use icons, but child pages do not
- API Reference: Don't use icons for a less-busy aesthetic
- Recipes: Use an emoji that best represents the recipe

#### Key MCP Operations

- Any create/update endpoint for relevant sections

View saved version →

---
name: managing-readme-docs
description: Shared reference for working on a ReadMe project, covering MCP routing, project sections, Git-backed docs (BiDi Sync), and confirming the active project and branch. Use before reading or changing documentation hosted on ReadMe.
---

# Working on a ReadMe project

Shared reference for project operations. Read the sections needed by the current workflow.

## MCP routing

Use [ReadMe's MCP server](https://docs.readme.com/main/docs/readmes-mcp-server) and its `execute-request` tool to read and maintain documentation hosted on ReadMe.

Use the MCP-server exposed `list-specs`, `list-endpoints`, `get-endpoint` and `search-endpoints` tools to search and understand the operations that can be performed on your documentation via the MCP server. These discovery tools describe ReadMe's APIs, not your endpoints/API reference hosted at ReadMe.

The `fetch` and `search` tools can be used to read through ReadMe's own documentation, hosted ad https://www.docs.readme.com.

Route project analytics separately: page views, search terms, and page quality belong to the `Developer Metrics API` spec, not the `ReadMe API` spec. Discover the available operation and inspect schema before calling endpoints.

## ReadMe Sections

A ReadMe project is organised into sections, and a page belongs to exactly one of them.

- **Guides** — prose documentation: concepts, how-tos, tutorials, onboarding. The main body of most projects, and where content belongs when no other section fits.
- **API Reference** — largely consisting of endpoint ("API") pages (documenting one HTTP method on one endpoint) backed by an OpenAPI definition. The section also holds prose ("API Reference") and webhook pages, which do not include any API schema. API Endpoint pages are commonly created from an uploaded OpenAPI Specification (OAS spec)
- **Changelog** — dated entries announcing releases and changes.
- **Custom pages** — standalone pages outside of other doc sections that generally aren't related to documentation, such as landing or marketing pages.
- **Recipes** — step-by-step code walkthroughs. A recipe is a code sample broken into ordered steps with per-step annotations and line highlighting, not prose with snippets in it. Structured content, edited through its own tooling rather than as markdown.
- **Discussions** — reader-generated community threads and questions.

Do not describe a page as belonging to a section other than the one it is actually in: a guide about a recipe is still a guide.

## Git backed documentation

ReadMe documentation is git-backed, meaning that ReadMe supports:

- Branches and versioning of documentation:
  - Each project has a single "Stable" branch (commonly v1.0, v2.0, ...)
  - By default operations will be applied to the stable branch **unless otherwise specified in a request**
  - Always be cautious when writing to a stable branch - any changes will be immediately visible to users.
  - It is recommended to make changes in branches, then merge branches into stable versions after getting approval for these (ReadMe UI offers an approval process)
- Bi-Directional Synchronization (aka "BiDi Sync") 
  - Users can setup BiDi Sync on a docs repository so that they can make changes to a repository and push those changes, rather than making changes through ReadMe's UI/API/MCP server
  - Configuring BiDi Sync is not supported via MCP and must be done via the UI
  - Github and Gitlab are supported, with BitBucket in beta (contact support)
  - **If you have been instructed to make documentation changes in a docs repository (contains `docs/`, `reference/` etc.) or the user has specified that this is a bi-di synced repository, then make changes via git operations rather than via the MCP server.

## Confirming the active Project

Use the `execute-request` tool to execute a request against the `/v2/projects/me` to get information on the current project. If this project conflicts with what the user is asking for, or if there is an issue connecting to the project use the `mcp-auth` skill to work with the user to setup their project.

If the user is performing first-time setup on ReadMe use the `setup-project` skill.

## Confirm Branch

For branch-scoped work, use the user's explicit target. If none was given, ask whether to use a named/new branch or the project's stable branch, and wait before writing. A ReadMe branch is a product branch/version, not automatically a local Git branch.

Use [ReadMe branches](https://docs.readme.com/main/docs/branches) when choosing or creating a target. Check each operation's scope: project-wide changes are not isolated by selecting a docs branch.

**NEEDS_INPUT — Scope map:** Document which page types and settings are branch-scoped, project-wide, and Git-backed, with canonical documentation links. Confirm changelog and discussion behavior separately.

## Documentation Management Mechanism

If you are in a documentation repository, use git to manage documentation via BiDi Sync unless the user has specified otherwise. Use MCP if you are not in a docs repository.
Note - project settings (styling etc.) must be managed via MCP or via UI, there is no BiDi Sync for these.

Consult the [BiDi Sync](https://docs.readme.com/main/docs/bi-directional-sync) documentation for more information on bi-directional sync.

## Detailed Workflows

Use the following skills to assist the user:

- `edit-page-content`: Understand how to write valid MDX, using custom-components and more for when a user wants to update pages
- `manage-navigation`: How to manage categories, move pages between categories, reorder pages within categories
- `mcp-auth`: How to authenticate with the MCP server and MCP Auth constraints
- `setup-project`: First-time project setup for ReadMe projects
- `update-project-settings`: View and update project-wide settings such as appearance, AI, MCP, SEO, and access

View saved version →

---
name: mcp-auth
description: Configure authentication with ReadMe to manage documentation hosted on ReadMe. Use during first time setup, or when a project operation is rejected for missing, invalid, expired, or unresolved authentication.
---

# Recover ReadMe MCP authentication

## Workflow

1. **Classify.** Capture the failing operation and non-secret error response. Check whether the response actually indicates missing/rejected credentials rather than validation, insufficient permissions, plan restrictions, or a service outage.
   **Done:** There is an authentication failure to repair, or the error is handed back to its owning workflow.
2. **Identify the environment.** Establish the client that you are running in (for example Claude Code versus Claude Desktop Chat). Commonly you will have information available about the client and surface that you are running in; ask if unclear. Read only the matching [client connection reference](CLIENTS.md).
   **Done:** You understand what client you are running in, and have rea the client connection reference for that client.
3. **Setup.** If you have the API key already in the chat for the project the user is attempting to modify, and the client is one that you can update settings for without user's intervention then setup the connection yourself. Otherwise Direct the user to the intended ReadMe project's **Settings → API Keys** to get their API key (if you have the link to their documentation page, this is accessed by adding "#/settings/api-keys" to any url in that domain). If the client is one where you can configure the MCP configuration yourself, offer to setup the environment if they give you the API key, and tell them that they can setup the configuration themselves and give them the steps to do so.
   **Done:** The user confirms the credential is configured, or you have setup yourself.
4. **Verify and resume.** Use the `https://api.readme.com/v2/projects/me` endpoint via the MCP's `execute-request` to determine whether the correct project has been authenticated. After this, resume with the original operations that the user was attempting to do.
   **Done:** The intended project is reachable and the original workflow resumes, or the unresolved error is reported without repeated guesses.

## First time account setup

New accounts and projects are created through the `setup-project` skill - follow it rather than creating an account from here. If the user has an existing account, they must create their project via the UI and provide the API Key.

## Authentication scope

ReadMe API keys are scoped to a single project only. To edit multiple projects, it is recommended that you set up multiple MCP clients under different names - ie "docs-projectNameA", "docs-projectNameB" and set these up with their individual, project-based API keys.

ReadMe does not currently offer OAuth via MCP.

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: mcp-server
description: Route ReadMe MCP calls to the right project and the right spec. Use before any request touching the user's own content - "our docs", "my hub", "create a page", "update the changelog", "what endpoints do we have", "search our guides", "how many page views", "top search terms", "send our API logs to ReadMe" - and before calling execute-request for the first time in a session.
---

# Which project does this call land in?

This plugin connects to `https://docs.readme.com/mcp`, which serves **ReadMe's own documentation**.
`search` and `fetch` answer questions about how ReadMe works. The user's project is reached only
through `execute-request` with their API key. Reads and writes land in different places.

Questions about ReadMe itself need nothing else: use `search` and `fetch` and answer.

## Tools on this server

| Tool | Answers for | Use it when |
| --- | --- | --- |
| `search`, `fetch` | ReadMe's own product documentation | The question is about how ReadMe works |
| `list-specs`, `list-endpoints`, `get-endpoint`, `search-endpoints` | ReadMe's API definitions, as documents | Looking up a route before calling it |
| `execute-request` | **The user's project**, with their key | Reading or changing anything of theirs |
| `update-docs`, `draft-changelog` | Nothing. They return instructions for you to carry out | You want the recommended procedure |

Tool availability is per-project configuration, not a fixed list. Call `tools/list` rather than
assuming a tool named here is present, and never assume one that is not.

## The three specs

`execute-request` reaches only servers declared in these definitions. There are three, and
`search-endpoints` searches all of them at once:

| Spec title | Server | Auth |
| --- | --- | --- |
| `ReadMe API` | `https://api.readme.com/v2` | Bearer `rdme_...` |
| `Developer Metrics API` | `https://metrics.readme.io` | HTTP basic, the key as username and an empty password |
| `Legacy API` | `https://dash.readme.com/api/v1` | HTTP basic |

**Use `ReadMe API` for all work on the user's content.** `Legacy API` is v1: it takes basic auth
rather than a bearer token, and it is unavailable to projects on ReadMe Refactored. `search-endpoints`
will surface its routes alongside the others — ignore them. Never fall back to v1 when a v2 call
fails.

## Finding a route

Do not guess paths or work from memory. `list-endpoints` returns every path and summary in a spec in
one cheap call; `get-endpoint` adds the full request and response schema for one of them, including
which routes exist only on ReadMe Refactored. Read them rather than reproducing them here.

Two things the definitions do not tell you:

- Paginated responses carry `paging.next`, `paging.previous`, `paging.first` and `paging.last`.
  Query with `page` and `per_page`, max 100 and max 50 on search.
- Enterprise child projects need the child's own key. Only the API-key routes take a `{subdomain}`,
  and `me` works there.

## Calling execute-request

```json
{
  "title": "ReadMe API",
  "harRequest": {
    "method": "get",
    "url": "https://api.readme.com/v2/projects/me"
  }
}
```

- `title` names the spec and is required whenever the server carries more than one, as this one does.
  Omitting it fails validation before the request is made.
- `url` must be absolute. `get-endpoint` and `search-endpoints` report paths relative to the server
  (`/projects/me`), so prepend `https://api.readme.com/v2` rather than pasting the path through.
- The key decides which project the call lands in, and the user cannot override it per-request.
  Name the project before you change anything; asking them which one to write to is misleading.

Setting up, verifying, or repairing that key is the `mcp-auth` skill.

## When the user asks about their own docs

"Search our docs", "what does our guide say", "find the page about X in my project" cannot be
answered by `search` or `fetch` here. Those read ReadMe's documentation and would return confident,
wrong answers about someone else's content.

Their key already reaches their content through the ReadMe API, so switch tools and carry on rather
than sending them away to configure anything:

| They want | Call, via `execute-request`, spec title `ReadMe API` |
| --- | --- |
| Search their content | `GET https://api.readme.com/v2/search?query=...`, optionally `section`, `version`, `projects` |
| Read one guide | `GET https://api.readme.com/v2/branches/{branch}/guides/{slug}` |
| List what is in a category | `GET https://api.readme.com/v2/branches/{branch}/categories/{section}/{title}/pages` |

`{branch}` is a version number, `stable`, or a branch name. Everything is branch-scoped except
changelogs, images, fonts, API keys, search and the project itself.

## Metrics

Page views, search terms and page quality live in the `Developer Metrics API` spec, and reading them
needs the Enterprise plan — without it the API answers with an auth or plan error rather than saying
so. The registration sends a bearer token; if a call returns `Unauthorized` with a key set, send
`Authorization: Basic <base64 of "<key>:">` on the HAR request instead.

Most of what the dashboard shows has no route at all, so check here before going looking:

| Metric | Readable via API |
| --- | --- |
| Page views, page quality, search terms | Yes |
| API calls | No — ingest only, `POST https://metrics.readme.io/request` |
| MCP tool calls, API errors, top endpoints, new users | No, dashboard only |

For anything in the No rows, send the user to
`https://dash.readme.com/project/{subdomain}/v{version}/metrics`.

Ingesting the user's own API logs is a server-side integration, not something to hand-build here.
Point them at the SDK for their stack — `readmeio` (Node), `readme-metrics` (Python, Ruby),
`readme/metrics` (PHP), `ReadMe.Metrics` (.NET) — and at `fetch` with id `main/sdks`.

## A different server, when they actually want one

Every ReadMe project publishes its own MCP server at `https://{subdomain}.readme.io/mcp`, or its
custom domain. That is for *their* end users to ask questions of *their* published hub. It is a
product feature they set up deliberately, not a workaround for this conversation, and it is not
needed to work on their own docs from here.

A server's hostname decides which project it serves. Enterprise hostnames serve a whole group, so
`search` and `fetch` there can span several child projects.

View saved version →

---
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.

## Tools

- `search`
- `fetch`
- `execute-request`

## 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 <file>` 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 under the same name, which replaces the plugin's one. The command differs per client: use the registration table in the `mcp-auth` skill, which also covers repairing a key that is already set.
7. Verify: `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. `Missing Security Schemes` means the registration is sending no key; a 401 titled `The API key couldn't be located.` means the key is wrong; a 500 titled `An unknown error has occurred.` means it resolved to an empty string. In every case, go back to step 5.

After step 7, the `mcp-server` skill covers which spec and which project everything else lands in.

## Driving the browser yourself

Steps 1 to 5 are all browser work. If you can drive a browser, offer to do them in the user's own browser instead of only listing the steps: open the signup page, create the project, upload the API definition, and open the API Keys page. Let the user type credentials and payment details themselves. Steps 6 and 7 stay in the terminal.

Find the row for the client you are running in. If you cannot tell which one that is, ask rather than guess.

| Client | Drive the browser with |
| --- | --- |
| Claude Code | `mcp__claude-in-chrome__*`, when the Claude in Chrome extension is connected |
| ChatGPT desktop app or ChatGPT web | `@Browser`. It has its own profile, so the user signs in to ReadMe there, and it asks before submitting forms. It cannot upload files, so for step 3 import the API definition by URL or run `npx rdme openapi upload <file>` from a terminal |
| Codex CLI, Codex IDE extension, Cursor | No browser of their own. List the steps for the user |

## When you cannot install anything yourself

On a chat surface 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 there. If the ReadMe tools are missing, the user has to install the plugin by hand. Find their client below and give them those steps exactly.

| Client | Steps |
| --- | --- |
| Claude Desktop, Cowork, claude.ai | Click **Customize** in the left sidebar, then **Plugins** — in Cowork, open the **Cowork** tab first. Under **Personal plugins**, click **+** → **Add marketplace** and enter `readmeio/agent-plugins`. Find **readme** in the list, click **Install**, then start a new chat so the tools load. Plugins need a paid Claude plan; on Team and Enterprise an owner may have disabled personal marketplaces, in which case they add it under **Organization settings → Plugins** |
| 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 tools but not the skills, so keep this skill's content in the conversation yourself |
| Cursor | Open **Cursor Settings → Plugins**, search for **ReadMe**, click **Install** and choose project or user scope. Or run `/add-plugin readme` in chat |

On the chat surfaces above the ReadMe connector stays read-only once installed: `search`, `fetch` and the endpoint tools work on public projects, but there is no way to supply an API key, so steps 6 and 7 of the Quick Start do not apply and write tools such as `update-docs` fail. Say so before the user tries. For creating or updating pages, offer to continue in a CLI or editor with the server registered as in step 6.

## Reading the docs meanwhile

Use `search` for a question, then `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 |

View saved version →

---
name: setup-project
description: Create a new ReadMe Docs project, including new account creation for those without an existing account.
---

# Set up a ReadMe project

This skill walks through the steps to setup a new ReadMe project, including the available options and required MCP configuration.

## Requirements

- This skill assumes that the ReadMe MCP server has been configured. If you do not have the ReadMe MCP available, you must first follow the steps in the `mcp-auth` skill for the specific client and setup the ReadMe MCP server before you can setup a new ReadMe project. Note that you don't need to connect up to an actual project if the user is creating a new account.
- Currently new project setup is only allowed if the user does not have an existing ReadMe account. If the user has an existing account, they must create their new project in the ReadMe UI, and follow the instructions in `mcp-auth` to get their project API key loaded into configuration.

**Done**
- You are connected to the ReadMe MCP server
- You have confirmed that the user is creating this project with a new account, OR if they have an existing account they've manually created it in the UI and have set you up with the API Key:
  - You should have used `execute-request` on the `/v2/projects/me` endpoint and have confirmed that the configuration is correct

## Workflow

### 1. Gather Required Information

Before creating the account and project for the user, you should verify that you have all of the required information to seed their project with some initial content for them to view. Having a project with some details already configured is a much better experience than putting them into an empty, generic project setup.

You should clarify the following with the user:

#### Information Source

What information will you be provided to create the docs for this user? Options include but are not limited to:

- An existing documentation repository that they want to connect via BiDi Sync (see #bidi-sync)
- An existing documentation site that they want to copy verbatim (see #docs-site-import)
- A non docs-website that has relevant information (ie their marketing site)
- Local files that they want to use as information to create a new docs site
- A summary that they will type out for what they want to configure
- An existing code repository that you will read to create docs from
- An existing OAS spec (see #oas-upload)

Note that the user may have one or more of these, and it is not an exhaustive list.

**Done**
You have the information that will be used to create at least the first few pages in the project, and you have verified that you can read these. If you cannot access, tell the user that you cannot and ask if they can provide or whether they would prefer to continue without this information.

#### Branding/Styling

Does the user have an existing color system/style guide? May include but not be limited to:

- Logo(s) and favicon
- Color systems - there are colors available for:
  - Brand (primary) color
  - Links color (if not given use the brand color they give)
  - Backgrount (if not given don't specify)
  - Sidebar Border (if not given don't specify)
  - Borders color (if not given don't specify)
  - BreadCrumts (use brand color if not specified)
  - Tint (accent color)
  - Ask AI (if not given don't specify)
  However, to keep it simple it is usually good to just get the primary/accent colors.

Note that its fine if the user doesn't have anything for this, since its styling that they can configure later via UI.

**Done**
When the user has either:

- Provided styling content; or
- Has said that they don't have any content to give you

#### Gather Account + Project Information (Optional)

IF the user is creating a new account + project, then you also need:

- The user's name
- The user's email
- The project's name

Instruct the user its VERY important that they have access to this email:

- This email owns the project and is the one used for account recovery. If they lose access to it, they may lose access to the project and all progress on it.
- They will need to verify this email before they can publish the project. This does not block setup, so they can do it later.

Use the email exactly as the user gives it. Never change, correct, or invent an email on their behalf - for example adding a `+` alias or fixing what looks like a typo. If you think there is a typo, ask the user to confirm the email instead.

**Done**
You have gathered all required information

### 2. Create initial content plan

Create a plan for the first bits of work you will do with the user - these should focus on the first few actions that you will perform so that the user can inspect their content in the UI as soon as possible.

This may include but not be limited to:

- Starting a docs site import (#docs-site-import)
- Configuring styling
- Creating the first few guide pages/all guide pages in a category for them
- Uploading an OAS spec/manually creating some API reference docs for them.

Unless the user pushes back, you should just focus on a smaller, horizontal across content piece of work (ie not just 5 guides, 3 guides and 2 api references are better) is better.

If the user is not importing from an existing docs site, and isn't uploading OAS specs, recommend to start with 5 pages to the user to get started so they can familiarize themselves with ReadMe, and that you can come back to this afterwards.

It is recommended to read the `manage-navigation` skill to understand how ReadMe does categorization for this, and the `edit-page-content` skill to understand how pages themselves can be formatted.

**Done**
The user has agreed to the initial content plan.

### 3. Execute on the plan

Execute on the content plan that you have agreed on with the user. Ensure that you understand whether the user needs a new account created, or if they have provided you with a project access key.

#### If Creating a new Project + Account

Only create an account if the user has confirmed they want to create a new account/they don't have a ReadMe account. If they have an existing account they must create their project via the UI and provide the API Key.

Follow these steps in order, before doing any of the content plan:

1. **Create the account.** Execute a POST `/v2/projects/ai_onboarding` via the `execute-request` tool from the ReadMe MCP.
   - If the request rejects the email, do NOT retry with an email you have changed or made up. Stop and ask the user, and only retry with the exact email they give you. ReadMe returns the same error for both causes, so tell the user both possibilities:
     - An account already exists for this email. They must sign in via the ReadMe UI to create their new project, then follow the `mcp-auth` skill to give you its API key.
     - The email is invalid. They must give you a different email that they have access to.
2. **Give the user their sign-in URL straight away.** Ask them to sign in with it and tell you once they have. Tell them:
   - The URL can only be used once, and expires after 1 week.
   - The project is empty for now, and they will see content appear as you work on it.
   - They will eventually need to verify their email before publishing the project, but this does not block anything now.
3. **Wait** until the user confirms they have signed in successfully.
4. **Connect the MCP to the new project.** Follow the steps in the `mcp-auth` skill using the API key returned when the account was created.
5. **Execute the content plan.**

## Intake branches

### BiDi Sync

A user can setup bi-directional sync with a local docs repository if that is their prefered method of setup. They cannot configure the git project connection via the server, however you should assist them with the correct formatting of content, folder structure, and more.

If they are creating a project, create their project, setup their styling (if provided) and then ask them to navigate to the `#/settings/git-connection` from any page on their docs domain to setup their BiDi sync.

Refer to the `manage-navigation` skill for how to handle BiDi sync navigation and folder structure.

### Docs Site Import

When importing from an existing documentation site - you may actually import from up to 2x individual projects in parallel. You MUST verify that these are indeed documentation site URLs - marketing site URLs and more will be rejected outright.

For those urls, you should import by doing a POST against the `v2/import` endpoint - find this via MCP and make a request against it.

To find information on all imports for a project you must use the GET `v2/import` as that will give you the list of all imports. For more information on individual imports, use the GET `v2/import/{runId}` endpoint with the runId from the list call.

### OAS Upload

If the user has an existing OAS spec - it can be uploaded to the POST `v2/branches/{branch}/apis` endpoint.

View saved version →

---
name: update-project-settings
description: View and update ReadMe project settings, including appearance, branding, AI features, MCP server settings, agent discovery, llms.txt, SEO, access and domains, API reference, localization, and integrations. Use when a user wants to configure any settings on their ReadMe docs site.
---

# Update ReadMe project settings

Note - these settings are only configurable via the ReadMe MCP Server - BiDi sync users must use the server or configure on their ReadMe site.

## Workflow

1. **Target.** Retrieve the current project via `execute-request` with `GET https://api.readme.com/v2/projects/me` and confirm it is the project the user means. Note `parent` (enterprise) and `plan.type`.
   **Done:** The intended project is confirmed and its current settings are in hand.
2. **Locate.** Match the request to a category and read its corresponding category file. When the user asks broadly (e.g. "what can I change about my styling?"), offer that category's common operations. Inspect the `updateProject` schema with `get-endpoint` for the exact fields.
   **Done:** Every requested change maps to a schema field or to a named dashboard-only action.
3. **Plan.** Show the current and proposed value for every field. Flag each change that is noted as being plan-gated, needs an extra purchase, may be overridden by an enterprise parent, or is write-only (see [How project settings behave](#how-project-settings-behave)). Get explicit approval: changes go live as soon as they are saved and make sure the user is aware of this.
   **Done:** The user has approved every field change, with the before values recorded for rollback.
4. **Apply.** Complete any upload step the category file names first. Send `PATCH https://api.readme.com/v2/projects/me` containing only the approved fields.
   **Done:** The request returned 200, or the error is reported with the field it names.
5. **Verify.** Retrieve the project again and compare every changed field with the plan. A field that kept its old value usually means a plan gate. Confirm write-only fields in the dashboard unless the category file says otherwise, and hand visual checks to the user.
   **Done:** Every approved field matches the plan, or each mismatch is reported with its likely cause.

## How project settings behave

- **Live immediately.** Settings are project-wide, apply to every branch and version, and are visible to readers as soon as they are saved. There is no draft or preview, so the recorded before values are the rollback.
- **Partial updates.** Send only the fields being changed; nested objects merge with the stored values.
- **Arrays are replaced in full.** Any array you send becomes the complete new value. Read the current array, edit it, and send the whole array back; sending one item deletes the rest. Category files name the exceptions. Keyed maps vary, so read the field's schema description before writing one.
- **Read-only fields.** Fields whose schema description says "Read-only" are ignored on write.
- **Write-only fields.** Fields marked write-only, such as site and MCP passwords and OAuth client secrets, can be set but are never returned. Other secrets, such as the JWT secret and integration keys, are returned to admins.
- **Plan-gated settings.** Some settings need a higher plan, such as Pro or Enterprise. Writes to a gated setting are silently ignored: the request still returns 200 and the old value stays. Category files mark each operation's tier. Check `plan.type` before writing, and don't write a setting below its tier. If the user wants to upgrade their plan, send the user to their plan page, reached by adding `#/settings/manage-plans` to any URL on their documentation domain.
- **Extra purchases.** Some features need an add-on beyond any plan, such as AI-enabled translations. Direct the user to sales@readme.io.
- **Enterprise parent projects.** A non-null `parent` means the project is a child in an enterprise group. Depending on the setting, the parent's value can override the child's, act as a default until the child sets its own, or be the only place the setting can be changed. Read the field's schema description for its inheritance rule before writing it on a child. Writing a value on a child, including a rollback to its before value, can stop that field inheriting from the parent.

## Categories

### General settings

Project name, meta description, company link, default version, suggested edits, new-page visibility, glossary, variable defaults, and Metrics feedback. Read [General settings](categories/general.md).

- Rename the project
- Update the meta description
- Set the "Go Home" company link
- Change the default version
- Turn suggested edits on or off
- Set default visibility for new pages
- Manage glossary terms
- Set variable defaults
- Turn page-quality voting on or off
- Turn email and company collection in metrics on or off

### Appearance

Brand, theme, fonts, layout, header navigation, page display, landing page, and custom code. Read [Appearance](categories/appearance.md).

- Upload or change the logo, favicon, and logo size
- Apply a theme preset and set the default color mode
- Set the primary, link, and fine-tuned colors (background, border, header, sidebar, breadcrumbs, Ask AI)
- Set the corner radius
- Choose heading, body, and code fonts, or upload and remove custom fonts
- Set text spacing
- Choose the layout style, full width, sticky header, and header style
- Choose the header link style and subnav alignment
- Show, hide, or rename built-in sections, and edit header links
- Choose the first page and where the logo links
- Turn collapsible categories, breadcrumbs, page icons, and the version picker on or off
- Choose the subheader layout and the classic or unified search modal
- Set the table of contents, changelog display, callout icons, and "What's Next" label
- Hide the ReadMe footer logo
- Edit the landing page hero and sections
- Add custom CSS, JavaScript, and HTML

### AI settings

Reader-facing Ask AI, the in-product AI agent, and the Slack AI Writer. Read [AI settings](categories/ai.md).

- Turn Ask AI on or off, and choose where readers can open it
- Give the in-product AI agent custom knowledge, and let it search project content
- Choose which built-in models the in-product AI agent can use
- Let the Slack AI Writer merge or delete the branches it opens
- Check whether AI Writer, Inline Editor, Linter, Docs Audit, or all AI features are available (read-only)

### MCP server

The MCP server readers connect AI tools to, with its endpoints, tools, OAuth sign-in, and OpenAI app verification. Read [MCP server](categories/mcp.md).

- Turn the MCP server on or off
- Password-protect the MCP server (write-only)
- Disable endpoints, or expose hidden and deprecated ones
- Disable built-in tools
- Add custom tools
- Set OAuth credentials per security scheme
- Customize the OAuth sign-in, success, and error pages
- Set the OpenAI app challenge token

### Agent discovery

How AI agents and crawlers find and read the docs: llms.txt, content signals, markdown responses, well-known endpoints, the "Open with…" menu, and the readiness score. Read [Agent discovery](categories/agent-discovery.md).

- Turn llms.txt on or off
- Split llms.txt per section (large projects only)
- Serve a custom llms.txt from the git repo
- Set Content-Signal preferences
- Serve markdown to agents and advertise discovery links
- Add sub-page, sibling, and "What's next" links to markdown pages
- Turn the hidden agent hint on or off
- Turn the API catalog, agent skills index, and MCP server card on or off
- Turn WebMCP on or off
- Advertise OAuth/OIDC discovery metadata
- Turn the "Open with…" menu on or off, and choose its entries
- Check the agent-readiness score (read-only)

### SEO settings

robots.txt crawling, sitemap, title tags, canonical URL, redirects, the custom 404 page, and search console verification. Read [SEO settings](categories/seo.md).

- Allow or block search engine crawlers
- Publish a sitemap.xml
- Use custom metadata titles as the page `<title>`
- Set the canonical URL
- Manage redirects
- Set a custom 404 page
- Set the Google or Bing verification code

### Access and domain settings

Who can view the site, site password, custom login, the login webhook, branch and OpenAPI sharing, custom domain, subdomain, and TLS/HSTS. Read [Access and domain settings](categories/access-and-domain.md).

- Choose who can view the site
- Set the site password (write-only)
- Set up custom login
- Rotate the JWT secret
- Set the login webhook
- Turn private branch share links on or off
- Choose who can view the /openapi page
- Set the custom domain
- Change the subdomain
- Set the minimum TLS version and HSTS

### API reference

The interactive API explorer, examples and code snippets, reference display options, API Designer editing, and API status. Read [API reference](categories/api-reference.md).

- Choose which parts of the API explorer are interactive (parameter inputs, authentication, Try It)
- Prefill parameters with default values
- Tune the request form: required-field validation, JSON body editing, filling optional objects
- Turn the OAuth flows experience on or off
- Show or hide request history
- Expand request examples, response examples, and response schemas by default
- Offer SDK-generated snippets
- Show or hide the OpenAPI download button
- Adjust how reference pages look (method badges, webhook badges, flat sections, parameter font, oneOf layout)
- Allow or block editing in the API Designer
- Show the API status to readers
- Check whether external SDK snippets are active (read-only)

### Localization

Site languages and guidance for ReadMe's AI translator, set on the enterprise group parent. Read [Localization](categories/localization.md).

- Turn translation on or off
- Add or remove languages
- Change the default language
- Keep words untranslated by the AI translator
- Give the AI translator guidance per language
- Check which languages ReadMe has unlocked for AI translation (read-only)

### Integrations

Third-party analytics, support widgets, fonts, translation widget, spam protection, and Postman. Read [Integrations](categories/integrations.md).

- Connect an analytics tool: Google Analytics, Heap, Segment, Koala
- Add the Intercom messenger, with optional identity verification
- Add the Zendesk widget
- Load an Adobe Fonts kit
- Add the Localize.js widget
- Protect forms with reCAPTCHA
- Store Postman credentials
- Connect Speakeasy

Referenced files: 10 — file references are metadata, not package contents.