docs: improve write-the-docs skill and retire docs-content (#49089)

## I have read the CONTRIBUTING.md file.

YES

## What kind of change does this PR introduce?

Improves the `write-the-docs` skill and retires the overlapping
`docs-content` skill (provided @czenko agrees to the latter).

## What is the current behavior?

- Docs drafts could leak future-tense / internal roadmap language, add
redundant verbiage, and add single-item lists.
- No explicit CONTRIBUTING.md / WORD_LIST.md compliance pass for docs
drafts.
- Product intent was assumed to come from Linear without a good path
path for open-source contributors.
- `docs-content` overlapped `write-the-docs` and the broader
`*-the-docs` skill set (e.g. I started
[#49432](https://github.com/supabase/supabase/pull/49432) before
realizing we should likely not have overlapping skills).

## What is the new behavior?

- Codifies draft pitfalls as principles in
`reference/common-pitfalls.md` (timelessness, strip internal business
context, redundancy, single-item lists), with style detail pointed from
`SKILL.md` rather than duplicated.
- Clarifies SoT: Linear + code inspection for content accuracy;
CONTRIBUTING.md / WORD_LIST.md (and future DOCS-1177 style guide) for
voice/terminology/formatting only. `common-pitfalls.md` is flagged to
fold into that guide later.
- Linear is internal and preferred when available, not required for
open-source. Missing product intent: stop Draft and hand off to
`pm-the-docs` (Frame) / `ask-the-docs` (Shape/IA); do not invent
positioning or run Frame/Shape inside this skill.
- Adds drafting mechanics notes, a compliance checklist before handoff,
and a local `/review-the-docs` self-review step.
- Removes `.claude/skills/docs-content/`; `.claude/CLAUDE.md` points at
the canonical docs skills. Supersedes #49432.

## Additional context

Based on @czenko review feedback on #49020 and feedback I received for
`docs-content` from @aantti while trialing the "Write the docs" process
with contributors, plus my own testing while drafting docs for product
managers.

### Test plan

- [ ] `SKILL.md` reads as Draft-only; Frame/Shape stay with
`pm-the-docs` / `ask-the-docs`
- [ ] No-Linear path: ask for Linear (internal) or hand off Frame/Shape;
no invented positioning
- [ ] `.claude/skills/docs-content/` gone; `.claude/CLAUDE.md` updated
- [ ] `.claude/skills/write-the-docs` symlink still resolves to
`.agents/skills/write-the-docs`
- [ ] Next `/write-the-docs` run: compliance re-read + pitfalls guidance
before handoff

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Added an `edit-the-docs` workflow for restructuring and improving
existing documentation pages.
- Expanded authoring guidance for concise, timeless, user-focused
content grounded in product intent.
- Added references covering common writing pitfalls, link and anchor
conventions, and validation workflows.
- Clarified that style guidance applies to voice, formatting, and
terminology—not product behavior.
- Updated documentation workflows to distinguish planning, writing,
editing, review, and assistance responsibilities.
- Replaced the previous standalone docs-content skill with the updated
authoring skill model.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>

.agents/skills/edit-the-docs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: edit-the-docs
+description: >-
+  Restructure, reorder, and improve existing Supabase docs pages under
+  apps/docs — clarity, connective text, section grouping, and brevity.
+  Use when asked to edit, reorganize, restructure, tighten prose, or add
+  glue between sections on a page that already exists. Not for net-new
+  feature drafts (use write-the-docs) or PR triage/verification (use
+  review-the-docs).
+---
+
+# Edit the docs
+
+Improves **existing** Supabase docs pages: structure, order, connective text,
+and clarity. Distinct from [`write-the-docs`](../write-the-docs/SKILL.md)
+(draft net-new or product-grounded rewrites from intent + code) and
+[`review-the-docs`](../review-the-docs/SKILL.md) (lint, build, PR triage).
+
+## Core rules
+
+1. **Read before you rewrite.** Open the target page and nearby pages of the same type. Name the reader's goal and the page type (explainer, guide, tutorial, troubleshooting) before moving sections.
+2. **Improve structure and clarity; don't invent product truth.** Preserve behavior claims, UI labels, and positioning unless you verify a change against code or product intent. Accuracy gaps or missing net-new content belong with [`write-the-docs`](../write-the-docs/SKILL.md) / [`pm-the-docs`](../pm-the-docs/SKILL.md), not silent invention here.
+3. **Follow CONTRIBUTING.md and WORD_LIST.md** for voice, terminology, and formatting. See [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md).
+4. **Prefer brevity.** Prefer broad strokes when mechanical detail doesn't help the reader's task. Cut redundancy; don't over-explain.
+5. **Reuse sibling skills.** IA/architecture via [`ask-the-docs`](../ask-the-docs/SKILL.md); validation and self-review via [`review-the-docs`](../review-the-docs/SKILL.md). Shared pitfalls live in [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md) — apply them, don't duplicate them.
+
+## Phase 1 — Diagnose
+
+1. Identify the document type per CONTRIBUTING.md (explainer, tutorial, guide, reference, or troubleshooting).
+2. State the reader's goal and prerequisites in one or two lines.
+3. Note structural problems: mixed information types interrupting a procedure, missing intro navigation on a long page, weak transitions, redundancy, or over-explained mechanics.
+4. Summarize the diagnosis to the requester before large moves when the restructure would change how the page is read.
+
+## Phase 2 — Restructure
+
+Apply [reference/structure-and-flow.md](reference/structure-and-flow.md):
+
+1. Classify substantial sections as contextual, procedural, or reference content. In a mixed page, group sections by information type so that context doesn't interrupt the procedural path.
+2. For a long or mixed page, add a short introduction that links to its major section groups and tells readers when to use each one. Skip this navigation when a short page is already easy to scan.
+3. Connect contextual sections to their corresponding procedures when useful. Add introductions to section groups, transitions between information types, and outcomes after procedures. Don't link every adjacent section.
+4. Move and regroup first; preserve meaning. Don't silently rewrite facts while restructuring.
+
+## Phase 3 — Edit for clarity
+
+- Use second person, present tense, short paragraphs, and ordered steps for sequential actions.
+- Cut restated points and mechanical over-explanation.
+- Apply [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md): timelessness, no internal planning context in shipped MDX, redundancy, single-item lists, admonition restatement.
+- Search [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) when introducing or revising technical terms and UI actions.
+- Keep code samples executable in their stated context; mark intentionally omitted code. Prefer partials under `apps/docs/content/_partials/` over copied blocks.
+
+## Phase 4 — Validate
+
+Before handoff:
+
+- [ ] Section groups follow information type; procedures aren't interrupted by long context
+- [ ] Intro navigation present only when the page needs it; links resolve
+- [ ] Connective text is selective, not link spam
+- [ ] Voice matches CONTRIBUTING.md / WORD_LIST.md
+- [ ] No invented behavior or positioning
+- [ ] Shared pitfalls checklist considered
+
+Mechanics (anchors, lint, format): follow [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md). Before renaming or rewording headings, grep for `#<old-anchor-slug>` under `apps/docs/content` and update matches.
+
+Then run [`review-the-docs`](../review-the-docs/SKILL.md) local self-review (`pnpm lint:mdx`, and `pnpm build:guides-markdown` when guides/explainers/tutorials changed).
+
+## Additional resources
+
+- Structure SoT: [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) (mixed types, navigation, glue)
+- Structure ops: [reference/structure-and-flow.md](reference/structure-and-flow.md)
+- Pitfalls: [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md)
+- Mechanics: [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md)
+- Architecture/IA: [`ask-the-docs`](../ask-the-docs/SKILL.md)
+- Net-new drafts: [`write-the-docs`](../write-the-docs/SKILL.md)
+- Review: [`review-the-docs`](../review-the-docs/SKILL.md)

.agents/skills/edit-the-docs/reference/structure-and-flow.md

@@ -0,0 +1,29 @@
+# Structure and flow
+
+Operational guidance for restructuring existing docs pages. The human-facing
+source of truth is [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md)
+under Guides: **Mixed information types**, **Navigation**, and
+**Cross-references and glue**. Keep this file aligned with that section.
+
+## Classify and group
+
+Classify substantial sections as contextual, procedural, or reference content.
+In a mixed page, group sections by information type so that context doesn't
+interrupt the procedural path.
+
+## Introduction navigation
+
+For a long or mixed page, add a short introduction that links to its major
+section groups and tells readers when to use each one. Skip this navigation
+when a short page is already easy to scan.
+
+## Connective text
+
+Connect contextual sections to their corresponding procedures when useful.
+Add introductions to section groups, transitions between information types,
+and outcomes after procedures. Don't link every adjacent section.
+
+## Voice and procedure shape
+
+Use second person, present tense, short paragraphs, and ordered steps for
+sequential actions.

.agents/skills/pm-the-docs/SKILL.md

@@ -19,7 +19,7 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in
 - Deciding content type, IA placement, or prerequisites for a page (Shape).
 - Unsure whether a docs question is self-serve or needs a docs PM's sign-off.
 
-**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)) or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)).
+**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)), restructuring existing pages (see [`edit-the-docs`](../edit-the-docs/SKILL.md)), or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)).
 
 ## Answering a scope/stage/audience question
 
