BuilderIO/packages/pinpoint/.agents/skills/pinpoint

Pinpoint — Visual Feedback Tool

You are an agent with access to Pinpoint, a visual feedback and annotation tool. Users annotate UI elements on web pages and send structured feedback to you.

Reading Annotations

Pins are stored as JSON files in data/pins/{uuid}.json:

{
  "id": "uuid",
  "pageUrl": "/dashboard",
  "comment": "This button color is wrong",
  "element": {
    "tagName": "button",
    "selector": ".sidebar button.primary",
    "classNames": ["primary", "btn"]
  },
  "framework": {
    "framework": "react",
    "componentPath": "<Sidebar> <ActionButton>",
    "sourceFile": "src/components/Sidebar.tsx:42"
  },
  "status": { "state": "open", "changedBy": "user" }
}

Key fields:

• sourceFile — exact file and line number to edit
• componentPath — React/Vue component hierarchy
• selector — CSS selector for the DOM element
• comment — what the user wants changed

Actions

Run with pnpm action <name>:

| Action | Purpose | Key Args | |--------|---------|----------| | get-pins | List pins | --pageUrl, --status | | create-pin | Create a pin | --pageUrl, --selector, --comment | | resolve-pin | Mark as resolved | --id, --message | | update-pin | Update a pin | --id, --comment, --status | | delete-pin | Remove a pin | --id | | list-sessions | List pages with pins | (none) |

Workflow

1. User annotates elements in the browser
2. Read pins: pnpm action get-pins --status open
3. Use sourceFile to locate the code and make the requested changes
4. Mark resolved: pnpm action resolve-pin --id <uuid>

Tips

• Always check sourceFile first — it points directly to the code to edit
• Use get-pins --status open to see only unresolved pins
• Resolve pins after fixing them so the user gets visual confirmation
• The componentPath helps you understand the component hierarchy when sourceFile is not available
• Multiple pins on the same page often relate to each other — read them all before starting fixes

Adding Pinpoint to a New App

If the repository does not have Pinpoint set up:

1. pnpm add @agent-native/pinpoint
2. npx @agent-native/pinpoint init — copies scripts and skill to your project
3. Add <Pinpoint /> component to the root React component:

   import { Pinpoint } from "@agent-native/pinpoint/react";
   <Pinpoint author="User" endpoint="/api/pins" autoSubmit />
   

4. Add server middleware in the Express setup:

   import { pagePinRoutes } from "@agent-native/pinpoint/server";
   app.use("/api/pins", pagePinRoutes());