How to use the Record Prisma Gotchas agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent when to apply a specific workflow and how to carry it out. This skill's SKILL.md is the only file listed for it.

The skill defines a gotcha as friction a consumer of Prisma 8, Prisma Compute, or Prisma Postgres would also feel: a surprising failure mode, undocumented behaviour, a workaround you wrote, or a mismatch between your mental model and the CLI, runtime, or docs. When the trigger fires, the agent appends a short entry to a local gotchas log, files a Triage-state ticket in the matching Linear project, and cross-links the two.

• Prisma 8 ORM issues go to the pn-gotchas Linear project.
• Prisma Compute issues go to the compute-gotchas Linear project.
• Prisma Postgres issues go to the ppg-gotchas Linear project.
• Bugs in code your own team maintains are not gotchas. The skill says those are normal product-backlog bugs.

How do you install the record-gotchas skill?

Download the ZIP from this page and unzip it. The skill folder should contain SKILL.md. Then place the folder in one of these locations, depending on whether you want it for all projects or one project.

To make it available across your projects, unzip it into ~/.claude/skills/. To make it available only inside one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal (all projects): ~/.claude/skills/
• Single project: <your-project>/.claude/skills/
• Claude apps: Settings → Capabilities → Skills

Set up the Linear MCP plugin before you use it

The skill requires the Linear MCP plugin to be installed and authenticated, and you need access to the Prisma Linear gotchas projects (pn-gotchas, compute-gotchas, ppg-gotchas). Without the plugin, the skill halts and asks you to install it. It does not write the local entry without the ticket, because the two halves are meant to exist together.

In Claude Code the plugin is referenced as plugin:linear:linear. The skill also links to the Linear plugin for Cursor.

• Install and authenticate the Linear MCP plugin.
• Confirm you have access to pn-gotchas, compute-gotchas and ppg-gotchas.
• The skill runs no scripts, but it does use the network to reach Linear.

How do you trigger the skill with natural requests?

The skill is written to fire on its own. It applies when the agent writes a workaround, hits a surprising failure, or finds undocumented behaviour while using one of the three products from the outside. Examples include building a new extension against the authoring API, working in an example app and hitting a CLI rough edge, reproducing a customer report, or running an integration test against the public CLI or runtime.

You do not need a special command. Describe the problem in plain terms as you work. The skill says to capture ambiguous cases rather than skip them, so if you are unsure whether something counts, let the agent record it.

• Working on an extension: the agent reports that a CLI check passed but the output did not match the docs.
• Reproducing a customer bug: the agent writes a workaround to get the repro running and records it.
• Example app: a runtime error with no documented cause is found and noted.

What happens when the skill fires?

The skill behaves differently depending on the repo you are in. In a Prisma product-team repo such as prisma-8-ws, it surfaces the gotcha and offers three paths: capture it as a gotcha, file a normal bug, or note it and move on. In any other repo, such as a pet project, hackathon entry, or customer codebase, it captures silently to the project's gotchas log and files a Triage-state ticket, without asking you.

For the local log, the skill uses docs/prisma-8-gotchas.md, docs/compute-gotchas.md, or docs/ppg-gotchas.md if one exists. Otherwise it appends to gotchas.md at the repo root and creates that file if it is missing.

• Product-team repo: choose capture-as-gotcha, file-a-normal-bug, or note-and-move-on.
• Other repos: silent capture to the local log plus a Triage ticket.
• Tickets are Triage status with no priority or labels, under the matching gotchas project.

Safety and what to check before you use it

The skill runs no scripts. It does use the network, because filing the ticket requires Linear access. Before you install it, check that you are comfortable with the agent writing to a Prisma Linear project under your authenticated account.

The skill is scoped to the three Prisma products. If a gotcha involves a fourth tool such as Bun or Next.js, the skill says to record it on the Prisma side and link the third-party tracker, rather than filing it there.

• No scripts are run.
• Network access is used to reach Linear.
• Gotchas are not for bugs in code your team owns.