CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

sqlalchemy-starter

Scaffold a SQLAlchemy 2.0+ project with Python, declarative models (mapped_column), Alembic migrations, async sessions, repository pattern, relationships, and engine configuration.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./database/sqlalchemy-starter/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

65%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.

The content is highly actionable and lean, with complete executable code for the core stack, held back by a dangling Profile model reference, no migration-review/verification checkpoints in the database workflow, and a monolithic single-file layout where model and repository templates could live in reference files.

Suggestions

Add a validation checkpoint to the migration workflow: review the autogenerated migration file before running "alembic upgrade head", and verify with "alembic current" after upgrading.

Define the missing Profile model (or remove the User.profile relationship) so the model code imports cleanly as written.

Deduplicate the alembic commands repeated across Scaffold Command, Database Initialization, and Common Commands into one section, and consider moving full model/repository templates into a references/ file to slim SKILL.md.

DimensionReasoningScore

Conciseness

The body is dense and free of conceptual over-explanation — it states conventions ("Use SQLAlchemy 2.0 style: mapped_column()") rather than teaching basics Claude already knows. However, alembic commands ("alembic revision --autogenerate", "alembic upgrade head", "alembic downgrade -1", "alembic init alembic") are repeated nearly verbatim across the Scaffold Command, Database Initialization, and Common Commands sections, which is trimmable duplication. This lands on the score-4 anchor (efficient with minor trimming possible) rather than 5.

4 / 5

Actionability

The guidance is almost entirely copy-paste-ready: complete settings, engine/session setup, three model files with relationships, repository functions with pagination, and a full async alembic env.py. The main gap is that User declares "profile: Mapped[Profile | None] = relationship(...)" but no Profile model is defined anywhere in the skill or the project structure, so the code as written fails on import — a concrete incompleteness that keeps it at the score-4 anchor rather than 5.

4 / 5

Workflow Clarity

The multi-step sequence is present and ordered (install deps → alembic init → edit env.py → define models → autogenerate → upgrade), but there are no validation checkpoints: no step to review the autogenerated migration before applying it, and no verification after upgrade (e.g. checking "alembic current"). Per the rubric's scoring notes, database operations without feedback loops cap workflow_clarity at 3 — this matches the anchor for steps listed with validation gaps.

3 / 5

Progressive Disclosure

The body has good structure — clear sections, a project-structure map, and labeled code blocks — but ~370 lines of full template code (three model files, repositories, env.py) are entirely inlined in SKILL.md with no references/, scripts/, or assets/ files at all. Content that clearly belongs in separate reference files is inline, matching the score-3 anchor; it is not 4 because there are no well-signaled one-level-deep references to offload the bulk.

3 / 5

Total

14

/

20

Passed

Description

71%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.

The description is strong on specificity and trigger terms, clearly naming the SQLAlchemy 2.0 stack and its concrete components. Its main weakness is the absence of any "Use when..." trigger guidance, which caps completeness, plus missing common synonyms like "ORM" or specific database names that users might naturally say.

Suggestions

Add an explicit trigger clause, e.g. "Use when starting a new SQLAlchemy project, adding ORM models or Alembic migrations, or setting up an async database layer in Python."

Include natural synonyms and ecosystem terms users would say — "ORM", "database models", "PostgreSQL/MySQL/SQLite" — to improve trigger-term coverage.

Tighten distinctiveness by leading with the technology ("SQLAlchemy 2.0+ project scaffolding...") rather than the generic "Scaffold a ... project with Python" framing.

DimensionReasoningScore

Specificity

The description lists multiple specific concrete capabilities — "declarative models (mapped_column)", "Alembic migrations", "async sessions", "repository pattern", "relationships, and engine configuration" — giving comprehensive coverage of what the skill scaffolds. It fits the score-5 anchor rather than 4 because there are no notable gaps in capability coverage.

5 / 5

Completeness

The description has a clear, specific "what" (scaffolds a SQLAlchemy 2.0+ project with enumerated components) but contains no "Use when..." clause or any equivalent trigger guidance — the "when" is entirely absent, not even weakly implied. Per the judging guidelines, a missing 'Use when' clause caps completeness at 3.

3 / 5

Trigger Term Quality

Good keyword coverage with natural terms users would say ("SQLAlchemy", "Alembic", "migrations", "models", "sessions"), but common variations and synonyms are missing — no "ORM", "database schema", "PostgreSQL/MySQL/SQLite", or "SQL" phrasing. This matches the anchor for good coverage with a few natural terms missing rather than the comprehensive score-5 anchor.

4 / 5

Distinctiveness Conflict Risk

The description carves out a clear niche (SQLAlchemy 2.0+ scaffolding) with technology-specific triggers like "mapped_column" and "Alembic", making it mostly distinct from other skills. However, the generic "Scaffold a ... project with Python" framing creates minor overlap risk with general project-scaffolding or other database/ORM skills, matching the score-4 anchor rather than the minimal-conflict score-5 anchor.

4 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

achreftlili/deep-dev-skills

Path

database/sqlalchemy-starter/SKILL.md

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.