explain
Explain a database schema, model, or a single finding in plain language, with a paradigm-aware diagram — what the tables/collections/keyspaces are, how they relate, and where the data lives. Read-only; teaches, does not change anything. Use when the user asks to explain, describe, walk through, draw, or diagram a schema, a data model, a relationship, or what a specific audit finding means.
How do I install this agent skill?
npx skills add https://github.com/hainrixz/claude-db --skill explainIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill analyzes database schemas and query plans using local scripts. It is generally safe but carries inherent risks from processing untrusted input files and using dynamic command execution for its diagram generation tool.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
/claude-db:explain
Plain-language description of a schema (or one finding), plus a paradigm-aware diagram. Read-only — explains, never edits or migrates.
$ARGUMENTS = <path|table|finding-id> [flags]. The target can be a schema/ORM/migration path, a single table/collection name, or a finding id from a prior audit.
What to do
- Detect the paradigm/engine (
scripts/detect-stack.mjs) and parse the model (scripts/parse-schema.mjs/parse-orm-python.py). - Give a plain-language description first — no jargon in the opening: what each entity holds, who owns what, and how the pieces connect, in the user's words ("a user has many orders; each order belongs to exactly one user").
- Render a paradigm-aware diagram (Mermaid) with
node scripts/gen-diagram.mjs --file <schema> [--paradigm relational|document|key-value|wide-column|graph]— paradigm-aware: ERD for relational, access-pattern map for document, key+GSI sketch for DynamoDB/KV, node/edge for graph:- Relational →
erDiagramwith tables, PKs/FKs, and cardinality. - Document → embedding/reference tree showing what is nested vs referenced.
- Key-value → access-pattern / key-design sketch (partition + sort key).
- Wide-column → table-per-query / partition-key layout.
- Vector → collection + metric/dimension + metadata filter fields.
- Time-series → hypertable / measurement + tags + retention.
- Graph → node-and-edge sketch with relationship types.
- Relational →
- Offer an expandable technical layer below the plain description: exact column types, index definitions, constraint names, on-delete behavior — for the reader who wants the precise DDL.
- If the target is a finding id, explain what it checks, which score/axis it affects (design | performance | both), why it matters, and how to reproduce it (
verification.reproduce).
Query / EXPLAIN-plan mode
Two additional inputs, both reusing the db-query-patterns (M13) reasoning:
--query "<SQL>"— given a raw SQL statement, explain in plain language why it would be slow and what fixes it: detect M13 shapes (SELECT *, structural N+1, OFFSET deep paging, non-SARGable predicates), then recommend the concrete index, keyset rewrite, or predicate change that lets an index be used. This is static reasoning over the query text — no live DB needed.- paste-an-EXPLAIN-plan — given a pasted
EXPLAIN/EXPLAIN ANALYZEplan, read the plan nodes (seq scans, sort/hash spills, row estimate vs actual, nested-loop blowups) and explain which step dominates and what index/rewrite removes it, again via the M13 reasoning. - If the user wants a live plan generated for them (running
EXPLAINagainst their database) rather than pasting one, mark the requestneeds_api/ Tier-2 and do not fabricate plan numbers — explain statically from the query text instead, or ask them to paste the plan.
Honesty
- Describe only what is actually in the model. Never invent columns, relationships, row counts, or latency. If a relationship is implied but not enforced (e.g. a logical FK with no constraint), say so explicitly.
- Respond in the user's language (EN/ES);
--langoverrides.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/hainrixz/claude-db/explain">View explain on skillZs</a>