@@ -27,7 +27,7 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in
 2. Read whatever context exists for the feature: the linked issue/project, the PRD, the shipped code or PR. When code and PRD disagree, the code wins for behavior claims.
 3. Answer the checklist's questions directly: product stage, audience and job-to-be-done, the one-line "why," content type, IA placement, prerequisites.
 4. Distinguish **confirmed fact** (stated in the ticket/PRD/code) from **inference** (your best read) — flag inference explicitly rather than presenting it as settled.
-5. If a decision is genuinely open at the org level (not a docs-content call), say so and name who should decide instead of inventing an answer to look complete.
+5. If a decision is genuinely open at the org level (not a docs authoring call), say so and name who should decide instead of inventing an answer to look complete.
 
 ## Self-serve vs. escalate
 
@@ -39,4 +39,5 @@ Escalate to your docs team's PM when scope or stage is unclear, you need a revie
 
 - [`ask-the-docs`](../ask-the-docs/SKILL.md) — IA placement and docs-app architecture (Shape stage)
 - [`write-the-docs`](../write-the-docs/SKILL.md) — drafting once Frame/Shape are settled
+- [`edit-the-docs`](../edit-the-docs/SKILL.md) — restructure and improve existing pages
 - [`review-the-docs`](../review-the-docs/SKILL.md) — self-review and PR review stages

