From ea79df46bc48931c0973ad9967230334283f18ad Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Mon, 14 Sep 2026 09:02:17 -0700 Subject: [PATCH] docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist (#50313) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs authoring guidance: keep `/edit-the-docs` out of the Write the docs checklist and document when to use what skill in `CONTRIBUTING.md`. ## What is the current behavior? The Write the docs checklist mentions `/edit-the-docs` mid-flow and lists it among checklist skills. That skill is a different workflow and audience, so it risks steering people off the six-stage process. ## What is the new behavior? - Checklist lists only Write the docs skills; no `/edit-the-docs` mid-stage note. - `CONTRIBUTING.md` splits **Write the docs skills** from **Edit existing pages**. - Write the docs applies when product intent and code drive the change, including revising or restructuring existing pages. `edit-the-docs` is for style, structure, or brevity when the product story is unchanged. ## Additional context Also drops a redundant `/test-the-docs` note from "What good looks like" (Self-review still covers it). --------- Co-authored-by: Nik Richers --- .../reference/write-the-docs-checklist.md | 6 ++---- apps/docs/CONTRIBUTING.md | 21 +++++++++++-------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md b/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md index afe39dc5a9d..27aef67c5aa 100644 --- a/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md +++ b/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md @@ -17,7 +17,7 @@ _Self-serve first ([agent skills](../../../../apps/docs/CONTRIBUTING.md#ai-agent - The **why** is explicit: a reader learns what problem this solves and when to reach for it, not only the steps. - The content **type is deliberate** and consistent within the page. - **Audience and prerequisites** are stated up front. -- **Examples are runnable and have been tested** (commands, code, expected result) — verify with `/test-the-docs` against a Docker-isolated local stack, not production. +- **Examples are runnable and have been tested** (commands, code, expected result) - **Correct stage** like GA is stated; limitations are named honestly. - The page **lives in the right place** in the IA and links to and from related pages. - Terminology and formatting match existing docs (and style guide once it lands). @@ -48,8 +48,6 @@ _Skill:_ `/write-the-docs` to draft net-new content grounded in Linear and the c - [ ] E: Contribute technical depth and verify accuracy (APIs, limits, edge cases) - [ ] P: Call out the current stage inline and any known limitations -When the work is improving an existing page (restructure, reorder, connective text, brevity) rather than authoring net-new content, use `/edit-the-docs` instead of `/write-the-docs`. - ### 4. Self-review against the bar _Skills:_ `/review-the-docs` for [local self-review](../../review-the-docs/SKILL.md#local-self-review-no-open-pr) before opening the PR; `/test-the-docs` to run snippets and produce a verification report. @@ -81,4 +79,4 @@ _Skill:_ `/review-the-docs` to triage, classify, verify the build, and report. ## Resources -Skills for this checklist: [AI agent skills for docs authoring](../../../../apps/docs/CONTRIBUTING.md#ai-agent-skills-for-docs-authoring) (`/pm-the-docs`, `/ask-the-docs`, `/write-the-docs`, `/edit-the-docs`, `/test-the-docs`, `/review-the-docs`). +Skills for this checklist: [AI agent skills for docs authoring](../../../../apps/docs/CONTRIBUTING.md#ai-agent-skills-for-docs-authoring) (`/pm-the-docs`, `/ask-the-docs`, `/write-the-docs`, `/test-the-docs`, `/review-the-docs`). diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md index 08317ea31b9..3da288f0a3c 100644 --- a/apps/docs/CONTRIBUTING.md +++ b/apps/docs/CONTRIBUTING.md @@ -21,20 +21,23 @@ To make docs as clear as possible: ## AI agent skills for docs authoring -If you're using an AI coding agent (Claude Code, Codex, or anything else that reads `.agents/skills/`), this repo ships skills that back the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) authoring checklist. +If you're using an AI coding agent that reads `.agents/skills/`, such as Claude Code, Cursor, or Codex, invoke skills with `/name`, for example `/write-the-docs`. The canonical files live in `.agents/skills/` (`.claude/skills` is a symlink). -Ask your agent for a skill by name (`pm-the-docs`, `ask-the-docs`, `write-the-docs`, `edit-the-docs`, `test-the-docs`, `review-the-docs`); in Claude Code these are also available as `/name` slash commands. +### Write the docs skills + +Use the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) checklist when product intent and code drive the change: net-new pages, or revising/restructuring existing ones. | Skill | Checklist stage | Use for | | --- | --- | --- | -| [`pm-the-docs`](../../.agents/skills/pm-the-docs/SKILL.md) | Frame / Shape | Audience, product-stage, and cross-cutting scope calls (universe when you have Supabase org access, else OSS path) | -| [`ask-the-docs`](../../.agents/skills/ask-the-docs/SKILL.md) | Frame / Shape | `apps/docs` architecture, IA placement, and where content lives | -| [`write-the-docs`](../../.agents/skills/write-the-docs/SKILL.md) | Draft | Drafting net-new content grounded in the code | -| [`edit-the-docs`](../../.agents/skills/edit-the-docs/SKILL.md) | Edit | Restructure and improve existing pages, split by change type | -| [`test-the-docs`](../../.agents/skills/test-the-docs/SKILL.md) | Draft / Self-review | Execute docs snippets in a Docker-isolated local stack; verification report | -| [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft and PR triage/verification | +| [`pm-the-docs`](../../.agents/skills/pm-the-docs/SKILL.md) | Frame / shape | Audience, stage, why, content type, cross-repo scope (universe when you have Supabase org access, else OSS path) | +| [`ask-the-docs`](../../.agents/skills/ask-the-docs/SKILL.md) | Frame / shape | Docs-app architecture, IA placement, where content lives | +| [`write-the-docs`](../../.agents/skills/write-the-docs/SKILL.md) | Draft | Draft or revise content grounded in intent and code | +| [`test-the-docs`](../../.agents/skills/test-the-docs/SKILL.md) | Draft / self-review | Run snippets in a Docker-isolated stack; verification report | +| [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft; verify a PR | -The canonical files live in `.agents/skills/`; `.claude/skills` is a Git symlink to that directory so Claude Code discovers them too. +### Edit existing pages + +Use [`edit-the-docs`](../../.agents/skills/edit-the-docs/SKILL.md) for style, structure, or brevity on an existing page when you are not changing the product story. ## Document types