# Visual Feedback

> Use when the user wants to give feedback on a document, concept, design, plan, or report section by section - e.g. asks for a "Review-Seite", "Feedback-Seite", a kommentierbare HTML-Version, "Feedback zu jedem Abschnitt/jeder Box/jedem Element", comment pins in SVG diagrams, or wants to annotate a deliverable and paste the collected feedback back into the chat. Also when retrofitting an existing…

- **Type:** Skill
- **Install:** `agentstack add skill-okuegow-agent-skills-visual-feedback`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [okuegow](https://agentstack.voostack.com/s/okuegow)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [okuegow](https://github.com/okuegow)
- **Source:** https://github.com/okuegow/agent-skills/tree/main/plugins/visual-feedback/skills/visual-feedback
- **Website:** https://github.com/okuegow/agent-skills

## Install

```sh
agentstack add skill-okuegow-agent-skills-visual-feedback
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Visual Feedback

## Overview

Turn any deliverable (concept, report, design, plan) into ONE self-contained HTML
review page where every meaningful element is an inline comment point. Each
comment can carry a category (Question/Error/Change/Praise) and priority
(Must/Optional). Comments persist in localStorage, and the user exports them as
structured markdown WITH a JSON attachment (clipboard or .md file) to paste back
into the chat. The chat paste-back closes the loop: the agent maps each comment
to its target `id` and works the feedback in.

The UI defaults to English and carries a small EN/DE toggle in the toolbar; the
toggle switches every visible string AND the exported markdown, and persists in
localStorage under `fb:lang`. Category/priority are stored as stable, language-
independent ids (`frage/fehler/aenderung/lob`, `muss/optional`); only their
display labels translate, so the JSON block reads the same in either language.

**Template:** copy and adapt `template.html` in this skill directory. It contains
the complete widget CSS/JS and one example of every target type. Do not rebuild
the mechanics from scratch - that is how past pages drifted into incompatible
variants. The script builds its own toolbar, toast and preview overlay, so
retrofitting an existing HTML page = paste the template's widget CSS block and
complete `` into it, then only add the markers from the recipe plus
`data-fbkey`/`data-fbver` on ``. Nothing else is required.

## Recipe (the page IS this)

1. **Comment points.** `` carries `data-fbkey=""` (never reuse
   across pages) and `data-fbver=""` (bump on every content rewrite, or old
   comments stick to changed spots). Each `` carries
   `data-fbsec=" · "`. Targets:
   - `data-fbauto` on a section/container auto-pins every `p`, `li`,
     `blockquote`, `h3`, `h4` and **every table row** inside (`data-fbskip`
     excludes subtrees) - the default for prose/tables
   - `data-fb="id"` + `data-fblabel="Label"` for manual targets (cards,
     callouts, diagram units)
   - `data-fb` on SVG elements gives overlay pins with a comment panel below
     the diagram
   - `` for always-visible fields: one general-feedback
     field per section plus a "Gesamturteil" at the end
2. **Widget.** A ✎ pin per target opens a textarea in place, plus type/priority
   chips. Input autosaves (debounced). The sticky toolbar (built by the script)
   shows a storage-status pill, an "X/Y commented" counter, an EN/DE language
   toggle, a filter (All/Open/Commented), jump arrows, Preview, Copy feedback,
   Save as .md and Reset. All labels shown here are the English default; the DE
   toggle swaps them (and the export) to German.
3. **Versioning that doesn't lose feedback.** Comments live under
   `fb::v`. When `data-fbver` is bumped, comments with a still-existing
   target `id` are carried into the new version automatically (marked "übernommen
   aus vX"); comments whose target is gone surface under "Nicht mehr zuordenbar".
   So bumping the version is safe, not lossy. Stable ids matter: manual `data-fb`
   ids and general fields carry cleanly; auto-ids are text-slug based.
   Multi-tab: saves are read-modify-write merged and a `storage` listener syncs
   other tabs live (targets with a pending edit or open editor are left alone),
   so the common case (one reviewer, maybe a second tab) never loses data.
   localStorage has no real transactions, so genuinely concurrent saves from two
   tabs in the same instant can still drop one - the tool is built for
   single-reviewer use, not concurrent co-editing.
4. **Export - both ways, structured, dual-format.** "Copy feedback"
   (navigator.clipboard with execCommand fallback), "Save as .md" (Blob
   download) and "Preview" all produce the same document: human-readable markdown
   grouped by section, PLUS a machine-readable JSON block for the agent. The
   markdown headings follow the UI language (English shown below; German when the
   DE toggle is on). The JSON block is language-independent.

   ```markdown
   # Feedback: 
   Captured on 
   Page: `` · Version v ·  comments
   Summary: 2× Error, 1× Question (of which 1× Must)

   ## 
   ****
   Text · `` · Error · Must
   _Ref: ""_
   > comment line(s)

   ...
   ```json
   { "page": ..., "version": ..., "comments": [ {id,type,section,label,quote,category,priority,comment,ts}, ... ], "orphans": [...] }
   ```
   ```

   When working the feedback in, prefer the JSON block: `id` is the stable anchor,
   `quote` the context, `category`/`priority` the intent (values stay
   `frage/fehler/aenderung/lob` and `muss/optional` regardless of UI language).
5. **Reset without dialogs.** Reset is a two-click confirm inside the button
   itself ("Sure? Click again" / "Wirklich? Erneut klicken", auto-disarm after
   3 s). The page contains zero `alert()` / `confirm()` / `prompt()` calls - they
   block the browser.
6. **Self-contained file.** No CDNs, webfonts, or external requests; system font
   stacks (e.g. Charter/Avenir on macOS); light + dark via
   `prefers-color-scheme`; `prefers-reduced-motion` respected; works from
   `file://` (in-memory fallback with a visible warning when localStorage is
   blocked). English UI by default with an EN/DE toggle; German strings use real
   Umlauten, and no text uses em-dashes.
