database-design

Database schema design, optimization, and migration patterns for PostgreSQL, MySQL, and NoSQL databases. Use for designing schemas, writing migrations, or optimizing queries.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/database-design/SKILL.md

Quality

Content

72%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A lean, highly actionable pattern reference with excellent executable SQL examples and good section organization. Its weaknesses are structural: migration workflows lack the validation/feedback checkpoints the rubric demands for database operations, and everything is packed into one file with no progressive disclosure.

Suggestions

Add explicit validation checkpoints to the migration workflows: verify backfill row counts before switching reads, confirm dual-write consistency before removing the old column, and integrate the 'test on production-size data' advice into the step sequence rather than leaving it in a bullet list.

Split depth content into one-level-deep reference files (e.g., references/indexing.md, references/migrations.md, references/optimization.md) and keep SKILL.md as a concise overview with clearly signaled links.

Trim examples of fundamentals Claude already knows — the 1NF/2NF/3NF comments and basic PRIMARY KEY / UNIQUE constraint DDL — to free tokens for higher-value guidance like index selection heuristics.

Dimension	Reasoning	Score
Conciseness	The body is dominated by tight, comment-annotated SQL with almost no prose padding, assuming Claude's competence throughout. It is not 5 because sections like the Constraints examples and the 1NF/2NF/3NF comments restate fundamentals Claude already knows and could be trimmed.	4 / 5
Actionability	Every section is copy-paste-ready executable SQL: CREATE INDEX variants, pg_stat diagnostic queries, a transactional migration template, EXPLAIN (ANALYZE, BUFFERS), keyset pagination, and constraint DDL covering the common cases. Nothing is pseudocode, and the one non-code block (zero-downtime steps) is appropriately procedural.	5 / 5
Workflow Clarity	The zero-downtime migration sequence ("1. Add new column (nullable) ... 5. Remove old column") and the batch-backfill template are clearly sequenced but have no validation checkpoints between steps — no verify-backfill, no confirm dual-write consistency before dropping the old column. Per the rubric, database/batch operations missing feedback loops cap workflow_clarity at 3, so it cannot score 4 despite the otherwise clear ordering.	3 / 5
Progressive Disclosure	There are no bundle files at all — no references/, scripts/, or assets/ — and ~170 lines of material spanning schema design, indexing, migrations, optimization, and constraints all live inline in SKILL.md. Section headers give reasonable structure, matching anchor 3 rather than 2, but content that clearly belongs in separate reference files (e.g., index analysis, query optimization) is not split out, and it is too long to qualify for the under-50-line single-file exception.	3 / 5
	Total	15 / 20 Passed

Description

75%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A well-constructed description that explicitly covers what the skill does and when to use it, with concrete domain-specific trigger phrases. It sits solidly at anchor 4 on every dimension: clear and specific, but lacking the synonym breadth and distinct trigger contexts that would push it to 5.

Dimension	Reasoning	Score
Specificity	"Database schema design, optimization, and migration patterns" plus "designing schemas, writing migrations, or optimizing queries" lists several specific actions across named database families. It falls short of 5 because coverage has gaps — indexing, EXPLAIN analysis, and constraint work implied by the body are not named — but exceeds 3 since more than 1-2 concrete actions are given.	4 / 5
Completeness	Both halves are explicit: the "what" ("Database schema design, optimization, and migration patterns for PostgreSQL, MySQL, and NoSQL databases") and the "when" ("Use for designing schemas, writing migrations, or optimizing queries"). It matches anchor 4 rather than 5 because the when-clause restates the what verbatim without adding distinct trigger situations a user would voice (e.g., "when the user complains about slow queries or needs to add an index").	4 / 5
Trigger Term Quality	Natural user phrases like "designing schemas", "writing migrations", "optimizing queries", "PostgreSQL", and "MySQL" are present. Not 5 because common variations are missing ("index", "slow queries", "Postgres", "database migration" as distinct trigger contexts); not 3 because keyword coverage goes well beyond a single generic term.	4 / 5
Distinctiveness Conflict Risk	Naming PostgreSQL, MySQL, and NoSQL carves out a clear database-design niche that is mostly distinct. Not 5 because the broad "optimization" scope overlaps with general SQL-tuning or ORM skills; not 3 because the explicit DB-engine triggers make confusion unlikely.	4 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: MoizIbnYousaf/ai-agent-skills
Path: skills/database-design/SKILL.md
Commit: 6d95c78

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

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.