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

75%

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 ./database/sqlalchemy-starter/SKILL.md

Quality

Content

76%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 with complete, executable code and a clear project structure, and it is well organized into navigable sections. The chief gaps are redundant command blocks across sections and the absence of validation checkpoints in the destructive migration workflow.

Suggestions

Add explicit validation checkpoints to the migration workflow (e.g., 'Review the autogenerate output before upgrading', 'After upgrade, run alembic current to verify', 'Test alembic downgrade -1 in a staging DB before relying on it').

De-duplicate the Alembic commands: keep the init/install steps in 'Scaffold Command' and 'Database Initialization', and reserve 'Common Commands' for the broader reference set without re-listing the same upgrade/downgrade commands.

Drop the blockquote under the title since it repeats the frontmatter description verbatim, saving tokens.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean executable code with minimal prose over-explanation, but the top blockquote duplicates the frontmatter description and several Alembic commands (init, upgrade, downgrade, autogenerate) are repeated across 'Scaffold Command', 'Database Initialization', and 'Common Commands' sections.	4 / 5
Actionability	Provides fully executable, copy-paste-ready code for config, database setup, models, repositories, and the Alembic async env, plus concrete shell commands that cover the common scaffolding cases.	5 / 5
Workflow Clarity	The migration workflow has a clear sequence (init → autogenerate → upgrade → downgrade) but no validation checkpoints — there is no 'review the generated migration', 'verify with alembic current', or rollback-test feedback loop — and destructive/batch migration work without validation is capped at 3 per the rubric.	3 / 5
Progressive Disclosure	Well-organized into clear single-level sections (Prerequisites, Scaffold, Structure, Conventions, Patterns, Commands, Integration Notes) with no nested references and easy header-based navigation, though full model and repository definitions are inlined rather than split into reference files.	4 / 5
	Total	16 / 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.

The description is specific and distinct, naming concrete capabilities rather than vague fluff, and uses appropriate third-person voice. Its main weakness is the absence of an explicit 'Use when…' trigger clause, which limits its completeness score.

Suggestions

Add an explicit 'Use when…' clause naming natural trigger phrases (e.g., 'Use when scaffolding a new SQLAlchemy 2.0 project, setting up Alembic migrations, or adding async sessions and the repository pattern to an existing app').

Include a couple of synonym/extension terms users might say (e.g., 'ORM', 'migrations', '.py') to broaden trigger-term coverage.

Consider mentioning the supported databases (PostgreSQL, MySQL, SQLite) in the description to further sharpen distinctiveness.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete, specific artifacts — 'declarative models (mapped_column), Alembic migrations, async sessions, repository pattern, relationships, and engine configuration' — giving comprehensive coverage of what the scaffold produces.	5 / 5
Completeness	It clearly answers 'what' (scaffold a SQLAlchemy project with the listed features) but provides no 'Use when…' trigger clause, and the guideline caps completeness at 3 when explicit trigger guidance is missing.	3 / 5
Trigger Term Quality	Strong natural technical keywords ('SQLAlchemy 2.0+', 'Alembic migrations', 'async sessions', 'repository pattern') that users would actually say, but lacks synonyms and file-extension variants, so a few natural terms are missing.	4 / 5
Distinctiveness Conflict Risk	A clearly defined niche (SQLAlchemy 2.0+ scaffolding with async/Alembic/repository pattern) with distinct triggers and minimal risk of firing for an unrelated skill.	5 / 5
	Total	17 / 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: achreftlili/deep-dev-skills
Path: database/sqlalchemy-starter/SKILL.md
Commit: 181fcbc

Reviewed: 1 day 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.