Save this content to: .claude/skills/instruckt/SKILL.md

# Instruckt — Visual Feedback for AI Agents

Instruckt lets users annotate elements directly in the browser. The user pastes structured markdown into the chat — everything you need is in the paste.

## Workflow

When the user pastes UI feedback:

1. **Make the fix** — the pasted markdown has the element, component, classes, and text context to find the right code
2. **Check for screenshots** — if any annotation mentions a screenshot, call `instruckt.get_screenshot` to see what the user sees
3. **Resolve via MCP** — call `instruckt.get_all_pending` to get annotation IDs, then call `instruckt.resolve` for each one you fixed. This removes the markers from the user's browser automatically (no reload needed).

## Recognizing Pasted Feedback

When the user pastes text like this, treat it as instruckt annotations:

```
# UI Feedback: /dashboard

## 1. Change the heading text
- ID: `01JWXYZ123ABC`
- Element: `h1.text-xl` in `pages::dashboard`
- Source: `app/Livewire/Pages/Dashboard.php:1`
- Classes: `text-xl font-bold`
- Text: "Welcome"
- Screenshot: `storage/app/_instruckt/screenshots/01JWXYZ.png`
```

Each `##` item is one annotation. The `ID` field is the annotation ID — use it directly with `instruckt.resolve` after fixing. The `Source` field (when available) tells you exactly which file to edit.

## Source Resolution

When annotations include framework context, the server automatically resolves component names to source file paths. The `framework` object in each annotation may include:

- `source_file` — relative path to the component file (e.g. `app/Livewire/Dashboard.php`)
- `source_line` — starting line number of the class
- `render_line` — line number of the `render()` method (Livewire)
- `class_name` — fully-qualified PHP class name (e.g. `App\Livewire\Dashboard`)

Use `source_file` to open the exact file instead of searching. For Livewire components, `render_line` points to where the view is returned.

## Screenshots

Annotations may include a screenshot of the clicked element or a user-selected region. When `get_all_pending` returns an annotation with `has_screenshot: true`, call `get_screenshot` to see exactly what the user is referring to.

## MCP Tools

| Tool | When to use |
|------|-------------|
| `instruckt.get_all_pending` | Get all pending annotations |
| `instruckt.get_screenshot` | Get the screenshot image for an annotation (when `has_screenshot` is true) |
| `instruckt.resolve` | Mark as resolved after fixing — removes the marker from the browser |

## Best Practices

- **Always resolve after fixing** — without this, the marker stays visible in the user's browser
- The annotation ID is in the pasted markdown (the `ID` field) — use it directly with `instruckt.resolve`. No need to call `get_all_pending` first unless you need screenshots.
- The `Source` field tells you exactly which file to edit — use it to navigate directly