Content
71%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 thorough, highly actionable policy document with concrete commands, executable examples, and explicit validation rules for risky database operations. Its main weaknesses are a monolithic single-file structure that inlines reference-grade material and some duplicated guidance around db-exec/db-patch.
Suggestions
Move the identity-column policy, state-machine rules, and migration-ownership details into reference files under references/ (e.g., references/identity-columns.md, references/migrations.md) and keep SKILL.md as an overview with one-level-deep pointers.
Consolidate the db-exec vs db-patch guidance into the decision table only, removing its repetition in the Agent Access bullet list and the Do list.
Make the domain-data code example self-contained by showing how `db` is obtained (e.g., const db = getDb()) so the snippet is copy-paste ready.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence (no explanations of what Postgres, ORM, or OAuth are), but the db-exec vs db-patch guidance is repeated across the Agent Access list, the decision table, and the Do list, and the migration-naming rationale paragraph runs long — some trimming is possible. | 4 / 5 |
Actionability | Guidance is highly concrete: exact commands with flags (pnpm action db-patch --table <t> --column <c>), executable registerIdentityColumns and Drizzle schema snippets, and named APIs. Minor gap: the domain-data example queries via a `db` variable that is never defined in the snippet (getDb()/createGetDb is described only in prose). | 4 / 5 |
Workflow Clarity | Risky operations carry explicit validation: migrations must be additive and backward compatible, status transitions are compare-and-set with "treat zero updated rows as a lost race or an illegal transition, never success", and a decision table routes db-exec vs db-patch. However, the migration-ownership paths (Drizzle Kit starters vs Chat vs Clips) are scattered across several conditionals rather than one clear sequence. | 4 / 5 |
Progressive Disclosure | The skill is a single ~250-line file with no references/ bundle; well-organized sections and tables exist, but deep policy material that belongs in separate reference files (identity-column policies, state-machine rules, migration ownership details) is fully inlined in SKILL.md. | 3 / 5 |
Total | 15 / 20 Passed |