## 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>
Migrates all studio-related Cursor rules to Claude skills and adds a
top-level `.claude/CLAUDE.md` for project context. Docs rules left in
place.
**Decisions:**
- Only studio + testing rules migrated — docs rules intentionally left
in `.cursor/rules/docs/`
- Vitest skill already shared via symlink (`.claude/skills/vitest` →
`.agents/skills/vitest`) — nothing to migrate
- Grouped ~21 granular cursor rules into 5 new skills + 1 updated skill
by topic
- `studio-architecture` skill fully merged into `CLAUDE.md` and deleted
to avoid overlap
- Skills are self-contained (content inlined, not relying on sub-files)
since Claude reads SKILL.md first
- Skills cross-reference each other inline where relevant (e.g.
best-practices → testing, error-handling, queries)
- No `paths` frontmatter — would auto-inject full skill content on every
matching file. Current description-based matching is more selective and
token-efficient.
**Removed:**
- `.cursor/rules/studio/` (21 rule files covering architecture, best
practices, UI patterns, queries, styling, etc.)
- `.cursor/rules/testing/` (e2e-studio + unit-integration rules)
- `.cursor/rules/studio-useStaticEffectEvent.mdc`
- `.claude/skills/studio-architecture/` — fully merged into CLAUDE.md to
avoid duplication
- `.claude/skills/studio-testing/rules/` — orphaned sub-files after
inlining content into SKILL.md
**Added:**
- `.claude/CLAUDE.md` — concise monorepo overview with structure,
commands, and conventions. Absorbs studio-architecture content.
References `studio-*` skills for detail.
- `.claude/skills/studio-best-practices/` — boolean naming, component
structure, loading/error/success patterns, state management, hooks,
TypeScript conventions. Cross-references `vercel-composition-patterns`,
`studio-ui-patterns`, `studio-queries`, `studio-error-handling`, and
`studio-testing` inline where relevant.
- `.claude/skills/studio-ui-patterns/` — layout, forms, tables, charts,
empty states, navigation, cards, alerts, sheets. Grouped from ~10
separate cursor rules into one cohesive skill.
- `.claude/skills/studio-queries/` — React Query `queryOptions` pattern,
`keys.ts` structure, mutation hook template, imperative fetching.
- `.claude/skills/use-static-effect-event/` — the `useStaticEffectEvent`
hook: when to use, when not to, patterns, implementation.
**Changed:**
- `.claude/skills/studio-e2e-tests/` — renamed from `e2e-studio-tests`
for `studio-*` naming consistency. Merged race condition, waiting
strategy, test structure, assertion, and cleanup patterns from the
cursor e2e rule.
- `.claude/skills/studio-testing/` — inlined key content from sub-rule
files directly into SKILL.md so it's self-contained. Removed broken
`AGENTS.md` reference. Deleted orphaned `rules/` sub-files.
- `.claude/skills/vercel-composition-patterns/` — added note that Studio
uses React 18, so React 19 patterns should be skipped.
- `.gitignore` — added `!.claude/CLAUDE.md` exception so it's tracked.
## To test
- Open Claude Code in the repo, verify `.claude/CLAUDE.md` loads as
project context
- Ask Claude about Studio conventions and verify it references the right
skills
- Check that `studio-*` skills appear in the skill list
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Problem
The design system documentation and examples promote an invalid usage of
react-hook-form state.
## Solution
- Fix the documentation and examples
- Update Claude skills for future components
## Out of scope
- Fix current code across the repository
## Problem
Some tests rely on hard coded timeouts. That makes them
- brittle if the timeout is not long enough
- take longer than necessary if the timeout is too long
## Solution
- Rely on playwright `expect` retries when possible
- Rely on UI updates when possible
## Summary
- Updates the Cursor rule at `.cursor/rules/studio/queries/RULE.md` to
recommend the `queryOptions` pattern from TanStack React Query instead
of custom `useXQuery` wrapper hooks
- Provides an example implementation by refactoring
`thirdPartyAuthIntegrationsQuery` from a
`useThirdPartyAuthIntegrationsQuery` hook to
`thirdPartyAuthIntegrationsQueryOptions`
## Why this pattern?
The `queryOptions` factory pattern from TanStack Query v5 offers several
benefits:
1. **Type safety** - Query keys and return types are properly inferred
2. **Reusability** - The same query config can be used with both
`useQuery()` in components and `queryClient.fetchQuery()` for imperative
fetching
3. **Consistency** - Aligns with TanStack Query's official
recommendations
4. **Simplicity** - Removes the need for custom generic wrapper hooks
## Test plan
- [ ] Verify the ThirdPartyAuthForm component works correctly with the
new pattern
- [ ] Check that the Cursor rule provides clear guidance for writing new
queries
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Documentation**
* Updated query pattern documentation with revised implementation
guidance.
* **Refactor**
* Updated third-party authentication integrations data fetching
mechanism.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
* chore(studio): integrate cursor rules with form patterns
* chore(studio): update FormLayout inner styling
* chore(studio): align actions form field to the right
* chore(design-system): wrap each form field in a CardContent
* Initial work on vector buckets.
* Add more queries and UI.
* chore(studio): vector buckets contents (#39705)
* language
* match analytics buckets
* shared empty state
* proper loading state
* create dialog cleanup
* simplify copywriting
* proper details
* filtering
* use real data
* chore(studio): vector buckets polish A (#39759)
* empty state
* better checks
* bucket name in sheet
* fix typo
* sheet improvements
* rename vector index to vector table
* cleanup
* More work on the vector indexes.
* Add delete for bucket and indexes. Create index should now work.
* chore(studio): vector buckets polish B (#39794)
* loading
* delete modal
* fix modal behaviour
* Add modal for deleting vector buckets.
* Bring back the shimmering loader.
* chore(studio): vector buckets polish C (#39887)
* fix bucketname on deletion dialog
* empty states
* remove extraneous padding
* proper loading and not-found cases
* Minor fixes.
* Minor updates to the vector components.
* Add more instructions to the cursor rules.
* Some refactors and shifting files around
* Refactor analytics buckets detial to improve time to fcp
* Fix
* Refactors + simplify
* Last few nits, just leaving comments
* If the bucket is not empty, delete all indexes first.
---------
Co-authored-by: Danny White <3104761+dnywh@users.noreply.github.com>
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
* docs: add cursor rule for embedding generation process
Add documentation for cursor IDE about how docs embeddings are generated,
including the workflow for creating and uploading semantic search content.
* feat: improve API reference metadata upload with descriptive content
- Add preembeddings script to run codegen before embedding generation
- Enhance OpenApiReferenceSource to generate more descriptive content including
parameters, responses, path information, and better structured documentation
* feat: add Management API references to searchDocs GraphQL query
- Add ManagementApiReference GraphQL type and model for API endpoint search results
- Integrate Management API references into global search results
- Update test snapshots and add comprehensive test coverage for Management API search
* style: format
* feat(graphql): add paginated errors collection query
- Add new GraphQL query field 'errors' with cursor-based pagination
- Add UUID id column to content.error table for cursor pagination
- Implement error collection resolver with forward/backward pagination
- Add comprehensive test suite for pagination functionality
- Update database types and schema to support new error collection
- Add utility functions for handling collection queries and errors
- Add seed data for testing pagination scenarios
This change allows clients to efficiently paginate through error codes using cursor-based pagination, supporting both forward and backward traversal. The implementation follows the Relay connection specification and includes proper error handling and type safety.
* docs(graphql): add comprehensive GraphQL architecture documentation
Add detailed documentation for the docs GraphQL endpoint architecture, including:
- Modular query pattern and folder structure
- Step-by-step guide for creating new top-level queries
- Best practices for error handling, field optimization, and testing
- Code examples for schemas, models, resolvers, and tests
* feat(graphql): add service filtering to errors collection query
Enable filtering error codes by Supabase service in the GraphQL errors collection:
- Add optional service argument to errors query resolver
- Update error model to support service-based filtering in database queries
- Maintain pagination compatibility with service filtering
- Add comprehensive tests for service filtering with and without pagination
* feat(graphql): add service filtering and fix cursor encoding for errors collection
- Add service parameter to errors GraphQL query for filtering by Supabase service
- Implement base64 encoding/decoding for pagination cursors in error resolver
- Fix test cursor encoding to match resolver implementation
- Update GraphQL schema snapshot to reflect new service filter field
* docs(graphql): fix codegen instruction
