Content
65%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The content is highly actionable with executable commands, examples, and correct/incorrect contrasts, but it is a monolithic 750-line document that inlines six topics with no progressive disclosure. Its biggest defects are contradictory migration guidance between Sections 2 and 4, generic SQL formatting explanation Claude already knows, and missing validation feedback loops for destructive database operations.
Suggestions
Resolve the contradiction between Section 2 (declarative schema management: 'Do NOT create or modify files directly in supabase/migrations/') and Section 4 (hand-authored migration files with a naming format) — state when each approach applies or merge them into one authoritative workflow.
Split the six topics into one-level-deep reference files (e.g. edge-functions.md, schema-management.md, sql-style.md, rls.md) and keep SKILL.md as a concise overview with clearly signaled links.
Trim content Claude already knows: the generic SQL formatting/style rules, the redundant closing '## Summary' section, and the repeated 'You are an expert...' framing; add explicit validation checkpoints (e.g. review generated migration output before applying) for destructive operations.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Supabase-specific material (CLI commands, migra caveats, RLS performance patterns) is efficient, but the generic SQL style guide ('Use lowercase for SQL reserved words', whitespace/alias/CTE formatting), the redundant closing '## Summary', and repeated 'You are an expert...' framing re-explain what Claude already knows. Matches 'mostly efficient but includes some unnecessary explanation'; the generic style-guide section is more than a minor instance, so not 4. | 3 / 5 |
Actionability | Guidance is copy-paste ready: exact CLI commands ('supabase db diff -f <migration_name>', 'supabase secrets set --env-file ...'), a precise migration filename format with field-by-field rules, executable Edge Function and SQL examples, and incorrect/correct RLS policy pairs covering the common cases. | 5 / 5 |
Workflow Clarity | The declarative schema workflow is sequenced (stop -> diff -> review), but Section 2 mandates 'Do NOT create or modify files directly in the supabase/migrations/ directory' while Section 4 instructs hand-creating migration files there — unreconciled contradictory guidance. Destructive/database operations also lack validate-and-retry feedback loops, so the rubric's cap at 3 applies; not 2 because each workflow's steps are individually well defined. | 3 / 5 |
Progressive Disclosure | The body has clear numbered sections, but six full topics (Edge Functions, schema management, SQL style, migrations, functions, RLS) are inlined in a single ~750-line file with no reference files at all — content that clearly belongs in separate files is inline. Matches 'some structure but could be better organized'; not 4 because essentially all detailed material lives in SKILL.md itself. | 3 / 5 |
Total | 14 / 20 Passed |