From 88ba84877568ed7abede0de71ebb8ba713063093 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 6 Aug 2026 19:59:25 -0300 Subject: [PATCH 1/2] feat: add capability-matrix maintenance skill Adds a repo-local Claude Code skill (.claude/skills/capability-matrix/) that helps contributors keep capabilities/*.yaml and specs/ internally consistent: semantic duplicate detection, naming-convention drift within a group, grouping fit, spec-file suggestions, and platform-scope notes. It's advisory only and defers to `npm run validate` for anything mechanical. Carves out .claude/skills/ from the repo-wide .claude/ gitignore rule so committed skills are tracked while session/worktree state stays ignored. Supersedes the CI-bot / PR-review-comment scope in SDK-994. --- .claude/skills/capability-matrix/SKILL.md | 111 ++++++++++++++++++++++ .gitignore | 4 +- 2 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/capability-matrix/SKILL.md diff --git a/.claude/skills/capability-matrix/SKILL.md b/.claude/skills/capability-matrix/SKILL.md new file mode 100644 index 0000000..81f0cea --- /dev/null +++ b/.claude/skills/capability-matrix/SKILL.md @@ -0,0 +1,111 @@ +--- +name: capability-matrix +description: Helps maintain the Supabase SDK capability matrix in 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: + +```bash +cd scripts/capability-matrix && npm run validate +``` + +This confirms schema conformance, `area` field matches the filename, IDs +follow the `..` 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/.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 `..` 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///.md`) are optional, but valuable +when a feature has real behavioral complexity: multiple named error +conditions, branching behavior, side effects, or prerequisites. If the new +feature's `description` hints at that kind of 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. diff --git a/.gitignore b/.gitignore index dcdfc9f..cdd3b6e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ # Claude Code internal state (worktree metadata, session files) -.claude/ +.claude/* +# ...except committed project skills +!.claude/skills/ # Generated site output site/ From 0d68d02b0e390779a472a84c0eaf9381b789d27d Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Fri, 7 Aug 2026 05:10:54 -0300 Subject: [PATCH 2/2] fix: correct spec-path guidance and close CI gap for spec-only PRs Two review findings on the capability-matrix skill, both still valid: - validate-capabilities.yml's PR trigger didn't include specs/**, so a spec-only change (e.g. a typo'd path that orphans a spec) could merge without ever running the validator that catches exactly that. - SKILL.md described spec paths as specs///.md, implying the current `group` field. The directory is actually derived from the feature id's own segments (/ per the schema), which can now diverge from `group` since SDK-1439 regrouped several features without renaming their ids. Reworded to match the schema's own terminology and call out the divergence. --- .claude/skills/capability-matrix/SKILL.md | 22 ++++++++++++--------- .github/workflows/validate-capabilities.yml | 1 + 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/.claude/skills/capability-matrix/SKILL.md b/.claude/skills/capability-matrix/SKILL.md index 81f0cea..c022191 100644 --- a/.claude/skills/capability-matrix/SKILL.md +++ b/.claude/skills/capability-matrix/SKILL.md @@ -27,9 +27,9 @@ cd scripts/capability-matrix && npm run validate ``` This confirms schema conformance, `area` field matches the filename, IDs -follow the `..` 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. +follow the `..` 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 @@ -83,12 +83,16 @@ its siblings in the same `group`: ## Step 5: spec suggestion -Spec files (`specs///.md`) are optional, but valuable -when a feature has real behavioral complexity: multiple named error -conditions, branching behavior, side effects, or prerequisites. If the new -feature's `description` hints at that kind of 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. +Spec files (`specs///.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 diff --git a/.github/workflows/validate-capabilities.yml b/.github/workflows/validate-capabilities.yml index 20bc67d..46a2993 100644 --- a/.github/workflows/validate-capabilities.yml +++ b/.github/workflows/validate-capabilities.yml @@ -6,6 +6,7 @@ on: pull_request: paths: - "capabilities/**" + - "specs/**" - "schema/**" - "scripts/capability-matrix/**" - "scripts/dart_symbol_extractor/**"