diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 53ac941840b..0db24a2a559 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -69,6 +69,14 @@ reviews: for both runtimes until the final cleanup pass (tracked in FE-3106). Keep this a reminder to verify, not a hard blocker: if no mirror is required, say so briefly rather than forcing a change. + - path: 'apps/docs/content/**/*.mdx' + instructions: | + Flag style, terminology, and structure issues as usual. When a page has two or + more of them, add one comment pointing the author at the `/write-the-docs` skill + for new content or `/edit-the-docs` for an existing page (canonical files in + `.agents/skills/`); both apply apps/docs/CONTRIBUTING.md and + apps/docs/WORD_LIST.md. Skip that pointer on a single issue, so it stays a + signal that the author isn't using the skills rather than boilerplate. - path: '{apps,packages}/**/*.{tsx,jsx,css,mdx}' instructions: | When reviewing UI changes, flag these accessibility gaps. Comments are diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8eba6749be..309727c5157 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,5 +27,9 @@ Prior to submitting your PR, please conduct the following pre-flight checks: - Run `npm run build` locally to ensure that your code builds successfully without having to wait on us to approve Vercel Preview deploys. - Ensure that the Prettier tests run successfully on your PR. +- If your PR changes docs content, use the docs authoring [agent skills](https://github.com/supabase/supabase/tree/master/.agents/skills). They apply the [docs style guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md) for you. + - `/write-the-docs` to draft a new page, or `/edit-the-docs` to revise an existing page. + - `/test-the-docs` to run any snippets you added. + - `/review-the-docs` to self-review before you open the PR. Running these before you create the PR will help reduce back and forth with the team. diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md index 2c8fc192003..59ccd0f293f 100644 --- a/apps/docs/CONTRIBUTING.md +++ b/apps/docs/CONTRIBUTING.md @@ -4,7 +4,14 @@ Our docs help developers to get started and keep succeeding with Supabase. We we If you'd like to contribute, see our list of [recommended issues](https://github.com/supabase/supabase/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation+label%3A%22help+wanted%22). We also welcome you to open a PR or a new issue with your question. -Here are some general guidelines on writing docs for Supabase. +Here are some general guidelines on writing docs for Supabase. If you write with an AI coding agent, these skills apply the guidelines for you: + +- `/write-the-docs` to draft a new page. +- `/edit-the-docs` to revise an existing page. +- `/test-the-docs` to run the snippets you wrote. +- `/review-the-docs` to check your work before you open a pull request. + +See [AI agent skills for docs authoring](#ai-agent-skills-for-docs-authoring) for the full set, including the skills that help you frame a page and place it in the information architecture. ## General principles @@ -83,7 +90,9 @@ The `using` clause accepts any expression that returns a boolean. ## AI agent skills for docs authoring -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). +Use these skills for every docs change you make with an AI coding agent: `/write-the-docs` to draft, and `/edit-the-docs` to revise an existing page. They apply this guide and the [word list](./WORD_LIST.md), so you don't have to hold either one in your head. + +Skills work in any agent that reads `.agents/skills/`, such as Claude Code, Cursor, or Codex. Invoke a skill with `/name`, for example `/write-the-docs`. The canonical files live in `.agents/skills/` (`.claude/skills` is a symlink). ### Write the docs skills diff --git a/apps/docs/DEVELOPERS.md b/apps/docs/DEVELOPERS.md index 37f48953ea1..65b6032c434 100644 --- a/apps/docs/DEVELOPERS.md +++ b/apps/docs/DEVELOPERS.md @@ -57,4 +57,4 @@ for coverage and skipped rules. ## Contributing -For repo organization and style guide, see the [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). +For repo organization and style guide, see the [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). If you write with an AI coding agent, use the `/write-the-docs` skill to draft, `/edit-the-docs` to revise an existing page, and `/review-the-docs` to self-review before you open a PR. diff --git a/apps/docs/README.md b/apps/docs/README.md index b961a051746..8cd53669d0e 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -20,4 +20,4 @@ It also means that we can switch to any documentation system we want. On this si ## Contributing -To contribute to docs, see the [developers' guide](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md) and [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). +To contribute to docs, see the [developers' guide](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md) and [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). If you write with an AI coding agent, use the `/write-the-docs` skill to draft and `/edit-the-docs` to revise an existing page. diff --git a/apps/docs/WORD_LIST.md b/apps/docs/WORD_LIST.md index 549c89a3faf..4bdce8533c0 100644 --- a/apps/docs/WORD_LIST.md +++ b/apps/docs/WORD_LIST.md @@ -9,6 +9,8 @@ conflict, follow `CONTRIBUTING.md`. Match literal code, API names, UI labels, an third-party product names even when they differ from this guidance, and format them as code or UI text as appropriate. +The `/write-the-docs` and `/edit-the-docs` agent skills apply this list as you draft. + Many unambiguous rules in this list are checked by `supa-mdx-lint`. Run `pnpm lint:mdx` from `apps/docs` after editing MDX. A lint warning still requires judgment: rewrite the sentence instead of applying a replacement that changes its