mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 17:35:10 +03:00
Nik RichersandNik Richers
cf36ad9e52
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Adds four AI agent skills that support docs contributors across the authoring lifecycle, intended to lower the barrier to entry for contributing to our docs. Closes DOCS-1287. ## What is the current behavior? Our process for writing docs is somewhat undefined beyond some general guidance in CONTRIBUTING.md and we don't make as easy to contribute to our docs as we could. As a result, content often needs additional changes during PR reviews or requires further revisions after merging. The four AI agent skills in this PR already existed in a private repo where I've been testing them but they were not previously available for general use until now. ## What is the new behavior? - Four skills added under `.agents/skills/`, symlinked from `.claude/skills/` and `.cursor/skills/` (same pattern as the existing `vitest` skill). - `ask-the-docs`: answers architecture and design questions about apps/docs (MDX pipeline, content components, federated docs) and checks whether a proposed change fits existing docs app patterns. - `write-the-docs`: drafts net-new or substantially rewritten docs content for a feature or launch, grounded in the Linear ticket, the actual code, and the docs style guide. - `review-the-docs`: runs a local, PR-type-specific review checklist against any open supabase/supabase docs PR (markdown pipeline, MDX content, tutorials, examples, Studio links) and produces a consolidated report. - `pm-the-docs`: supports "Write the docs" authoring process across the different phases. - `apps/docs/CONTRIBUTING.md` gets a new "AI agent skills for docs authoring" section mapping each skill to its checklist stage - Cross-references to skills that stay in `docs-agent-skills` (`work-linear-issue`, `audit-docs-ia`, `create-pull-request`, `proof-it-works`, `pm-the-docs-full`) now point there via absolute GitHub links instead of relative paths ## Additional context - Companion PR: [supabase/docs-agent-skills#28](https://github.com/supabase/docs-agent-skills/pull/28). Removes the three moved skills, renames `pm-the-docs` to `pm-the-docs-full`, and fixes now-dangling inbound links. - Worktree: `~/GitHub/supabase/supabase-worktrees/nikrichers/docs-1287-move-skills-mentioned-in-write-the-docs-from-docs-agent` - Opened as draft: this is a docs-authoring-tooling change with no runtime/build surface. Flip to ready once you've sanity-checked the skill content. ### Test plan - [ ] `ls -la .claude/skills/{ask-the-docs,pm-the-docs,write-the-docs,review-the-docs}` resolves to `.agents/skills/...` - [ ] Open a fresh Claude Code session with cwd in this repo and confirm `/ask-the-docs`, `/pm-the-docs`, `/write-the-docs`, `/review-the-docs` are available - [ ] Read the new section in [`apps/docs/CONTRIBUTING.md`](apps/docs/CONTRIBUTING.md) in context - [ ] Spot-check `.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md` has no `linear.app` links and carries the snapshot disclaimer --------- Co-authored-by: Nik Richers <nik@validmind.ai>
Reference Docs
Supabase Reference Docs
Maintainers
If you are a maintainer of any tools in the Supabase ecosystem, you can use this site to provide documentation for the tools & libraries that you maintain.
DocSpec
We use documentation specifications which can be used to generate human-readable docs.
- OpenAPI: for documenting API endpoints.
- SDKSpec (custom to Supabase): for SDKs and client libraries.
- ConfigSpec (custom to Supabase): for configuration options.
- CLISpec (custom to Supabase): for CLI commands and usage.
The benefit of using custom specifications is that we can generate many other types from a strict schema (eg, HTML and manpages). It also means that we can switch to any documentation system we want. On this site we use Next.js, but on Supabase's official website, we use a custom React site and expose only a subset of the available API for each tool.
Contributing
To contribute to docs, see the developers' guide and contributing guide.