database-documentation-gen

Process use when you need to work with database documentation. This skill provides automated documentation generation with comprehensive guidance and automation. Trigger with phrases like "generate docs", "document schema", or "create database documentation".

Quality

62%

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 ./plugins/database/database-documentation-gen/skills/database-documentation-gen/SKILL.md

Quality

Content

50%Weight 40%Scale 1-3

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

The content is structured and grounded in real, executable SQL plus a genuine scripts bundle, but it underuses that bundle: SKILL.md never references the provided scripts in its workflow, relies on long inline queries, and lacks the validation/feedback checkpoints the rubric expects for database batch operations. This lands each dimension at 2 — competent but not exemplary.

Suggestions

Wire the bundled scripts into the workflow (e.g. step 1: run init_db_docs.py to scaffold; step N: run erd_generator.py for diagrams) instead of leaving them unmentioned, so the SKILL.md acts as an overview pointing one level deep.

Add explicit validation checkpoints between phases — verify DB connectivity, confirm the table inventory is non-empty before per-table extraction, and re-run generation after schema changes.

Move the long inline introspection SQL into a references file or the scripts and keep SKILL.md as concise step summaries, improving both conciseness and progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean SQL commands and tight step lists, but it repeats near-identical introspection queries inline (long single-line SQL) that would be cleaner as bundled scripts, and includes some explanatory filler ("Document each view with its purpose, source tables, and any filtering logic") that pads without adding executable value.	2 / 3
Actionability	Concrete SQL queries are provided for most steps and bundled scripts exist (init_db_docs.py, validate_config.py, erd_generator.py), but the SKILL.md never references or invokes those scripts in its workflow, and several steps give only a template ("target_table") rather than executable, copy-paste-ready guidance for a real run.	2 / 3
Workflow Clarity	The ten steps are clearly sequenced, but for a database introspection/batch-generation process there are no validation checkpoints (e.g. verify connection, confirm tables extracted before generating output, re-run on schema change); the rubric caps workflow clarity at 2 when feedback loops are missing for database/batch operations.	2 / 3
Progressive Disclosure	Sections are well-labeled (Overview, Prerequisites, Instructions, Output, Error Handling, Examples, Resources) and a real scripts bundle exists, but the body never signals those scripts to the reader — the long inline SQL could be offloaded to scripts/references, leaving the SKILL.md as a wall of queries rather than an overview pointing one level deep.	2 / 3
	Total	8 / 12 Passed

Description

75%Weight 40%Scale 1-3

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 answers both what the skill does and when to use it with explicit trigger phrases, giving it good completeness and distinctiveness. However, the prose is grammatically broken ("Process use when..."), padded with vague fluff ("comprehensive guidance and automation"), and names only one concrete action, capping specificity and trigger-term quality at 2.

Suggestions

Fix the opening grammar to a clean third-person verb phrase, e.g. "Generates database documentation by introspecting live PostgreSQL/MySQL schemas."

Replace the vague "comprehensive guidance and automation" with 2-3 concrete deliverables (e.g. "produces a Markdown data dictionary, ERD, and index catalog").

Expand trigger phrases to include natural variations like "schema docs", "data dictionary", and "DB documentation".

Dimension	Reasoning	Score
Specificity	It names the domain ("database documentation") and an action ("automated documentation generation"), but stops at one action plus generic fluff ("comprehensive guidance and automation") rather than listing multiple concrete actions like schema extraction, ERD, or data dictionary generation.	2 / 3
Completeness	It answers both what ("automated documentation generation") and when with an explicit trigger clause ("use when you need to work with database documentation... Trigger with phrases like..."), satisfying the what-and-when requirement.	3 / 3
Trigger Term Quality	It offers several plausible natural phrases ("generate docs", "document schema", "create database documentation"), but the phrasing is awkwardly broken and it omits common variations users would say (e.g. "schema docs", "DB documentation", "data dictionary").	2 / 3
Distinctiveness Conflict Risk	The database-documentation niche and its specific trigger phrases ("document schema", "create database documentation") are distinct enough that it is unlikely to fire for unrelated skills.	3 / 3
	Total	10 / 12 Passed

Validation

87%

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 — 14 / 16 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	14 / 16 Passed

Repository: jeremylongshore/claude-code-plugins-plus-skills
Path: plugins/database/database-documentation-gen/skills/database-documentation-gen/SKILL.md
Commit: 399d94c

Reviewed: 3 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.