generating-database-documentation
This skill enables Claude to automatically generate comprehensive documentation for existing database schemas using the database-documentation-gen plugin. It is triggered when the user requests database documentation, ERD diagrams, or a data dictionary. The plugin supports multiple database engines and generates documentation that includes ERD diagrams, table relationships, column descriptions, indexes, triggers, stored procedures, and interactive HTML documentation. Use this skill when you need to document existing database schemas for team onboarding, architectural reviews, or data governance purposes. The trigger terms include "database documentation", "ERD diagram", "data dictionary", and `/db-docs`.
68
53%
Does it follow best practices?
Impact
98%
1.24xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./backups/skills-batch-20251204-000554/plugins/database/database-documentation-gen/skills/database-documentation-gen/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly communicates what the skill does, when to use it, and includes specific trigger terms. It lists concrete outputs (ERD diagrams, table relationships, indexes, etc.), provides explicit use-case scenarios, and names the underlying plugin. The description is well-structured and distinctive enough to avoid conflicts with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: generate ERD diagrams, table relationships, column descriptions, indexes, triggers, stored procedures, and interactive HTML documentation. Very detailed about what the skill produces. | 3 / 3 |
Completeness | Clearly answers both 'what' (generate comprehensive documentation including ERDs, table relationships, column descriptions, etc.) and 'when' (explicit 'Use this skill when...' clause with specific scenarios and trigger terms listed). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'database documentation', 'ERD diagram', 'data dictionary', '/db-docs', plus contextual terms like 'team onboarding', 'architectural reviews', 'data governance'. Good coverage of natural trigger terms. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly occupies a distinct niche around database schema documentation generation. The specific mention of ERD diagrams, data dictionaries, the plugin name 'database-documentation-gen', and the slash command '/db-docs' make it unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
7%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill content is largely descriptive rather than instructive. It explains what the plugin does conceptually but provides no concrete commands, configuration examples, connection string formats, or plugin invocation syntax that Claude could actually use. The content reads more like a marketing overview than an actionable skill definition.
Suggestions
Add concrete plugin invocation syntax with actual commands, e.g., `/db-docs --engine postgres --connection-string <uri> --output html`
Replace the abstract examples with executable examples showing specific commands, expected inputs (connection strings, credentials format), and expected output file paths/formats
Add validation steps: how to verify the connection succeeded, how to check if generated documentation is complete, and error recovery for common failures (auth errors, missing tables)
Remove the 'How It Works', 'When to Use This Skill', and 'Integration' sections as they explain concepts Claude already knows and add no actionable value
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is verbose and explains concepts Claude already knows (what ERD diagrams are, what documentation includes, when to use it). The 'How It Works' section describes obvious plugin behavior rather than providing actionable instructions. The 'When to Use This Skill' section repeats information from the description. Much of this content is padding. | 1 / 3 |
Actionability | There are no concrete commands, executable code, configuration examples, or specific plugin invocation syntax. The examples describe what the skill 'will do' in abstract terms rather than showing actual commands, connection strings, or plugin parameters. Claude would not know how to actually invoke the database-documentation-gen plugin from this content. | 1 / 3 |
Workflow Clarity | The steps listed are abstract descriptions of plugin behavior ('Activate the plugin', 'Connect to the database') rather than actionable workflow steps. There are no validation checkpoints, no error handling, no feedback loops for connection failures or schema issues, and no concrete commands to execute at each step. | 1 / 3 |
Progressive Disclosure | The content is organized into logical sections with clear headers, which provides some structure. However, there are no references to supporting files, no bundle files exist, and the content is somewhat monolithic with sections that could be trimmed rather than split out. The organization is reasonable but the content itself doesn't warrant the number of sections. | 2 / 3 |
Total | 5 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 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 | 9 / 11 Passed | |
- Commit
a5f74ac
- 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.