---
name: prisma-parser
description: Parses Prisma ORM schema files (.prisma) into structured, human-readable documentation tables covering columns, data types, mandatory flags, primary keys, foreign keys, and recursive child-table relationships. Use whenever a Prisma schema is present and a readable view would help — explicitly requested or not. It can also call the db-query skill to query the database and clarify something inside the real database.
when_to_use: Use this skill any time a Prisma schema is present and a readable view would help.
allowed-tools: Read, Glob, Grep, Bash, Write, Edit
---

Converts Prisma ORM schema definitions into structured, readable documentation
tables — including columns, data types, constraints, primary keys, foreign keys,
and recursive child-table documentation.


| Situation | Trigger? |
|---|---|
| User says "show me the table" or "I want to see the table" | ✅ Yes |
| User says "use prisma parser" or names this skill | ✅ Yes |
| A `schema.prisma` file or the `prisma` folder is shared | ✅ Yes |
| User asks "what columns does X have?" or "is Y required?" | ✅ Yes |
| User asks about FK relationships or child tables | ✅ Yes |
| User is writing docs, a README, or a data dictionary | ✅ Yes |
| Agent step needs to understand table structure before generating queries | ✅ Yes |
| User says "walk me through this schema" or "help me understand this schema" | ✅ Yes |
| Schema is visible in context but user hasn't explicitly asked to parse it | ✅ Yes — parse proactively |
| User is only asking about business logic unrelated to schema structure | ❌ Skip |

**Default stance: if a Prisma schema is in scope and structure matters, run this skill.**

---

## Output Format

For **each model** (parent and all child models), produce two sections:

### Section 1 — Table Overview

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Table  : <Human-Readable Table Name>
Schema : <schema name>  (use "public" if not specified)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Columns
┌─────────────────────┬──────────────────┬───────────┬─────────────────────────────────────┐
│ Column Name         │ Data Type        │ Mandatory │ Description                         │
├─────────────────────┼──────────────────┼───────────┼─────────────────────────────────────┤
│ id                  │ uuid             │ Yes       │ Primary key, auto-generated UUID    │
│ created_at          │ timestamp        │ Yes       │ Record creation timestamp           │
│ ...                 │ ...              │ ...       │ ...                                 │
└─────────────────────┴──────────────────┴───────────┴─────────────────────────────────────┘
```

**Mandatory** = `Yes` if the column does not have `?` (is required) and is not auto-generated without a default.

**Description** — infer a short plain-English description from:
1. A comment directly above or beside the column definition (prefer this)
2. The column name itself (e.g. `createdAt` → "Record creation timestamp")
3. Type + constraint hints (e.g. `@relation(...)` → "Foreign key to ...")

---

### Section 2 — Keys & Relationships

```
Keys & Relationships
┌─────────────────────┬────────┬──────────────────────────────┐
│ Column Name         │ Type   │ Related To                   │
├─────────────────────┼────────┼──────────────────────────────┤
│ id                  │ PK     │ —                            │
│ invoiceId           │ FK     │ finance.PurchaseInvoice      │
│ productId           │ FK     │ inventory.Product            │
└─────────────────────┴────────┴──────────────────────────────┘
```

- **PK** — primary key column(s)
- **FK** — foreign key; "Related To" is `schema.model_name` (use `public` if no schema defined)
- **UQ** — unique constraint (if present)
- Show all PK, FK, and UQ entries. If a table has none, write `(no keys or relationships defined)`.

---

### Section 3 — Child Tables (Recursive)

After documenting a parent table, immediately document all child tables that
reference it via a foreign key, applying **the same two-section format** recursively.

Use a visual header to show nesting:

```
  ┗━ Child Table of: <Parent Table Name>
```

For grandchildren:
```
      ┗━ Child Table of: <Parent Table Name> › <Child Table Name>
```

Repeat until all descendants are documented.

---

## Parsing Rules

### Identifying Tables
Look for Prisma model definitions:
```prisma
model TableName { ... }
```

### Identifying Schema
Prisma usually defines schemas globally or via `@@schema("name")` if multi-schema is enabled.
If no schema object is used, default to `public`.

### Detecting Foreign Keys
Foreign keys appear as:
```prisma
vendor Vendor @relation(fields: [vendorId], references: [id])
```

### Detecting Primary Keys
```prisma
id String @id @default(uuid())
// or composite
@@id([col1, col2])
```

### Detecting Not Null / Mandatory
- Missing `?` → Mandatory: **Yes**
- Has `@default(...)` → Mandatory: **No** (auto-filled)

---

## Step-by-Step Workflow

1. **Receive input** — search for `.prisma` files, primarily `schema.prisma` in the `prisma/` folder.
2. **Identify all models** — list every `model` definition.
3. **Resolve schemas** — map each model to its schema name.
4. **Build relationship graph** — for each FK, record `(child_table, child_column) → (parent_table, parent_column)`.
5. **Determine root tables** — tables that are not referenced as FK targets by any other table (or explicitly identified by the user as the starting point).
6. **Output parent table** — Sections 1 and 2.
7. **Find direct children** — tables with FK pointing to the current table.
8. **Recurse** — output each child with its own Sections 1 and 2, then recurse into grandchildren.
9. **Continue** for all root tables not yet documented.
10. **Save Output** — Write the complete generated documentation into a Markdown file inside the `.claude/tmp/` folder (e.g., `.claude/tmp/schema-parser.md`).
11. **Ask User & Cleanup** — Ask the user if they want to open this file in their editor or markdown preview. Once they are finished reviewing it and confirm they are done, delete the generated file from the `.claude/tmp/` folder.
12. **Clarify via Database (Optional)** — If there's ambiguity or you need to clarify something inside the real database, call the `db-query` skill (e.g. using `node .claude/skills/db-query/scripts/index.js`) to verify table definitions or data directly.

---

## Clarifying against the Real Database

When using the `prisma-parser` skill, you may encounter situations where the schema file is ambiguous or lacks full context. You are empowered to **call the `db-query` skill** to query the database and clarify something inside the real database.

- **Use Case:** Validating exact column types, constraints, or existing data structures that aren't fully apparent from the Prisma code.
- **Action:** Execute raw SQL against the PostgreSQL database using `node .claude/skills/db-query/scripts/index.js`.
- **Note:** Always use appropriate queries (e.g., querying `information_schema` or limiting result sets) to inspect the live database safely.

---

## Edge Cases & Notes

- **Composite primary keys** — list all PK columns in the Keys table, each as a separate `PK` row.
- **Self-referencing tables** — (e.g. `parentId` referencing the same table) — show as FK pointing to itself.
- **Enums** — show as `enum(val1, val2, ...)` in Data Type column.
- **Comments in schema** — if `///` or `//` comments exist beside a column, use them verbatim as the Description.