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.
A highly actionable troubleshooting reference organized by symptom with concrete diagnostic and fix code for each area. Its main weaknesses are the absence of validation/revert steps around the database changes it instructs (capping workflow clarity), and a monolithic 450-line body whose error-code tables duplicate the existing reference file.
Suggestions
Add validation feedback loops around the SQL the skill instructs Claude to run: after CREATE POLICY / CREATE INDEX fixes, re-run the 'SET request.jwt.claims' test query to confirm the fix; after 'SET log_statement' / 'SET log_min_duration_statement' debugging, include the RESET statements to revert the temporary settings.
Move the 'Common Error Codes' tables (PGRST*, PostgreSQL, Auth) out of SKILL.md into references/common-errors.md, replacing them with a one-line pointer, so the body acts as an overview and the reference file is the single source for error codes.
Replace placeholder fragments with runnable equivalents — e.g., complete the 'Optimize RLS Queries' example as a full CREATE POLICY statement and substitute real patterns for 'heavyComputation()' in the Edge Function timeout section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean code with minimal prose padding and no explanation of concepts Claude already knows (no 'Supabase is a backend-as-a-service...' boilerplate). Minor trimmable instances remain: the redundant opening line 'Debug and fix common Supabase issues.', comments restating the obvious ('// Check Docker is running'), and the ~30 lines of error-code tables that duplicate references/common-errors.md. Above anchor 3 ('some unnecessary explanation') but not the every-token-earns-its-place level of anchor 5. | 4 / 5 |
Actionability | Nearly every section gives executable JavaScript/SQL/bash snippets (e.g., the RLS debug sequence with 'SET request.jwt.claims = ...' and 'SELECT auth.uid();', the realtime cleanup useEffect). A few snippets are illustrative fragments rather than copy-paste ready: 'const result = heavyComputation()'/'heavyComputationAsync()' are placeholder names, 'USING (user_id IN (SELECT ...))' appears without its CREATE POLICY wrapper, and '...values'/'{...}' ellipses appear in upsert and channel examples. Concrete with minor gaps — anchor 4, not fully executable anchor 5. | 4 / 5 |
Workflow Clarity | A clear diagnosis flow exists (Quick Diagnosis symptom→cause table funneling into per-issue sections, with check steps like 'supabase status', the _health probe, and subscription status logging), but there are no validate-after-fix checkpoints for the database operations the skill performs. The scoring note caps workflow clarity at 3 when database operations lack feedback loops: e.g., 'SET log_statement = ...' (temporary, per its own comment) is never reverted, and CREATE POLICY examples aren't followed by a re-test step. Not anchor 2 — the sequence and per-symptom checks are well defined; anchor 4's 'most checkpoints present' is blocked by the missing verify-the-fix loop. | 3 / 5 |
Progressive Disclosure | The single reference is real, one level deep, and clearly signaled in a dedicated '## References' section ('[common-errors.md](references/common-errors.md) - Error code reference'). However, substantial content that overlaps the reference file — the entire 'Common Error Codes' section of PGRST/PostgreSQL/auth tables — is inlined in a ~450-line body, matching anchor 3's 'content that should be separate is inline' rather than anchor 4's 'most content appropriately placed'. | 3 / 5 |
Total | 14 / 20 Passed |