diff --git a/skills/PROJECT-WORKFLOW.md b/skills/PROJECT-WORKFLOW.md new file mode 100644 index 0000000..83a78f6 --- /dev/null +++ b/skills/PROJECT-WORKFLOW.md @@ -0,0 +1,51 @@ +# Working on a ReadMe project + +Shared reference for project operations. Read the sections needed by the current workflow. + +## Draft boundaries + +`NEEDS_INPUT` marks maintainer work required before merge, not information the customer must supply. Use documented, available capabilities; when an unresolved detail is required for an action, pause that action and explain the manual continuation. Report partial work as partial. + +## MCP routing + +The plugin connects to [ReadMe's MCP server](https://docs.readme.com/main/docs/readmes-mcp-server). Its documentation search and fetch tools read **ReadMe's own docs**, not the customer's project. + +For customer content, discover the available ReadMe API operations and inspect their current schemas before executing them against the authenticated project. Use the current ReadMe API rather than treating legacy routes as a fallback. Tool schemas are the authority for names, arguments, supported fields, and pagination. + +The existing server uses `execute-request` with the `ReadMe API` spec for project operations; endpoint discovery tools describe those operations. Those discovery tools describe ReadMe's APIs, not the endpoints in a customer's API reference. For customer endpoint questions, use an available project API-reference operation and inspect its current schema. If none is available, state that limitation instead of substituting ReadMe's own endpoint definitions. An instructional tool response is a procedure to follow, not evidence that a mutation happened. + +Route project analytics separately: page views, search terms, and page quality belong to the `Developer Metrics API`, not the `ReadMe API` content routes. Discover the available operation and inspect its current schema before calling it. Treat authorization or plan errors as errors, not as empty results. + +**NEEDS_INPUT — MCP contract:** Confirm the current project-identity operation, search scoping, and execution contract against the monorepo. Add an agent-facing API documentation pointer for operations not covered by the product docs. + +## Target and branch + +For hosted writes, confirm the intended project's name and subdomain with a successful non-mutating project read; the credential determines the project. Resolve a mismatch through the connection configuration, not a per-request project guess. For local work, confirm the project context through the sync mapping below instead. + +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. + +## Source of truth + +Select the write surface for each item before checking hosted access. Use MCP for hosted changes by default. Switch to local files only when the user explicitly confirms bidirectional Git sync and the repository, intended ReadMe project, mapped ReadMe branch, and synced files are established. Missing MCP or failed authentication is not evidence of sync or a file mapping; ask for missing confirmation before local writes. + +Confirmed mapped local edits do not require a working MCP connection or authenticated project read. Read, edit, and validate those files locally, using the same ReadMe MDX rules. Keep each change on one write surface. In mixed work, handle confirmed local items separately from hosted-only items; unavailable hosted access blocks only the latter, which remain pending with their next actions. + +For sync work, consult the current ReadMe Git-sync documentation. + +**NEEDS_INPUT — Git sync:** Add the canonical bidirectional-sync URL, branch mapping, file layout, supported sections/settings, and conflict/verification workflow. Until those are established, limit local edits to confirmed synced files. + +## Authentication failure + +Attempt the needed project operation with the existing connection. On an authentication rejection, use [mcp-auth](mcp-auth/SKILL.md), then resume the interrupted operation after verification. Handle validation, plan, permission, and network errors according to their actual response rather than assuming each needs a new key. + +## Verification + +After a hosted write, re-read the changed resource and compare the requested content/settings and preserved fields. Report the project, branch or project-wide scope, changed resources, review links, and remaining manual work. A saved draft is not necessarily published. + +For confirmed Git-sync work, report local validation and diff separately from remote synchronization/publication. + +**NEEDS_INPUT — Review:** Add supported preview, publishing, and sync-status checks for each operation. Provide a manual review link when automated checks are unavailable. diff --git a/skills/edit-page-content/MDX.md b/skills/edit-page-content/MDX.md new file mode 100644 index 0000000..2cd3dde --- /dev/null +++ b/skills/edit-page-content/MDX.md @@ -0,0 +1,16 @@ +# ReadMe MDX + +Load when authoring a ReadMe page body, including in a confirmed Git-synced repository. + +## Authoring contract + +Use ReadMe's supported MDX and built-in components. Preserve existing valid components when changing surrounding prose; check supported syntax and props before introducing one. Local files and hosted bodies follow the same rendering rules. + +**NEEDS_INPUT — Canonical docs:** Add the maintained ReadMe MDX authoring URL and focused component reference pointers. Confirm any differences between page types/editor generations. + +## Reference to fill + +- **NEEDS_INPUT — Built-ins:** Add pointers and minimal valid examples for supported callouts, tabs, code blocks/groups, cards, tables, images, and embeds; distinguish built-ins from project-defined components. +- **NEEDS_INPUT — Syntax:** Specify ReadMe's JSX/MDX constraints, escaping, supported HTML, and import/custom-component behavior. Avoid assuming general React or another docs platform's MDX works here. +- **NEEDS_INPUT — Metadata:** Specify which hosted metadata is outside the body and when synced files require frontmatter. +- **NEEDS_INPUT — Validation:** Add supported rendering/preview checks and a manual fallback. Saving the body alone establishes persistence, not valid rendering. diff --git a/skills/edit-page-content/PAGE-TYPES.md b/skills/edit-page-content/PAGE-TYPES.md new file mode 100644 index 0000000..91df7f0 --- /dev/null +++ b/skills/edit-page-content/PAGE-TYPES.md @@ -0,0 +1,28 @@ +# ReadMe page types + +Load when selecting a page type, resolving its URL, or applying type-specific authoring rules. + +| Type | Authoring concern | Public path | +| --- | --- | --- | +| Guides | Narrative docs organized into categories | `/docs/{slug}` | +| API Reference | Distinguish descriptive prose from an OpenAPI operation/definition change | `/reference/{slug}` | +| Changelogs | Release-note content and publication state | NEEDS_INPUT — confirm route and scope | +| Discussions | Distinguish a topic from a reply and confirm available write operations | NEEDS_INPUT — confirm route and MCP/API support | +| Recipes | Step-by-step code walkthroughs | NEEDS_INPUT — confirm current availability, route, and format | +| Custom pages | Standalone content outside the standard guide/reference organization | NEEDS_INPUT — confirm route and supported body formats | + +Sidebar nesting does not add path segments to a page slug. Use the actual page URL returned by ReadMe when available. + +## API Reference + +For an imported API, identify the authoritative OpenAPI source before changing endpoint definitions; keep prose edits distinct from spec updates. Read [OpenAPI upload and management](https://docs.readme.com/main/docs/openapi-upload-and-management) for that branch. + +**NEEDS_INPUT — API authoring:** Add canonical reference-page documentation, manual versus imported endpoint behavior, editable prose fields, and preservation/re-import rules. Decide whether observed endpoint-creation failures justify a separate `creating-endpoints` skill; keep it deferred until then. + +## Other page types + +**NEEDS_INPUT — Type pointers:** Add maintained ReadMe documentation URLs and creation/edit/publication constraints for each type above. Verify existing guide/reference path conventions across supported project generations. + +**NEEDS_INPUT — Discussion and recipe scope:** Confirm whether these belong in current supported workflows; narrow the skill description if they are unavailable. + +Scope and Git-backed behavior belong in [project workflow](../PROJECT-WORKFLOW.md), rather than a second scope map here. diff --git a/skills/edit-page-content/SKILL.md b/skills/edit-page-content/SKILL.md new file mode 100644 index 0000000..e24848d --- /dev/null +++ b/skills/edit-page-content/SKILL.md @@ -0,0 +1,31 @@ +--- +name: edit-page-content +description: Create or edit ReadMe page content, including guides, API reference prose, changelogs, discussions, recipes, and custom pages. +--- + +# Edit ReadMe page content + +## Workflow + +1. **Target.** Read [project targeting and source of truth](../PROJECT-WORKFLOW.md). Identify the page type and whether this is a new page or an edit; use [page types](PAGE-TYPES.md) for section paths and scope. + **Done:** The project, write surface, section, page identity, and applicable branch are explicit. +2. **Locate and read.** For confirmed local work, read the mapped file's complete body/metadata, or confirm its mapped destination for a new page. For hosted work, search the customer's content through the project API, scoped to the target where supported. If search is insufficient, retrieve categories for the section, then pages within each relevant category, following pagination. Fetch the complete target page before editing. + **Done:** The exact page and full current body/metadata are available, or the new page's category and slug are agreed. +3. **Draft.** Read [Creating and managing guides](https://docs.readme.com/main/docs/creating-and-managing-guides) for guide operations, [Structuring your docs](https://docs.readme.com/main/docs/structuring-your-docs.md) for organization, and [ReadMe MDX](MDX.md) when writing page bodies. Preserve unrelated content and metadata; use the page-type reference for type-specific requirements. + **Done:** A complete replacement body or new-page draft satisfies the requested change and applicable ReadMe rules. +4. **Write.** For confirmed local work, edit the mapped file. For hosted work, inspect the available operation's schema. Submit the **full updated body** for body edits, not a patch/diff; send unrelated metadata only if required, retaining its current values. + **Done:** The intended write surface contains the requested content; failures and partial changes are explicit. +5. **Verify.** Follow [verification](../PROJECT-WORKFLOW.md). Check every changed link, anchor, component, and requested content change, plus preservation of unrelated fields. Provide the page/review link and publication state. + **Done:** The saved result matches the draft, or remaining rendering/review checks are named. + +## Links and identity + +Prefer root-relative internal links such as `/docs/getting-started`, with descriptive anchor text. Use a section's correct path and append `#heading-anchor` only after checking the destination heading/anchor. + +ReadMe page slugs stay one layer deep regardless of sidebar nesting: a nested guide can still be `/docs/getting-started`, not `/docs/category/getting-started`. + +**NEEDS_INPUT — Link forms:** Document the alternative ReadMe internal-reference syntax, cross-branch/custom-domain behavior, slug collisions, and generated heading-anchor rules. + +## Operation gaps + +**NEEDS_INPUT — Page API:** Confirm search filters, category/page enumeration, complete-body fields, create/update operations, concurrency protection, and writable metadata by page type. Add canonical operation pointers rather than a copied endpoint catalog. diff --git a/skills/manage-navigation/SKILL.md b/skills/manage-navigation/SKILL.md new file mode 100644 index 0000000..986249c --- /dev/null +++ b/skills/manage-navigation/SKILL.md @@ -0,0 +1,28 @@ +--- +name: manage-navigation +description: Organize ReadMe navigation by creating or renaming categories, moving or reordering pages, changing page titles/slugs, or removing navigation content. +--- + +# Manage ReadMe navigation + +## Workflow + +1. **Inspect.** Read [project targeting and source of truth](../PROJECT-WORKFLOW.md), then [Structuring your docs](https://docs.readme.com/main/docs/structuring-your-docs.md). For confirmed local work, read the mapped navigation files and their documented representation; otherwise retrieve the target section's categories and their pages through the project API, including all pagination. Establish existing order/parent relationships on the selected surface. + **Done:** The affected navigation and its project/branch are known. +2. **Plan.** Show the proposed before/after structure, including page identities, destination categories, order, title versus slug changes, and removals. 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. +3. **Apply.** For confirmed local work, edit the mapped navigation files using their documented representation. For hosted work, discover supported category/page operations and inspect their schemas. Preserve page bodies while changing navigation metadata. Apply only supported ReadMe hierarchy changes. + **Done:** Every approved structural change has a result, with any partially completed sequence recorded. +4. **Verify.** Re-read the changed local files or hosted categories/pages and compare membership, order, titles, slugs, and hierarchy to the plan. Follow [verification](../PROJECT-WORKFLOW.md), check affected links, and report outstanding review, redirect, and sync/publishing work. + **Done:** The resulting structure matches the plan or every discrepancy is reported. + +## ReadMe hierarchy + +Categories organize pages; sidebar nesting does not create nested URL paths. Use [page types and paths](../edit-page-content/PAGE-TYPES.md) when a slug changes. Use [edit-page-content](../edit-page-content/SKILL.md) when the page body itself must change. + +## Reference to fill + +- **NEEDS_INPUT — Structure operations:** Add canonical docs/API pointers for category CRUD, page moves, ordering, supported nesting depth, and section restrictions. +- **NEEDS_INPUT — Identity:** Confirm rename versus slug-change behavior, inbound-link discovery, and redirects. +- **NEEDS_INPUT — Removal:** Confirm hide/archive/delete options, child-page handling, category-deletion effects, and recovery. +- **NEEDS_INPUT — Scope:** Confirm which navigation elements exist and are writable in ReadMe; distinguish categories/pages from site navigation links and branch/version selection. diff --git a/skills/mcp-auth/CLIENTS.md b/skills/mcp-auth/CLIENTS.md new file mode 100644 index 0000000..cd78c0a --- /dev/null +++ b/skills/mcp-auth/CLIENTS.md @@ -0,0 +1,15 @@ +# Client connection references + +Read exactly the reference for the current client **and surface**. These files also support the setup workflow's connection handoff without proactively invoking authentication recovery. + +| Environment | Reference | +| --- | --- | +| Cursor | [Cursor](clients/cursor.md) | +| Claude Code, including its desktop Code surface | [Claude Code](clients/claude-code.md) | +| Claude Desktop Chat, Cowork, or claude.ai | [Claude apps](clients/claude-apps.md) | +| Codex CLI or IDE extension | [Codex](clients/codex.md) | +| ChatGPT web or desktop | [ChatGPT](clients/chatgpt.md) | + +For an unlisted or ambiguous environment, establish the client and consult its maintained MCP setup documentation before offering configuration changes. + +**NEEDS_INPUT — Client verification:** Test each reference on supported client versions and add maintained client documentation URLs. Retain distinct instructions where secret storage, config scope, or reconnect behavior differs. diff --git a/skills/mcp-auth/SKILL.md b/skills/mcp-auth/SKILL.md index 0a3d9b7..1291b3e 100644 --- a/skills/mcp-auth/SKILL.md +++ b/skills/mcp-auth/SKILL.md @@ -1,115 +1,31 @@ --- name: mcp-auth -description: Establish or repair the ReadMe API key behind execute-request. Use when a ReadMe call fails with "Missing Security Schemes", "The API key couldn't be located", or "An unknown error has occurred", when the user asks which project their key reaches, when they say they set a key but it is not working, and before the first write to their project. +description: Recover a ReadMe MCP connection when a project operation is rejected for missing, invalid, expired, or unresolved authentication. --- -# The key behind execute-request +# Recover ReadMe MCP authentication -Public reads of ReadMe's documentation need no key; anything touching the user's own project does, -and it travels on the MCP server registration rather than in the tool call. See the `mcp-server` -skill for which calls land where. +Invoke on an authentication failure, not before routine project work. -Cursor prompts for `README_API_KEY` on install. Claude and Codex ship anonymous, so those users -still have to register the server themselves. +## Workflow -## Tools +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 both the client and surface (for example Claude Code versus Claude Desktop Chat); ask if unclear. Read only the matching [client connection reference](CLIENTS.md). + **Done:** The instructions apply to the user's actual environment. +3. **Repair.** Direct the user to the intended ReadMe project's **Configuration → API Keys** and their client's credential settings. Keep secrets out of chat, committed files, and tool arguments. The user enters or rotates the key; apply non-secret configuration only with permission. Follow the environment's reconnect instructions. + **Done:** The user confirms the credential is configured, or receives an explicit manual handoff. +4. **Verify and resume.** Use a documented, non-mutating project-identity operation through the MCP connection; confirm the project matches the intended target. Retry the interrupted operation only after successful verification, checking the existing state before retrying a write with an uncertain result. + **Done:** The intended project is reachable and the original workflow resumes, or the unresolved error is reported without repeated guesses. -- `execute-request` +## Authentication scope -## Assume the registration may be empty +Public reads of ReadMe's own product docs can use the plugin's anonymous connection. Operations on the customer's project use the authenticated connection; a successful public-doc search does not verify it. The credential selects the project. -Do not spend a call proving auth unless you need the user's project. Go straight to the work: +Use [MCP routing](../PROJECT-WORKFLOW.md) for the project-operation contract. -- ReadMe documentation questions — `search` and `fetch`, no key involved. -- The user's project, and they have not mentioned a key — go to **No key yet** below. -- The user says they set a key, or an `execute-request` call fails — verify with the probe. +## Reference to fill -## Verify - -`execute-request`, spec title `ReadMe API`, with no `Authorization` header of your own: - -```json -{ - "title": "ReadMe API", - "harRequest": { - "method": "get", - "url": "https://api.readme.com/v2/projects/me" - } -} -``` - -| Response | Means | Next | -| --- | --- | --- | -| A project object | The registration carries a working key | Name the project and subdomain, carry on. Ask for nothing | -| `Missing Security Schemes` | No `Authorization` header at all — the server is anonymous | **No key yet** | -| `"title": "The API key couldn't be located."`, status 401 | A key is being sent, but it is not a real key | **A key is set but wrong** | -| `"title": "An unknown error has occurred."`, status 500 | The bearer is empty — the variable resolved to nothing | **A key is set but wrong** | - -Resolve this once per session. Having seen a project object, send no `Authorization` header of your -own for the rest of the session. - -## No key yet - -If the user has not named a project, ask, and wait. Pick no project, infer none from open files or -earlier turns, and read no guides to narrow it down. Ask which project, and whether they would rather -register the key with the server or paste it in chat. - -Offer the better option first: - -- **Preferred:** they put the key on the server registration, so it stays out of the chat. They - create the key under **Configuration → API Keys** in ReadMe, then follow **Registering the key** - below. -- **Otherwise:** they paste it and you send it as a header on each call: - - ```json - { - "title": "ReadMe API", - "harRequest": { - "method": "get", - "url": "https://api.readme.com/v2/projects/me", - "headers": [{ "name": "Authorization", "value": "Bearer rdme_..." }] - } - } - ``` - - This works, and it also puts the key in the transcript. Say so, and tell them to rotate it. - -Send a header of your own **only** when the probe returned `Missing Security Schemes`. A header on the -server registration overrides anything you set in `harRequest`, so against a registered server a -pasted key is silently ignored and the call lands in whichever project the registration owns — no -error, just the wrong project. - -## A key is set but wrong - -Both failures mean an `Authorization` header is reaching the API and the API is rejecting it. The -usual cause is the registration referring to an environment variable the client resolved to nothing, -or passed through as literal text, because the variable is unset where the client launched from: - -- **Status 500, `An unknown error has occurred.`** — the header arrived empty. -- **Status 401, `The API key couldn't be located.`** — a value arrived, but no such key exists. - Also what a revoked or mistyped key returns. - -Say that plainly before asking them to paste anything. Ask them to confirm the variable is exported -in the environment the client launched from, then reconnect as the **Registering the key** row for -their client describes. If the key is genuinely gone, they create a new one under **Configuration → -API Keys**. - -Do not work around either failure by probing with `curl` or by retrying against the `Legacy API` -spec. One key maps to one project; if the call reaches the wrong project, the registration is the -thing to change. - -## Registering the key - -On Cursor, set the plugin variable. On Claude and Codex, registering a `readme` server of their own -replaces the plugin's anonymous one. The server name stays the same, so the skills and tools keep -working. - -Find the row for the client you are running in. If you cannot tell which one that is, ask the user — -the wrong row sends them to a config file their client never reads. - -| Client | How | -| --- | --- | -| Claude Code | `export README_API_KEY=rdme_…`, then `claude mcp add --scope user --transport http readme https://docs.readme.com/mcp --header 'Authorization: Bearer ${README_API_KEY}'`. Keep the single quotes: the variable is expanded when Claude Code starts, so the key never lands in a config file. Restart afterwards | -| Codex, and the ChatGPT desktop app that shares its config | `export README_API_KEY=rdme_…`, then `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. Start a new session afterwards | -| Cursor | Open **Customize**, find **ReadMe**, and set **ReadMe API key** under **Plugins → Configure** (also the install prompt). Create the key under **Configuration → API Keys**. Restart if the server was already connected. Do not also add a `readme` entry in `~/.cursor/mcp.json`: a user-level server with the same name overrides the plugin, including a blank or `${env:README_API_KEY}` header that never resolved | -| Claude Desktop, Cowork, claude.ai, ChatGPT web | Not possible. The connector is read-only on these surfaces and cannot take a key. Say so, and offer to carry on in a CLI or editor | +- **NEEDS_INPUT — Failure contract:** Confirm auth-required operations and reliable error/status mappings. The old drafts treated some generic 500 responses as empty-key failures; verify that behavior before using it diagnostically. +- **NEEDS_INPUT — Key UI:** Verify the current key-creation/rotation labels and link to maintained ReadMe instructions. +- **NEEDS_INPUT — Verification:** Confirm the current read-only identity operation, key/project permissions, and supported project-switching behavior. diff --git a/skills/mcp-auth/clients/chatgpt.md b/skills/mcp-auth/clients/chatgpt.md new file mode 100644 index 0000000..0f12797 --- /dev/null +++ b/skills/mcp-auth/clients/chatgpt.md @@ -0,0 +1,14 @@ +# ChatGPT connections + +Applies to ChatGPT web and desktop, not Codex CLI or its IDE extension. + +## Connection handoff + +Use the surface's supported connector settings and user-managed authentication. A Codex shell registration applies only if that specific surface documents shared configuration; establish that support before recommending it. + +If the surface cannot authenticate the ReadMe connection, give the user a supported CLI/editor continuation for project writes while retaining public ReadMe documentation access. + +## Before merge + +- **NEEDS_INPUT — Surface support:** Confirm plugin/connector availability, credential handling, and config sharing separately for web and desktop; the previous draft's assumptions differed between surfaces. +- **NEEDS_INPUT — UI:** Add exact installation, authentication, admin/plan restrictions, and reconnect steps for each supported surface, with canonical client documentation links. diff --git a/skills/mcp-auth/clients/claude-apps.md b/skills/mcp-auth/clients/claude-apps.md new file mode 100644 index 0000000..4fcb410 --- /dev/null +++ b/skills/mcp-auth/clients/claude-apps.md @@ -0,0 +1,14 @@ +# Claude app connections + +Applies to Claude Desktop **Chat**, Cowork, and claude.ai. The desktop **Code** surface uses the [Claude Code reference](claude-code.md). + +## Connection handoff + +These surfaces use app/cloud connector settings rather than a local Claude Code registration. Guide the user through the supported app settings; shell environment variables are not a substitute for connector credentials. + +If authenticated ReadMe connections are unavailable on their surface, explain that limitation and hand off project writes to a supported client. Public ReadMe product-documentation reads can continue. + +## Before merge + +- **NEEDS_INPUT — Surface support:** Verify authenticated connector support separately for Desktop Chat, Cowork, and claude.ai; the previous draft asserted all were read-only. +- **NEEDS_INPUT — UI:** Add each supported surface's key/auth flow, install/settings link, plan/admin restrictions, and reconnect steps. Provide a tested manual alternative where auth is unsupported. diff --git a/skills/mcp-auth/clients/claude-code.md b/skills/mcp-auth/clients/claude-code.md new file mode 100644 index 0000000..2f12b7a --- /dev/null +++ b/skills/mcp-auth/clients/claude-code.md @@ -0,0 +1,16 @@ +# Claude Code connection + +## Connection handoff + +The bundled MCP configuration is anonymous. The existing connection approach registers an authenticated HTTP server named `readme`, with the key referenced from the environment: + +```sh +claude mcp add --scope user --transport http readme https://docs.readme.com/mcp --header 'Authorization: Bearer ${README_API_KEY}' +``` + +Have the user set `README_API_KEY` privately in the environment that launches Claude Code and restart/reconnect afterwards. Keep the single quotes so the registration stores a variable reference rather than expanding the secret in the shell. + +## Before merge + +- **NEEDS_INPUT — Registration:** Verify this command, runtime variable expansion, plugin/server naming and precedence, and update-versus-add behavior against current Claude Code docs. +- **NEEDS_INPUT — Scope:** Confirm user versus project scope and desktop Code environment inheritance; add exact reconnect steps and documentation links. diff --git a/skills/mcp-auth/clients/codex.md b/skills/mcp-auth/clients/codex.md new file mode 100644 index 0000000..404cc1a --- /dev/null +++ b/skills/mcp-auth/clients/codex.md @@ -0,0 +1,16 @@ +# Codex connection + +## Connection handoff + +The bundled MCP configuration is anonymous. The existing connection approach reads the credential through an environment-variable reference: + +```sh +codex mcp add readme --url https://docs.readme.com/mcp --bearer-token-env-var README_API_KEY +``` + +Have the user set `README_API_KEY` privately in the environment that launches Codex and start a new session afterwards. Store a variable name, not the token, in configuration. + +## Before merge + +- **NEEDS_INPUT — Registration:** Verify current CLI syntax, plugin/server precedence, existing-registration updates, and config scope; add canonical Codex MCP documentation. +- **NEEDS_INPUT — IDE:** Confirm IDE-extension environment inheritance and reconnect instructions independently from the CLI. diff --git a/skills/mcp-auth/clients/cursor.md b/skills/mcp-auth/clients/cursor.md new file mode 100644 index 0000000..6e835c3 --- /dev/null +++ b/skills/mcp-auth/clients/cursor.md @@ -0,0 +1,12 @@ +# Cursor connection + +## Connection handoff + +The package declares a `README_API_KEY` **plugin variable**, not a shell environment variable. Have the user set **ReadMe API key** in the install prompt or **Plugins → Configure** for the installed ReadMe plugin, then reconnect the server. + +Prefer the plugin credential setting. An independently configured `readme` server can shadow the plugin connection; inspect non-secret registration details when the configured key appears unused. + +## Before merge + +- **NEEDS_INPUT — UI:** Verify current install/configure labels and reconnect steps; add Cursor's canonical plugin-variable documentation. +- **NEEDS_INPUT — Precedence:** Verify user/project MCP overrides and how to detect duplicate registrations without exposing headers. diff --git a/skills/mcp-server/SKILL.md b/skills/mcp-server/SKILL.md deleted file mode 100644 index fcbaf37..0000000 --- a/skills/mcp-server/SKILL.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -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 :">` 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. diff --git a/skills/onboarding/SKILL.md b/skills/onboarding/SKILL.md deleted file mode 100644 index 3b500eb..0000000 --- a/skills/onboarding/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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 ` 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 ` 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 | diff --git a/skills/project-workflow/SKILL.md b/skills/project-workflow/SKILL.md new file mode 100644 index 0000000..90f70d6 --- /dev/null +++ b/skills/project-workflow/SKILL.md @@ -0,0 +1,8 @@ +--- +name: project-workflow +description: Use when answering standalone questions about a ReadMe project's API endpoints, page views, page quality, or search terms—including what endpoints their project has, how many page views it gets, or its top search terms—even when the user is not asking to edit or set up content. +--- + +# Project questions + +Read [shared project and API guidance](../PROJECT-WORKFLOW.md) before answering. Use its routing guidance to distinguish ReadMe's own documentation, the customer's ReadMe API, and the Developer Metrics API. Follow current tool schemas rather than guessing operation contracts. diff --git a/skills/setup-project/SKILL.md b/skills/setup-project/SKILL.md new file mode 100644 index 0000000..f33bac1 --- /dev/null +++ b/skills/setup-project/SKILL.md @@ -0,0 +1,51 @@ +--- +name: setup-project +description: Set up a first ReadMe project from an OpenAPI definition, an existing documentation site, or source material for new docs. +--- + +# Set up a ReadMe project + +## Workflow + +1. **Intake.** Establish the intended audience, project name/subdomain, owner/account status, and starting point. Use the matching intake branch below and collect available branding. + **Done:** Every input needed for the initial plan is supplied or explicitly deferred. +2. **Plan.** Propose the initial sections, navigation, seed content, branding, and migration/import approach. Separate supported automation from user actions and deferred work. + **Done:** The user approves the setup scope and which account/project to create or reuse. +3. **Provision.** Read [Creating a project](https://docs.readme.com/main/docs/creating-a-project) and discover available onboarding operations. Create the approved account/project only through supported capabilities. If unavailable, hand the user the signup link (`https://dash.readme.com/signup`) and the documented project-creation steps; resume when they return the project link. Let the user enter credentials, consent, and billing details. + **Done:** A confirmed project link and owner exist, or a specific manual handoff is recorded. +4. **Target and route.** Read [project targeting and source of truth](../PROJECT-WORKFLOW.md). Assign each approved item to its write surface and scope using that guidance. Resolve missing project/branch or sync/file-mapping confirmation before that item's writes. + **Done:** Each item has a confirmed target and write surface, or is pending with the missing confirmation named. +5. **Connect and verify hosted access.** Skip this step for local-only work confirmed in step 4. For hosted items, use the existing connection first. Only when connection setup is needed, read the [client-specific connection reference](../mcp-auth/CLIENTS.md); apply non-secret configuration only with permission, and let the user supply credentials through their client's settings. Use a supported, non-mutating project read and inspect its current schema to confirm the connection reaches the intended project. Invoke [mcp-auth](../mcp-auth/SKILL.md) only when the read fails for authentication, then retry the read after recovery. If the read is unavailable or does not succeed, stop hosted seeding and give the user a client-specific manual next step; confirmed local items can still proceed. + **Done:** Hosted items have a successful intended-project read or are blocked with the reason and next action; confirmed local items remain independent of hosted access. +6. **Seed and configure.** Apply the approved initial structure and content only to confirmed mapped local files or the successfully verified hosted target. Use [edit-page-content](../edit-page-content/SKILL.md), [manage-navigation](../manage-navigation/SKILL.md), or [update-project-styling](../update-project-styling/SKILL.md) for the matching work on its selected surface. Keep blocked hosted-only configuration pending rather than substituting local files. Treat migration kickoff and completed migration as different states. + **Done:** Each approved item is verified on its write surface or listed as pending with its next action; local validation is distinguished from remote sync/publication. +7. **Hand off.** Give the project link, the setup summary, and any pending manual next steps. + **Done:** The user has the project link and a concise record of completed and deferred work. + +## Intake branches + +### Existing OpenAPI definition + +Collect its file or URL, source of truth, intended API version, and update workflow. Plan import and the first supporting guide. + +Consult [OpenAPI upload and management](https://docs.readme.com/main/docs/openapi-upload-and-management) before importing. + +**NEEDS_INPUT — Import:** Confirm supported onboarding/import operations, accepted definition formats, validation errors, and re-import behavior. + +### Migration from an existing site + +Collect the source URL/export, ownership, sections to migrate, and content/assets to preserve. Explain the ReadMe-assisted migration option once its current process is confirmed; plan the kickoff and review handoff rather than promising immediate completion. + +**NEEDS_INPUT — Migration:** Add the ReadMe migration-service URL, supported sources, required access, kickoff operation or contact path, timing guidance, and status/completion checks. + +### Starting from scratch + +Collect source files, notes, product/API context, and example or competitor sites. Identify which sources are authoritative and which are inspiration. Plan a small usable seed, such as a getting-started guide and initial API reference when applicable. + +**NEEDS_INPUT — Seed:** Add supported generation/seeding operations and the minimum content required for a usable first project. + +### Branding + +Ask for available logos/icons, primary/accent colors, typography, and light/dark preferences; distinguish requested assets from supported settings. Record missing assets as deferred, using [update-project-styling](../update-project-styling/SKILL.md) for the support matrix. + +**NEEDS_INPUT — Provisioning:** Add account/project creation and initial-configuration contracts, required fields, duplicate-project handling, and recovery from partial setup. diff --git a/skills/update-project-styling/SKILL.md b/skills/update-project-styling/SKILL.md new file mode 100644 index 0000000..6f7e232 --- /dev/null +++ b/skills/update-project-styling/SKILL.md @@ -0,0 +1,31 @@ +--- +name: update-project-styling +description: Configure ReadMe project branding and site appearance, including logos, colors, typography, and supported layout settings. +--- + +# Update ReadMe project styling + +## Workflow + +1. **Inspect.** Read [project targeting and source of truth](../PROJECT-WORKFLOW.md). For confirmed Git-backed configuration covered by the documented sync workflow, read the mapped configuration files and supported fields. For hosted configuration, retrieve current settings and inspect the available operation's schema and scope. + **Done:** The current configuration, supported fields, and affected project/branch scope are explicit. +2. **Specify.** Collect the desired branding assets and appearance changes using the support matrix below. Distinguish missing assets from unsupported options and show which current settings will remain. + **Done:** Every requested change is mapped to a supported field or a named manual/deferred action. +3. **Apply.** For confirmed Git-backed configuration covered by the documented sync workflow, edit only the agreed, supported fields in the mapped files. For hosted configuration, submit only the agreed, schema-supported changes or direct the user to the appropriate dashboard setting. Preserve unrelated settings. + **Done:** Each agreed setting is applied or reported as pending. +4. **Verify.** Re-read the changed local configuration or hosted settings and follow [verification](../PROJECT-WORKFLOW.md). Review the site's supported preview modes; check asset loading, legibility, and contrast, or hand off unavailable visual checks. Report local validation, remote sync, and publication state separately. + **Done:** Stored values match the request and visual review is complete or explicitly handed off. + +## Branding support matrix + +Record user preferences as desired inputs, not promises of supported API fields. + +| Area | Inputs to collect | Supported settings | +| --- | --- | --- | +| Logos and icons | Assets, variants, intended placement | NEEDS_INPUT — formats, size limits, upload/link mechanism, light/dark support | +| Colors | Primary/accent colors, existing brand palette | NEEDS_INPUT — writable color fields and accepted values | +| Typography | Font choice, font files or hosted sources | NEEDS_INPUT — font support, licensing/access constraints, API coverage | +| Appearance | Light/dark preferences, layout goals | NEEDS_INPUT — modes, layout options, plan restrictions | +| Advanced styling | Specific changes beyond built-in settings | NEEDS_INPUT — custom CSS/HTML support and safe preview/rollback | + +**NEEDS_INPUT — Canonical docs:** Add maintained ReadMe branding/appearance documentation and dashboard links. Confirm configuration read/update operations, asset handling, and visual preview capabilities.