| name | capability-matrix |
| description | Helps maintain the Supabase SDK capability matrix in packages/capability-matrix/capabilities/*.yaml and specs/ — naming a new feature ID, picking or creating a group, checking for duplicate or semantically-overlapping capabilities, spotting naming drift within a group, suggesting when a spec file is warranted, and noting platform-specific behavior. Use whenever a capability YAML or spec file is being added or edited, before opening a PR that touches capabilities/, or when asked to review/audit the matrix, check for duplicates, or suggest groupings. This is an advisory pass, not a gate — it complements `npm run validate`, it doesn't replace it. |
Capability Matrix Maintenance
This repo is the canonical registry of features across Supabase's client SDKs
(capabilities/*.yaml). The JSON Schema and npm run validate already catch
everything mechanical: malformed IDs, area/filename mismatches, exact
duplicate IDs, orphaned spec files. What they can't catch is judgment —
whether a new feature is actually new, whether its name reads naturally
next to its siblings, whether it's filed under the right group. That
judgment is what this skill provides.
This is a local, advisory pass. There is no CI bot version of this — findings
are suggestions for the person editing the file to accept, adjust, or ignore.
Don't present anything as a hard requirement.
Step 0: run the mechanical checks first
Before spending any judgment calls, run the deterministic validator so you're
not duplicating what it already guarantees:
cd packages/capability-matrix && npm run validate
This confirms schema conformance, area field matches the filename, IDs
follow the <area>.<group_namespace>.<method_stem> pattern, no two features
share an exact ID, and every spec file maps to a real feature. If this
fails, fix that first — the checks below assume a structurally valid file.
Step 1: read for context, not just the diff
Read the whole target area file (capabilities/<area>.yaml), not just the
new/changed entry — group names and sibling features are the only baseline
for judging naming and grouping consistency. If the new feature could
plausibly overlap another area (e.g. something touching both realtime and
database, or client and auth session handling), skim that file too.
Step 2: semantic duplicates
npm run validate only catches identical IDs. Read every feature's name +
description in the same area (and group, if cross-area overlap looks
possible) and ask: does this describe behavior another entry already
covers, just worded differently? Common patterns to watch for:
- Same underlying API call described from two angles (e.g. a "set" feature
and a separate "update" feature that hit the same endpoint)
- A new entry that's actually a narrower case of an existing one (should it
be a note on the existing feature instead of a new ID?)
- Copy-pasted description with only the verb changed
If you find a likely duplicate, name both IDs and describe the overlap —
don't assume which one should win; that's the author's call.
Step 3: naming consistency
The schema enforces the <area>.<group>.<method> shape via regex, but not
whether the words chosen fit. Compare the new feature's id/name against
its siblings in the same group:
- Verb choice — if the group already uses
create/delete/list for
parallel operations, a new add_x or remove_x reads inconsistent.
(See CONTRIBUTING.md's "Choosing a feature ID" section for the
verb-object convention.)
- Admin/scoped variants should be namespaced the way existing ones are
(
auth.admin.delete_user, not auth.delete_user_admin).
name (the human-readable title) should match the tone of sibling
entries in the same group — not suddenly more/less verbose or technical.
Step 4: grouping
- Does the feature's
group field point to a group that actually fits, or
is it forcing a fit into the nearest existing one? If several recent
features don't cleanly fit any group, say so and suggest a new group
entry under groups: at the top of the file.
- Conversely, flag a group that's accumulated features with little in
common — that's a sign it should split.
- A feature with no
group at all is valid (it's optional) but worth a
second look — is that intentional, or was a fitting group just missed?
Step 5: spec suggestion
Spec files (specs/<area>/<group_namespace>/<method_stem>.md) are optional,
but valuable when a feature has real behavioral complexity: multiple named
error conditions, branching behavior, side effects, or prerequisites. The
directory always mirrors the feature id's own segments — e.g.
auth.mfa.challenge lives at auth/mfa/challenge.md — regardless of what
that feature's optional group field currently says; the two can diverge
when a feature has been regrouped for display without renaming its id.
If the new feature's description hints at real complexity and no spec
exists, suggest creating one from specs/TEMPLATE.md. Don't suggest a spec
for a simple getter/setter with an already-complete one-line description.
Step 6: platform-scope notes
There is no schema field for "this only applies to mobile/web SDKs" — that
nuance (biometric auth, secure enclave storage, browser-only APIs like
localStorage) is expected to live in prose, not structured data. If a
feature's behavior is inherently platform-scoped, suggest a line either in
the feature's description or, if it has a spec, in the spec's ## Notes
section. Point out why it matters: SDKs that don't apply can declare
not_applicable in their sdk-compliance.yaml, but only if the constraint
is documented somewhere a maintainer would see it.
Presenting findings
Group findings by step, lead with the ones most likely to need a real
change (duplicates, then naming, then grouping, then spec/platform notes).
For each finding, name the specific IDs involved and explain the reasoning
in one or two sentences — enough for the author to judge it themselves.
Skip steps that have nothing to report; don't manufacture a finding to fill
out every section. If everything looks clean, say so briefly and move on.