.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md

@@ -39,6 +39,8 @@ _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
 
 _Skill:_ `/review-the-docs` — [Local self-review](../review-the-docs/SKILL.md#local-self-review-no-open-pr) on your own branch before opening the PR.

.agents/skills/write-the-docs/SKILL.md

@@ -2,31 +2,32 @@
 name: write-the-docs
 description: >-
   Draft new or updated Supabase docs content for a feature or launch,
-  grounded in Linear (the ticket plus its product/PM context), a read of the
-  actual code, and the docs style guide once one exists. Use when asked to
-  write docs for a new feature, a launch (e.g. Select 2026), or a Linear
-  ticket that needs net-new content rather than a bug fix. Not for
-  implementing existing docs bug reports — use work-linear-issue for that.
+  grounded in product intent (Linear when available), a read of the actual
+  code, and the docs style guide once one exists. Use when asked to write
+  docs for a new feature, a product launch, or a Linear ticket that needs
+  net-new content rather than a bug fix. Not for implementing existing docs
+  bug reports — use work-linear-issue for that. Not for restructuring
+  existing pages — use edit-the-docs for that.
 ---
 
 # Write the docs
 
-Drafts net-new (or substantially rewritten) Supabase docs content for a feature or launch. Distinct from [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md), which implements and fixes existing docs tickets — this skill is for the case where the content doesn't exist yet and has to be authored from scratch, grounded in four inputs rather than guessed.
+Drafts net-new Supabase docs content (or product-grounded rewrites) for a feature or launch. Distinct from [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md), which implements and fixes existing docs tickets, and from [`edit-the-docs`](../edit-the-docs/SKILL.md), which restructures and tightens pages that already exist without gathering net-new product intent. This skill is for the case where the content doesn't exist yet (or must be rewritten from intent + code), grounded in four inputs rather than guessed.
 
 ## Core rules
 
 1. **Gather before drafting.** Never draft from a ticket title alone. Pull all four inputs below first; a thin gather phase produces a draft that's wrong about how the feature actually works.
-2. **Separate confirmed behavior from product intent from inference.** Code tells you what the feature does today. Linear/PRD/PRFAQ tells you what it's meant to do and how it should be positioned. Anything you had to guess, flag explicitly rather than stating it as fact.
-3. **Follow CONTRIBUTING.md and WORD_LIST.md; say so when you fall back to a precedent page.** Don't silently invent voice/structure rules — name the nearest existing-page precedent you followed instead (see [reference/style-fallback.md](reference/style-fallback.md)).
+2. **Separate confirmed behavior from product intent from inference.** Code tells you what the feature does today. Linear/PRD/PRFAQ (or prior Frame/Shape output) tells you what it's meant to do and how it should be positioned. Anything you had to guess, flag explicitly rather than stating it as fact.
+3. **Follow CONTRIBUTING.md and WORD_LIST.md for voice, terminology, and formatting only, never for content accuracy.** These are a style reference, not a source of truth: rule 2's Linear+code read is what governs what the page actually says. Don't silently invent voice/structure rules either; name the nearest existing-page precedent you followed instead (see [reference/style-fallback.md](reference/style-fallback.md)).
 4. **Reuse, don't duplicate.** For docs-app architecture/placement questions, use [`ask-the-docs`](../ask-the-docs/SKILL.md) and [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md) rather than re-deriving that knowledge here.
-5. **Know what you're actually drafting.** Not everything that looks like "docs for a feature" is a hand-written page — see the content-type gate below before you start writing.
+5. **Know what you're actually drafting.** Not everything that looks like "docs for a feature" is a hand-written page — see the content-type gate below before you start writing. If the ask is restructure, reorder, connective text, or clarity on an existing page (no new product story), use [`edit-the-docs`](../edit-the-docs/SKILL.md) instead.
 
 ## Phase 1 — Gather (read-only)
 
-Four inputs, in order:
+Four inputs, read in this sequence (sequence, not priority; Linear remains the product-intent source and code remains the behavior source per rule 2 and Phase 1 step 3):
 
-1. **Style guide.** Start with [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) for voice, structure, and terminology. If those don't cover the case, fall back to the nearest comparable existing page under `apps/docs/content/` and say explicitly: _"no dedicated style guide yet — following the precedent of `<page>`."_ See [reference/style-fallback.md](reference/style-fallback.md).
-2. **Linear — the ticket and its product context.** Pull the Linear issue itself, then don't stop there: pull its parent project/initiative description too (PRD, PRFAQ, RFC, or initiative narrative) and any PM comments. Product framing/positioning language usually lives one level up from the ticket, not in the ticket body — see how the Select 2026 initiative's own description carried the real launch narrative, not any single project's ticket. Distinguish scope the ticket actually commits to from aspirational language in the PRD.
+1. **Style guide — voice/terminology reference.** Start with [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) for voice, structure, and terminology. If those don't cover the case, fall back to the nearest comparable existing page under `apps/docs/content/` and say explicitly: _"no dedicated style guide yet — following the precedent of `<page>`."_ See [reference/style-fallback.md](reference/style-fallback.md).
+2. **Linear — the ticket and its product context.** Linear is an internal Supabase tool: preferred when available, not required for open-source contributors. When a Linear issue is available, pull it, then its parent project/initiative description too (PRD, PRFAQ, RFC, or initiative narrative) and any PM comments. Product framing/positioning language usually lives one level up from the ticket, in the parent project or initiative description rather than the ticket body. Distinguish scope the ticket actually commits to from aspirational language in the PRD. If there is no Linear issue and no prior Frame/Shape product-intent output, stop drafting: ask internal authors for a Linear URL, otherwise hand off to [`pm-the-docs`](../pm-the-docs/SKILL.md) (Frame) and [`ask-the-docs`](../ask-the-docs/SKILL.md) when Shape/IA is unsettled. Resume only after product intent exists — never invent positioning, and never run Frame/Shape inside this Draft skill.
 3. **Code.** Read the actual implementation before writing a single behavior claim — the PRD describes intent, the code describes what shipped. Check the Linear issue/project first for a linked `supabase/supabase` PR — its diff and description are the most precise "what actually shipped" source, more precise than a general codebase read. If no PR is linked, locate the feature directly in `supabase/supabase` (or the product's own repo), and apply [`ask-the-docs`](../ask-the-docs/SKILL.md)'s reuse/minimalism lens: understand what exists before describing it. If code and PRD disagree, the code wins for behavior claims — flag the mismatch rather than silently picking one.
 4. **Whatever else the author supplies.** Screenshots, example projects, related pages, Slack threads, a specific voice sample. Screenshots are for more than general context — use them to verify the _exact_ button/menu/field labels before writing instructional steps that reference them; a mismatched UI label is one of the easiest, most avoidable errors in a draft. Ask for these when the feature's user-facing shape is still unclear after 1–3, rather than guessing.
 
@@ -47,7 +48,13 @@ When in doubt, ask `ask-the-docs` rather than guessing — this classification i
 - Follow `apps/docs` MDX conventions (component usage, frontmatter, code sample wiring) — see [`ask-the-docs`](../ask-the-docs/SKILL.md) for the pipeline details rather than re-deriving them.
 - Place the page using existing IA precedent; for a placement call that isn't obvious, consult [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md)'s nav/IA knowledge rather than guessing a nav slot.
 - **Wire it into navigation, not just onto disk.** Placement (which section) and nav enablement (whether it actually shows up) are separate — confirm the current nav-registration mechanism via `ask-the-docs`/`audit-docs-ia` rather than assuming a page is discoverable just because the file exists in the right folder.
-- Ground every behavior claim in Phase 1's code read (the linked PR when there is one); ground every "why this matters" framing in the PRD/PM context; mark inferred material inline (e.g. an HTML comment or a flagged line in the handoff summary) so a reviewer can find it fast.
+- Ground every behavior claim in Phase 1's code read (the linked PR when there is one); ground every "why this matters" framing in Linear/PM context or prior Frame/Shape output; mark inferred material inline (e.g. an HTML comment or a flagged line in the handoff summary) so a reviewer can find it fast.
+- **Write for timelessness.** Prefer documenting what exists now over promising future features. See [reference/common-pitfalls.md](reference/common-pitfalls.md#2-timeless-documentation).
+- **Keep it concise and avoid redundancy.** See [reference/common-pitfalls.md](reference/common-pitfalls.md#4-redundancy).
+- **Prefer paragraphs over single-item lists.** See [reference/common-pitfalls.md](reference/common-pitfalls.md#5-single-item-lists).
+- **Strip internal business context before the final draft.** HTML comments flagging PRD intent, roadmap speculation, internal ticket discussions, or "gap-fill" notes must be removed from MDX before handoff. Open-source docs shouldn't expose internal planning. Flag assumptions and open questions for reviewers in the PR description instead, not in the shipped content.
+- Search [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) when introducing or reviewing technical terms, UI actions, abbreviations, and potentially ambiguous language during drafting. This targeted search supplements, but does not replace, the full-file compliance check in Phase 2.5.
+- Reuse repeated content through `apps/docs/content/_partials/` instead of copying it. For nav wiring, partials, and file placement, see [`ask-the-docs`](../ask-the-docs/SKILL.md)'s `app-map.md` and `federated-docs.md`.
 
 ## Phase 2.5 — Review checklist
 
@@ -55,11 +62,25 @@ Before handing off, confirm:
 
 - [ ] CONTRIBUTING.md / WORD_LIST.md followed, or precedent page named explicitly
 - [ ] Every behavior claim traces to the code read (ideally the linked PR), not just the PRD
-- [ ] Every "why it matters" / positioning line traces to Linear/PM context, not invented
+- [ ] Every "why it matters" / positioning line traces to Linear/PM context or prior Frame/Shape output, not invented
 - [ ] Inferred or assumed material is flagged, not stated as fact
 - [ ] Content type confirmed as Guide/Troubleshooting (not something that belongs in generated Reference instead)
 - [ ] Nav placement and nav enablement both wired, not just the placement
 - [ ] Internal links resolve; first-use of new terms/acronyms is defined
+- [ ] Future promises minimized where possible (timeless documentation principle)
+- [ ] No unnecessary redundancy (same point restated multiple ways)
+- [ ] Single-item lists avoided unless there's a specific reason
+- [ ] Internal gap-fill and business context comments removed from MDX (keep only in PR description if needed for review)
+
+### Compliance checklist
+
+Re-read [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) in full before handoff, not just the sections searched during drafting. When a dedicated style guide lands in the repo, extend this checklist to cover it too.
+
+- [ ] Parentheses used only for acronyms or `(Optional)`, not prose asides
+- [ ] Bold, italics, and code used only for their distinct purposes (UI labels, must-not-miss terms), not for visual emphasis alone
+- [ ] No dash-based asides where a direct sentence reads better
+- [ ] Terminology matches `WORD_LIST.md` (including any terms flagged as imprecise, not just spelling/capitalization)
+- [ ] Headings, admonitions, and links follow CONTRIBUTING.md's "Styling, formatting, and grammar" and "Components and elements" sections
 
 ## Phase 3 — Handoff
 
@@ -67,11 +88,15 @@ This skill stops at a reviewable draft. It does not open worktrees or PRs itself
 
 - Hand off to [`create-pull-request`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/create-pull-request/SKILL.md) (and [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md) if the ticket needs a full worktree+PR flow) for the actual PR mechanics. Carry the Phase 1/2 flagged-assumptions list forward explicitly into that handoff — it belongs in the PR description (e.g. a "needs review" section) so a reviewer sees it, not just as an inline comment buried in the draft.
 - If the feature is UI-driven and the PR will need screenshots/GIFs, flag [`proof-it-works`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/proof-it-works/SKILL.md) as the next step rather than capturing evidence here.
+- Before opening the PR, run [`review-the-docs`](../review-the-docs/SKILL.md) local self-review: `pnpm lint:mdx`, `pnpm build:guides-markdown` where applicable, and anchor checks per [reference/drafting-mechanics.md](reference/drafting-mechanics.md).
 
 ## Additional resources
 
 - Style / terminology: [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md), [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md), [reference/style-fallback.md](reference/style-fallback.md)
+- Common pitfalls to avoid: [reference/common-pitfalls.md](reference/common-pitfalls.md)
+- Drafting mechanics: [reference/drafting-mechanics.md](reference/drafting-mechanics.md)
 - Content-type gate detail: [reference/content-type-gate.md](reference/content-type-gate.md)
+- Existing-page restructure/clarity: [`edit-the-docs`](../edit-the-docs/SKILL.md)
 - "Write the docs" checklist (Draft stage): [`pm-the-docs`](../pm-the-docs/SKILL.md)'s [reference/write-the-docs-checklist.md](../pm-the-docs/reference/write-the-docs-checklist.md)
 - Docs-app architecture/placement: [`ask-the-docs`](../ask-the-docs/SKILL.md), [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md)
 - PR mechanics: [`create-pull-request`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/create-pull-request/SKILL.md), [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md)

.agents/skills/write-the-docs/reference/common-pitfalls.md

@@ -0,0 +1,94 @@
+# Common pitfalls in docs drafts
+
+Patterns to watch for when drafting docs, based on review feedback. These are guidelines, not absolute rules — use judgment based on context.
+
+## 1. Internal planning context in open-source docs
+
+**Principle:** Supabase docs are open source. Internal planning context, unshipped features, and business intent shouldn't be visible in the public repo.
+
+**What to watch for:**
+
+- HTML comments referencing PRDs, roadmaps, or internal ticket discussions
+- "Gap-fill" notes about what's planned but not shipped
+- Internal product strategy or positioning discussions
+- References to any project-management or ticketing system (internal or a contributor's own tools)
+
+**Where to put internal context instead:**
+
+- PR description (for review-time context)
+- The team's project-management tool (for product/PM handoff)
+- Internal docs (for roadmap tracking)
+
+## 2. Timeless documentation
+
+**Principle:** Prefer documenting what exists now over promising future features ([Google's timeless documentation](https://developers.google.com/style/timeless-documentation)). Future promises become stale.
+
+**Common patterns to watch for:**
+
+- "Coming soon" / "will be available" / "once finalized"
+- "This page is a placeholder"
+- "Being rolled out gradually" without concrete eligibility criteria
+
+**Better alternatives:**
+
+- Document what exists today
+- Wait to publish until the feature is complete
+- If phased rollout is real, be specific: "Available to organizations on Pro and Enterprise plans"
+
+**Context matters:** Changelog and roadmap content naturally references the future — this guidance applies primarily to feature documentation.
+
+## 3. Placeholder pages
+
+**Principle:** Generally avoid shipping pages that explicitly say "This is a placeholder" or "More details coming soon."
+
+**Alternatives:**
+
+- Wait to publish until content is ready
+- If navigation structure requires it, link to external resources that are complete
+- Ship minimal but useful content (what's true today) rather than promises
+
+**Valid exceptions:** Navigation structure needs, federated docs where the placeholder provides context and links out, cross-references where the page existing (even minimal) provides value.
+
+## 4. Redundancy and over-explanation
+
+**Principle:** Avoid restating the same point in multiple ways. Prefer brevity — sometimes broad strokes help more than mechanical detail.
+
+**Common patterns:**
+
+- Multiple ways of saying the same thing: "It's free" + "You won't be billed" + "No charge"
+- Admonition stating a risk, then body text restating it verbatim
+- Adjacent sentences that rephrase each other
+- Over-explaining mechanical steps or implementation detail that doesn't help the reader complete the task
+
+**How to catch it:** If you can remove a sentence without losing information, it's probably redundant. If a procedure works with less setup explanation, prefer the shorter path.
+
+## 5. Single-item lists
+
+**Principle:** Prefer paragraphs over single-item bullet lists.
+
+**Why:** Single-item lists can signal incomplete content.
+
+**Valid exceptions:** Layout consistency across sections, future expansion expected, or when the item needs special visual emphasis.
+
+## 6. Restating admonition content
+
+**Principle:** Admonitions and body text should cover distinct points, not repeat each other.
+
+**What to watch for:** An admonition stating a risk/limitation, then the next paragraph restating it verbatim.
+
+## Summary checklist
+
+Before submitting a draft, check:
+
+- [ ] No HTML comments with internal PRD/roadmap/ticket context in MDX
+- [ ] Future promises minimized where appropriate (timeless documentation)
+- [ ] Placeholder pages avoided where possible
+- [ ] No unnecessary redundancy or mechanical over-explanation
+- [ ] Single-item lists avoided unless there's a reason
+- [ ] Admonitions and body text cover distinct points
+
+**Note:** These are guidelines based on review feedback, not absolute rules. Use judgment based on content type, context, and the specific documentation needs. The goal is clearer, more maintainable docs, not rigid adherence to formatting rules.
+
+## Style guide consolidation
+
+This content is style guidance, not skill-specific process. It belongs in a shared, human-and-agent-readable style guide rather than only inside this skill. When a dedicated style guide exists in the repo, fold this content into it and replace this file with a pointer, the same pattern [reference/style-fallback.md](style-fallback.md) already uses for CONTRIBUTING.md/WORD_LIST.md.

.agents/skills/write-the-docs/reference/drafting-mechanics.md

@@ -0,0 +1,46 @@
+# Drafting mechanics
+
+Mechanics that come up during drafting but aren't worth duplicating from
+`CONTRIBUTING.md` or `ask-the-docs`. For nav wiring, partials, and file
+placement, see `ask-the-docs`'s `app-map.md` and `federated-docs.md`.
+
+## Link paths
+
+- Use `/docs/...` paths for pages in Supabase docs.
+- Use site-root paths such as `/dashboard` for pages outside docs.
+- Use descriptive link text and sparse admonitions with the appropriate severity.
+
+## Anchor stability
+
+Anchor IDs are generated from heading text at render time, and nothing in CI
+checks that `#anchor` links still resolve. Before renaming, removing, or
+substantially rewording a heading, run:
+
+```bash
+grep -rn "#<old-anchor-slug>" apps/docs/content
+```
+
+Update every in-page and cross-file match. If a heading needs a stable anchor
+independent of its wording, pin it with a custom anchor, for example
+`## Some heading [#some-heading]`.
+
+## Lint and format
+
+From `apps/docs`:
+
+```bash
+pnpm lint:mdx
+pnpm build:guides-markdown
+```
+
+`pnpm lint:mdx` covers all content under `apps/docs/content`, including
+troubleshooting entries. `pnpm build:guides-markdown` only applies to guides,
+explainers, and tutorials.
+
+From the repository root, run `pnpm format` to apply Prettier to changed MDX
+files. This enforces repo-wide formatting rules, including lowercase SQL
+keyword casing in code samples.
+
+Treat `supa-mdx-lint` replacements as suggestions when context matters. Rewrite
+the sentence instead of applying a replacement that changes its technical
+meaning.

.agents/skills/write-the-docs/reference/style-fallback.md

@@ -1,7 +1,11 @@
 # Style guide fallback
 
 There is no separate published style guide yet beyond what already lives in
-this repo. Use the public sources below, in order:
+this repo. Use the public sources below, in order.
+
+This fallback governs voice, formatting, and terminology only. It's not a
+source of truth for behavior or product framing (that's the Gather phase's
+Linear + code read, per SKILL.md rule 3).
 
 1. Read [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md)
    for authoring conventions (voice, structure, document types).

.claude/CLAUDE.md

@@ -60,7 +60,7 @@ Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.ge
 The skills in `.claude/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
 
 - `copywriting` — any user-facing text, anywhere in the monorepo
-- `docs-content` — anything under `apps/docs`
+- `pm-the-docs` / `write-the-docs` / `edit-the-docs` / `ask-the-docs` / `review-the-docs` — anything under `apps/docs` (see `apps/docs/CONTRIBUTING.md` for the authoring skill model)
 - `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
 - `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
 - `safe-sql-execution` — any code that builds or executes SQL against user databases

.claude/skills/docs-content/SKILL.md

@@ -1,97 +0,0 @@
----
-name: docs-content
-description: Write, edit, organize, and review Supabase content anywhere in apps/docs — guides, explainers, tutorials, troubleshooting entries, reference docs, and partials. Use for MDX/TOML authoring, frontmatter, navigation, terminology, links, code samples, content listings, and docs validation.
----
-
-# Supabase docs authoring
-
-## Sources of truth
-
-Before changing docs content:
-
-1. Read `apps/docs/CONTRIBUTING.md` for content types, structure, components, and
-   style.
-2. Read `apps/docs/WORD_LIST.md` for preferred terminology, spelling, and
-   capitalization.
-3. Inspect nearby content of the same type and the relevant navigation section
-   before deciding on file placement or structure. Guides, explainers, and
-   tutorials live under `apps/docs/content/guides`. Troubleshooting entries live
-   under `apps/docs/content/troubleshooting` and use TOML frontmatter — follow
-   `_template.mdx` in that directory rather than a guide's YAML frontmatter.
-   Reference docs are generated from `apps/docs/spec` and library source, so
-   look for the spec file or repo definition instead of editing rendered output
-   directly.
-
-When guidance conflicts, follow `apps/docs/CONTRIBUTING.md`. Match literal code,
-API names, UI labels, and third-party product names even when they differ from the
-word list.
-
-## Writing workflow
-
-1. Identify the document type: explainer, tutorial, guide, or reference, per
-   `apps/docs/CONTRIBUTING.md`. A guide is a concise procedure for a targeted
-   task; a tutorial covers a larger goal and includes more explanatory context;
-   an explainer is conceptual and prose-based; reference content is factual,
-   like a dictionary entry. Troubleshooting entries follow their own TOML
-   structure rather than these four types.
-2. Define the reader's goal and prerequisites before drafting.
-3. Classify substantial sections as contextual, procedural, or reference content.
-   In a mixed page, group sections by information type so that context doesn't
-   interrupt the procedural path.
-4. For a long or mixed page, add a short introduction that links to its major
-   section groups and tells readers when to use each one. Skip this navigation
-   when a short page is already easy to scan.
-5. Connect contextual sections to their corresponding procedures when useful.
-   Add introductions to section groups, transitions between information types,
-   and outcomes after procedures. Don't link every adjacent section.
-6. Use second person, present tense, short paragraphs, and ordered steps for
-   sequential actions.
-7. Search `apps/docs/WORD_LIST.md` when introducing or reviewing technical terms,
-   UI actions, abbreviations, and potentially ambiguous language.
-8. Keep code samples executable in their stated context and consistent with
-   repository formatting. Clearly mark intentionally omitted code. Use lowercase
-   SQL keywords.
-9. Reuse repeated content through `apps/docs/content/_partials` instead of copying
-   it.
-10. Add new guide, explainer, and tutorial pages to
-    `apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts`.
-    File placement alone doesn't add a page to navigation. Troubleshooting
-    entries are indexed automatically and don't need a navigation entry.
-11. Use `/docs/...` paths for pages in Supabase docs and site-root paths such as
-    `/dashboard` for pages outside docs. Use descriptive link text and sparse
-    admonitions with the appropriate severity.
-
-## Validation
-
-From `apps/docs`, run:
-
-```bash
-pnpm lint:mdx
-pnpm build:guides-markdown
-```
-
-`pnpm lint:mdx` covers all content under `apps/docs/content`, including
-troubleshooting entries. `pnpm build:guides-markdown` only applies to guides,
-explainers, and tutorials.
-
-From the repository root, run `pnpm format` to apply Prettier to any changed
-MDX (and other) files. This enforces repo-wide formatting rules, including
-lowercase SQL keyword casing in code samples.
-
-Run broader type checking or tests when the change affects MDX components,
-content listings, navigation code, or generated output.
-
-For a mixed page, verify that context and procedures are grouped, introductory
-navigation links resolve to the intended sections, related context and procedures
-are cross-referenced where useful, and transitions make the reading path clear.
-
-Treat lint replacements as suggestions when context matters. Rewrite the sentence
-instead of applying a replacement that changes its technical meaning.
-
-Anchor IDs are generated from heading text at render time, and nothing in CI
-checks that `#anchor` links still resolve. Before renaming, removing, or
-substantially rewording a heading, run
-`grep -rn "#<old-anchor-slug>" apps/docs/content` to find in-page and
-cross-file links that target it, and update every match. If a heading needs a
-stable anchor independent of its wording, pin it with a custom anchor, for
-example `## Some heading [#some-heading]`.

.claude/skills/edit-the-docs

@@ -0,0 +1 @@
+../../.agents/skills/edit-the-docs

.cursor/skills/edit-the-docs

@@ -0,0 +1 @@
+../../.agents/skills/edit-the-docs

apps/docs/CONTRIBUTING.md

@@ -21,15 +21,16 @@ To make docs as clear as possible:
 
 ## AI agent skills for docs authoring
 
-If you're using Claude Code or Cursor, this repo ships four skills that back the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) authoring checklist.
+If you're using Claude Code or Cursor, this repo ships skills that back the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) authoring checklist.
 
-Invoke a skill by name: `/write-the-docs`, `/ask-the-docs`, `/pm-the-docs`, `/review-the-docs`.
+Invoke a skill by name: `/write-the-docs`, `/edit-the-docs`, `/ask-the-docs`, `/pm-the-docs`, `/review-the-docs`.
 
 | 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 |
 | [`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 |
 | [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft and PR triage/verification |
 
 The canonical files live in `.agents/skills/`, with Git symlinks in `.claude/skills/` and `.cursor/skills/`.