erd

Files (5)

• SKILL.md
• openai.yaml · agents/
• example.json
• generate.ts
• template.html

SKILL.md (first lines)

# Interactive ERD

1. Gather every table, column, primary key and foreign key from the available source: a live database's `information_schema` through authorized read-only access, migration or schema code, DDL, or a described model. Group tables by business domain. Represent inferred relationships as soft links. Collection is complete when every source foreign key has its referenced table and column.
2. Write a JSON file outside the repository being diagrammed, unless the user names a location. Use [example.json](example.json) as the format reference. Set the required `title` to what the diagram maps and add an optional `subtitle`. Each table has `id`, `group`, `caption` and `columns`. Tables and columns accept optional `status` values of `"existing"` (the default), `"new"` or `"changed"`; new and changed elements show a badge. Every new or changed element requires `reuse: { checked: string, why: string }` naming the existing primitive checked first and why it cannot carry the need; both strings must be nonblank, appear in the details panel, and are rejected on existing elements. `checked` names symbols as `path/to/file.ext:SymbolName`, comma-separated. `why` must remain unique after removing the element's id, caption and column name, lowercasing and collapsing whitespace. Optional top-level `reuseRoot`, an absolute repo path, also verifies each file is inside it and contains the named symbol. Each column has `name`, `type` and optional `pk`, `fk` and `unique` booleans. A column can have several key flags. `unique` displays a UQ badge without marking the column as a PK. Copy the exact declared type, including sizes, precision, unsigned modifiers and enum or set literals. For MySQL, read `information_schema.COLUMNS.COLUMN_TYPE`, rather than `DATA_TYPE`; use the engine's equivalent elsewhere. Preserve types such as `int unsigned`, `tinyint(1)`, `varchar(255)`, `decimal(10,2)`, `enum('a','b')`, `int4` and `jsonb`. Mark an unknown type explicitly, such as `int?`. Enum and set values appear in the details panel; their rows show the type name and count. For values enforced in code, add a `values` array of strings; the panel marks these "Values set in code". Each link has `fk` and `pk` endpoints with `table` and `column`, plus an optional `soft` boolean. Emit one link per column pair in a composite key. Include referenced tables, mark the FK column with `fk`, and mark the referenced column with `pk` or `unique`. The `pk` endpoint names the referenced key, which can be primary or unique. Preserve full names and captions.
3. Run `node <skill-directory>/generate.ts schema.json out.html` with Node 24 or newer. Resolve every validation error and rerun until the generator succeeds. The output embeds the schema and loads ELK from a CDN, so opening it requires internet access.
4. Open the generated HTML in the available browser. Scripted checks can wait for `#stage` to have `data-state="ready"`; `data-state="error"` puts the diagnostic in `#err`. Check every source foreign key against a rendered line from its FK row to its referenced PK or UQ row, with the arrowhead at that key. Check dashed soft links and line, row and table-header hover. A header highlights all attached links and connected tables. Verify exact column types and allowed values in the details panel. Details never cover what is in focus: the selected item and every highlighted table and line. The panel chooses a clear corner or pans the view just enough; narrow screens use a bottom dock. Click locks a selection and expands its lists; clicking it again, empty space or Escape unlocks. Clicking "+N more" expands a folded list and locks the panel. Check Fit, pan, zoom, long names, light and dark themes, and reduced motion. When a check fails, fix the JSON or generator and rerun step 3. Completion requires every source foreign key to have a rendered line and the page to open without a layout error. Return a link to the HTML file.

From Camgineer/skills, Apache-2.0.

More from Camgineer/skills