Content
88%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 strong operational skill body: executable commands for all eight subcommands, clearly sequenced workflows with genuine validation checkpoints (round-trip upgrade/downgrade tests, alembic heads confirmation), and rare project-specific gotchas that Claude could not infer. The main lever is structural — the long rebase procedure and pitfall detail could move to reference files to trim the main body.
Suggestions
Move the detailed ~60-line rebase procedure (Steps 1-5) into a references/rebase.md and keep a short summary in SKILL.md, so the main body stays a lean dispatch overview.
Condense the rebase Step 5 stale-Docker-image explanation into a compact 'Gotcha:' bullet (rebuild data-import before testing; alembic current only reads the version table) to cut ~80 words.
Move the sqlalchemy-continuum version-tables pitfall detail (create_type=False, which models need <table>_version) into a reference file or trim it to the two actionable rules.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific, non-obvious knowledge (divergent-head rebasing, the stale data-import Docker image, sqlalchemy-continuum version tables) and mostly skips concepts Claude already knows. It is not a 5 because several prose passages could be trimmed — e.g. "because that's where alembic.ini lives and where models is importable" and the ~120-word stale-image explanation in rebase Step 5 — but not a 3 because there is no real padding. | 4 / 5 |
Actionability | Every subcommand ships copy-paste-ready bash: "alembic revision --autogenerate -m \"your migration message\"", "git show origin/main:backend/alembic/versions/<new-file>.py > ...", "docker compose --profile setup up db data-import --build -d", plus concrete autogenerate-review checklists. Placeholders like <new-file>.py are inherently variable filenames, not pseudocode, so the guidance is fully executable. | 5 / 5 |
Workflow Clarity | Multi-step flows are numbered with explicit validation checkpoints and feedback loops: create's "Review the generated migration (critical!)" checklist and upgrade → verify → downgrade → re-apply round-trip, and rebase's "Confirm with alembic heads — it should report exactly one head" plus a real downgrade/upgrade round-trip with "\d <table>" schema checks. The destructive/batch database operations all carry verification, so the workflow-clarity cap at 3 does not apply. | 5 / 5 |
Progressive Disclosure | As a single-file skill it is well structured — an argument-dispatch section per subcommand, a Key File Locations index, and a Common Pitfalls section make navigation easy. It is not a 5 because the ~60-line rebase procedure and the deep pitfall detail would sit more naturally in references/ files, and no bundle files exist to split the 240-line body. | 4 / 5 |
Total | 18 / 20 Passed |