7. **Verify, then open.** Parse the HTML (python `html.parser`: no unclosed tags,
   count of `data-fb` targets matches plan), `node --check` the extracted
   ``, then open with macOS `open` (never browser-automation tools for
   local files). The widget mechanics themselves are covered by the jsdom smoke
   test `template-test.js` next to the template (needs `npm install jsdom`,
   run only after changing the template, not per page).

## Common mistakes

| Mistake | Fix |
|---|---|
| Rebuilding widget JS/CSS instead of copying the template | Copy template.html; only content and markers change |
| Hand-marking every paragraph with data-fb | `data-fbauto` on the section; hand-mark only boxes and SVG elements |
| Working feedback in from the prose alone | Use the JSON block: `id` is the stable anchor, `quote` the context |
| Changing manual `data-fb` ids between versions | Keep ids stable so v-bump carries comments; only auto-ids may shift |
| SVG pins at 0/0 or drifting after resize | Positioning runs via getBoundingClientRect on load AND resize - keep the template's positionSvgPins wiring intact |
| Table rows not commentable | Use the ✎-cell + colspan-row mechanism from the template |
| `confirm()` for reset | Two-click confirm in the button (template has it) |
| Export as free-form plaintext | Grouped markdown with `data-fbsec`/`data-fblabel` so the agent can map comments back |
| Only clipboard export | Also offer the .md Blob download (clipboard can fail on file://) |
| Same localStorage key on two pages | Unique key per file, or comments bleed between pages |
| Feedback UI drowns the content | Widgets stay collapsed until toggled; content layout comes first |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [okuegow](https://github.com/okuegow)
- **Source:** [okuegow/agent-skills](https://github.com/okuegow/agent-skills)
- **License:** MIT
- **Homepage:** https://github.com/okuegow/agent-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-okuegow-agent-skills-visual-feedback
- Seller: https://agentstack.voostack.com/s/okuegow
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.