managing-database-migrations
Process use when you need to work with database migrations. This skill provides schema migration management with comprehensive guidance and automation. Trigger with phrases like "create migration", "run migrations", or "manage schema versions".
79
72%
Does it follow best practices?
Impact
94%
1.34xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/database/database-migration-manager/skills/managing-database-migrations/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description covers the basics of what the skill does and when to use it, including explicit trigger phrases, which is good for completeness. However, it relies on vague language like 'comprehensive guidance and automation' instead of listing concrete actions, and the trigger terms could be broader to capture more natural user phrasings. The opening 'Process use when' appears to be a grammatical error that hurts clarity.
Suggestions
Replace 'comprehensive guidance and automation' with specific concrete actions like 'create, run, rollback, and track database schema migrations'.
Expand trigger terms to include common variations users might say, such as 'rollback migration', 'schema change', 'alter table', 'database schema', or specific migration tool names.
Fix the grammatical error 'Process use when' at the beginning — it should read something like 'Use when you need to work with database migrations.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions 'schema migration management' and references 'create migration', 'run migrations', and 'manage schema versions', which name the domain and some actions, but it doesn't list multiple specific concrete actions (e.g., rollback, seed, diff schemas). 'Comprehensive guidance and automation' is vague filler. | 2 / 3 |
Completeness | The description answers both 'what' (schema migration management with guidance and automation) and 'when' (explicitly states 'Use when you need to work with database migrations' and provides trigger phrases). Both components are present and explicit. | 3 / 3 |
Trigger Term Quality | It includes some relevant trigger terms like 'create migration', 'run migrations', 'manage schema versions', and 'database migrations', but misses common variations users might say such as 'rollback', 'alter table', 'schema change', 'migrate database', or specific tools like 'alembic', 'knex', 'flyway'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on database migrations is a reasonably specific niche, but the description is broad enough ('comprehensive guidance and automation') that it could overlap with general database management or ORM-related skills. More specificity about the type of migrations or tooling would help distinguish it. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, highly actionable database migration skill with strong workflow clarity and concrete examples across multiple frameworks. Its main weaknesses are moderate verbosity (explaining patterns Claude likely knows, like expand-contract) and a monolithic structure that would benefit from splitting detailed reference material (error table, examples, resources) into separate bundle files. The validation checkpoints and rollback guidance are particular strengths.
Suggestions
Split the error handling table, detailed examples, and resources into separate bundle files (e.g., ERRORS.md, EXAMPLES.md) and reference them from the main SKILL.md to improve progressive disclosure and reduce token consumption.
Trim explanatory text that Claude already knows—e.g., the expand-contract pattern description could be reduced to just the phase names and actions, and the large-table migration tools section could be a brief reference rather than an explanation of how shadow tables work.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly comprehensive but includes some unnecessary verbosity. Phrases like 'Document whether the change is additive (safe) or destructive (requires data migration)' and general explanations of expand-contract pattern are things Claude already knows. The error handling table and examples add value but could be tighter. The Resources section with external URLs adds little value for Claude. | 2 / 3 |
Actionability | The skill provides concrete, executable commands throughout: specific CLI commands (pg_dump, alembic revision, npx prisma migrate dev), exact SQL patterns (CREATE TYPE, ALTER TABLE, UPDATE with WHERE clauses), and framework-specific naming conventions. The examples section gives fully concrete migration sequences rather than abstract descriptions. | 3 / 3 |
Workflow Clarity | The 10-step workflow is clearly sequenced with explicit validation checkpoints: step 1 captures baseline, step 6 has a full validation cycle (UP → test → DOWN → re-UP for idempotency), step 7 details the expand-contract pattern with distinct phases, and step 9 verifies migration state. The feedback loop of validate-on-staging before production is well-articulated. | 3 / 3 |
Progressive Disclosure | The content is a monolithic document with no bundle files or references to supplementary materials. The error handling table, examples, and resources could be split into separate files. For a skill of this length (~100+ lines of dense content), having everything inline makes it harder to navigate and consumes more tokens than necessary when only a subset of the guidance is needed. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
3a2d27d
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.