Supabase docs authoring

Sources of truth

Before changing docs content:

Read apps/docs/CONTRIBUTING.md for content types, structure, components, and style.
Read apps/docs/WORD_LIST.md for preferred terminology, spelling, and capitalization.
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

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.
Define the reader's goal and prerequisites before drafting.
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.
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.
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.
Use second person, present tense, short paragraphs, and ordered steps for sequential actions.
Search apps/docs/WORD_LIST.md when introducing or reviewing technical terms, UI actions, abbreviations, and potentially ambiguous language.
Keep code samples executable in their stated context and consistent with repository formatting. Clearly mark intentionally omitted code. Use lowercase SQL keywords.
Reuse repeated content through apps/docs/content/_partials instead of copying it.
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.
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:

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].

Overall Score

82/100

Grade

B

Good

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

88

Quality

80

Clarity

85

Completeness

78

Summary

This skill guides agents to write, edit, and organize documentation content in the Supabase docs repository. It covers MDX/TOML authoring, frontmatter, navigation, terminology management, and content validation across guides, tutorials, explainers, troubleshooting entries, and reference docs. The skill emphasizes reading source-of-truth files (CONTRIBUTING.md, WORD_LIST.md) before making changes and provides structured workflows for document type identification, content classification, and validation.

Detected Capabilities

file readfile writedirectory navigationmarkdown/mdx authoringshell execution (pnpm commands)content validation

Trigger Keywords

Phrases that agents use to match this skill to user intent.

write supabase guideedit docs contentadd documentation pagemanage docs navigationupdate terminologyvalidate markdown docs

Use Cases

+Create new Supabase documentation guides, tutorials, and explainers within the docs repository
Edit and maintain existing documentation content while adhering to style and terminology standards
Organize documentation content by proper file placement, navigation structure, and content grouping
Validate documentation using MDX linting and guide markdown building tools
Manage anchor links and ensure cross-file references remain valid when renaming headings
Reuse documentation content through partials instead of duplicating across files

Quality Notes

Clear document type taxonomy provided (explainer, tutorial, guide, reference, troubleshooting) with explicit differentiation
Well-structured workflow with numbered steps that guide agents through identification, drafting, and organization
Strong emphasis on reading source-of-truth files (CONTRIBUTING.md, WORD_LIST.md) before making changes — reduces errors and maintains consistency
Practical validation commands provided with clear context (when to run from apps/docs vs. repository root)
Comprehensive coverage of common documentation tasks: frontmatter handling, navigation configuration, partial reuse, code sample maintenance
Anchor ID handling and heading rename procedures documented with concrete grep example
Guidance on information architecture (grouping contextual, procedural, and reference content) helps with larger documentation pages
Code samples are kept executable and consistent with repository formatting standards
Missing explicit guidance on new vs. edit vs. review workflows — the skill covers all three but doesn't clearly separate them
No explicit error handling guidance for common authoring errors (e.g., broken links after refactoring, missing frontmatter fields)
Scope is well-bounded to apps/docs and related files, but external reference docs generated from spec/source are mentioned without deep guidance on modifying them

Model: claude-haiku-4-5-20251001Analyzed: Jul 19, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

docs-content