Claude Code

Install one skill and Claude Code embeds the Patchrooms widget whenever it generates a UI artifact for review — reviewers drop comments straight onto the preview, and Claude Code gets clean, structured feedback to patch from.

Prerequisites

• Claude Code with skills enabled (.claude/skills/ in your project, or your user skills directory).
• A project key (pr_…) from your Patchrooms dashboard.

Public vs secret keys

A pr_… project key is public and safe in client code. A secret pr_sk_… key must never be embedded in a generated artifact or skill.

Install the skill

Place the skill so Claude Code can discover it:

• Directoryyour-project/

  • Directory.claude/

    • Directoryskills/

      • Directorypatchrooms-artifact-review/

        • SKILL.md

Paste this into SKILL.md:

---
name: patchrooms-artifact-review
description: Use when generating an HTML, React, or preview artifact that a human will review — embed the Patchrooms SDK so reviewers can drop comments straight onto the preview and feedback comes back as structured, agent-ready context. Triggers when you build a UI, page, component, or app preview for someone to review.
---

# Patchrooms: make the artifacts you generate reviewable

When you generate a UI artifact (HTML page, React app, preview build) a human
will review, embed Patchrooms. It turns the preview into a review room: the
reviewer clicks any element to comment in place, and you get clean, structured
feedback instead of vague chat. Loop: generate → review in place → patch → ship.

Apply when the artifact is meant to be looked at and commented on. Skip
backend-only code, library internals, or artifacts with no visual surface.

## 1. Embed the SDK

Add just before `</body>`. The UMD build attaches `window.Patchrooms`.

```html
<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>
  Patchrooms.init({
    projectKey: 'pr_xxx',  // <-- the user's project key
    mode: 'artifact-review',
    artifact: {
      id: 'my-app',        // stable room key — reuse across regenerations
      title: 'Checkout flow',
      tool: 'claude-code',
      goal: 'What this artifact is supposed to do',
    },
  });
</script>
```

For React, render the two `<script>` tags in `index.html` (not inside a
component) so `window.Patchrooms` exists before app code runs.

## 2. Project key

`projectKey` (`pr_…`) is required — get it from the user or their Patchrooms
dashboard settings and pass it in `init()`. Reports land in the dashboard and
stream live; you can read them over MCP. `projectKey` is not a `data-*`
attribute.

## 3. Stable anchors

Put `data-patchroom-id` on the key UI elements (primary buttons, headers, nav,
hero, form fields, cards) using semantic, stable ids so comments survive
regeneration. A handful of meaningful anchors per screen, not every node.

```html
<button data-patchroom-id="checkout-submit">Pay now</button>
```

## 4. Never embed secrets or PII

No API keys, tokens, secrets, or real user data in the page, `artifact.meta`, or
`extra`. `pr_…` is public and safe; a secret `pr_sk_…` key must never appear in
client code.

## 5. Tell the user how to review

After shipping, print a short note: open the preview, click any element to
comment (text / screenshot / element selection / voice) — the report lands in
the Patchrooms dashboard, where "Copy as prompt" copies it as Markdown to paste
back so you can patch.

Where it goes

The skill lives in your project’s .claude/skills/ (or your user skills directory). Claude Code surfaces it by its description when you ask it to build a reviewable UI.

The install snippet Claude Code emits

The skill above uses the programmatic snippet so it can attach artifact metadata. If you don’t need that, the lowest-friction install is the per-project loader — the key lives in the URL and the server inlines your config, so the widget auto-initializes:

<script src="https://room.patchrooms.com/v1/patchrooms/pr_xxx.js"></script>

Programmatic alternative (when the skill should attach mode/artifact):

<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>
  Patchrooms.init({ projectKey: 'pr_xxx', mode: 'artifact-review', artifact: { id: 'my-app', tool: 'claude-code' } });
</script>

Verify it works

1. Ask Claude Code to build a UI page or component preview.

2. Confirm it emitted the <script> tags and the Patchrooms launcher appears in the preview.

3. Click an element to comment. With a project key, the report should stream into your dashboard.

Your first feedback

Open the preview, click an anchored element, and leave a comment like:

The form validation message is hard to read — bump the contrast and move it under the field.

Add a screenshot, element selection, or voice note to the same thread. The report is in your dashboard — hit Copy as prompt and paste the Markdown back to Claude Code to patch, or let Claude Code pull it over MCP.

Read feedback back: triage & fix

The skill above is the write side — making artifacts reviewable. The other direction is reading those reports back so Claude Code patches the code. Connect Claude Code to the cloud project over MCP with a secret read key (pr_sk_…):

claude mcp add --transport http patchrooms https://room.patchrooms.com/mcp \
  --header "Authorization: Bearer $PATCHROOMS_API_KEY" --scope project

Then ask Claude Code to list_reports, get_report, and set_status — it reads the feedback filed on your running app and fixes the right code path, closing the generate → review → patch loop. Full setup, scopes, and a no-MCP curl fallback: see the MCP reference.

Keep the secret key out of the app

The pr_sk_… key used here is for reading on your machine — keep it in an env var, never in the artifact, the skill, or a commit. The widget only ever uses the public pr_… key.

API the skill relies on

Real init options (packages/sdk-web/src/types.ts):

• mode: 'default' | 'artifact-review'. Use 'artifact-review'.
• artifact: { id, title?, tool?, source?, goal?, constraints?: string[], url?, meta?: Record<string,string> }. id is required and is the room key.
• Script data-* reads: data-project-key, data-mode, data-artifact-id, data-source.

Troubleshooting

Symptom	Fix
Claude Code doesn’t apply the skill	Confirm SKILL.md is under .claude/skills/<name>/ and ask explicitly for a reviewable UI.
No launcher in the preview	Check the <script> is in the rendered HTML. In React, both tags must be in index.html.
Console: [Patchrooms] unknown project key	The pr_… key in the loader URL is wrong — copy it from the dashboard.
Comments drift after regeneration	Use stable data-patchroom-id anchors and reuse the same ids.

Not yet available

@patchrooms/react (<Patchrooms … />) is planned — no such package yet; always embed via <script> + init(). MCP today supports list_reports / get_report / set_status; extended write tools (create_room, register_artifact, export_feedback_as_prompt, …) are planned.