refactor(skills): draft ReadMe workflow-focused skill skeletons

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.

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.

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.

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.

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.

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.