CtrlK
BlogDocsLog inGet started
Tessl Logo

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".

53

Quality

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

Quality

Content

65%

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, packed with executable introspection SQL and a useful error-handling matrix, but it lacks validation checkpoints in the workflow and fails to surface the bundled scripts, leaving inline content that overlaps with existing bundle files.

Suggestions

Add validation checkpoints to the workflow, e.g. after connecting verify access to information_schema/pg_catalog, and after each extraction confirm non-empty results before generating Markdown.

Replace or supplement the inline ERD/statistics steps with references to the bundled scripts (e.g. 'Run scripts/erd_generator.py --format all for diagrams; see scripts/README.md'), so SKILL.md points to rather than duplicates the bundle.

Trim the narrative Examples and redundant Output section to keep the body lean.

DimensionReasoningScore

Conciseness

The body is mostly dense and efficient (concrete SQL queries, tight prerequisites), but the narrative Examples section and the Output section—which restates what the instructions already produce—could be tightened to earn a 3.

2 / 3

Actionability

It provides fully executable, copy-paste-ready PostgreSQL and MySQL introspection queries for every step (tables, columns, constraints, foreign keys, indexes, views, routines, statistics), with specific column lists and ordering.

3 / 3

Workflow Clarity

Steps are clearly numbered 1–10, but for a database batch operation there are no validation/verification checkpoints (e.g. confirm connection, verify non-empty results) and no validate→fix→retry feedback loop, which caps workflow clarity at 2 per the database-operations guideline.

2 / 3

Progressive Disclosure

The body is well-sectioned, but it never references the bundled scripts (init_db_docs.py, validate_config.py, erd_generator.py) that already implement related work such as ERD generation; content that could live in those scripts is duplicated inline, so references are neither signaled nor appropriately split.

2 / 3

Total

9

/

12

Passed

Description

57%

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 both what and when with explicit triggers, but is weakened by vague fluff ('comprehensive guidance and automation'), a broken opening ('Process use when'), second-person voice, and a generic lead trigger that risks overlap with other documentation skills.

Suggestions

Replace fluff ('comprehensive guidance and automation') with concrete actions the skill performs, e.g. 'Extracts table structures, columns, relationships, indexes, constraints, views, and stored procedures into Markdown documentation.'

Rewrite in third person and fix the opening fragment, e.g. 'Generates database documentation by introspecting live PostgreSQL or MySQL schemas. Use when the user asks to generate docs, document a schema, or create database documentation.'

Broaden trigger coverage with common variations like 'schema documentation', 'db docs', and 'data dictionary'.

DimensionReasoningScore

Specificity

The description names the domain ('database documentation') and a single action ('automated documentation generation') but pads with fluff ('comprehensive guidance and automation') rather than listing concrete actions; the second-person phrasing 'when you need to work with' further reduces specificity per the third-person-voice guideline.

1 / 3

Completeness

It explicitly answers both what ('automated documentation generation') and when ('use when you need to work with database documentation' plus an explicit trigger-phrase list), satisfying the explicit-trigger requirement.

3 / 3

Trigger Term Quality

It lists natural trigger phrases ('generate docs', 'document schema', 'create database documentation') a user might say, but coverage is moderate and misses common variations like 'schema documentation', 'db docs', or 'database schema'.

2 / 3

Distinctiveness Conflict Risk

The database-documentation niche is fairly clear, but the lead trigger 'generate docs' is generic enough to overlap with general documentation- or code-doc-generation skills.

2 / 3

Total

8

/

12

Passed

Validation

87%

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

Validation14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

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