Skip to content
Skills Library
Programming · Tool integration

agentation

/agentation

Add Agentation visual feedback toolbar to a project. Use when the user asks to "install Agentation", "add the Agentation toolbar", or "set up visual feedback". Covers Rails apps that bundle with webpack into `app/assets/builds` (the RoleModel default) by adding React as a development-only dependency, plus hosts that already bundle React. The same pattern adapts to other server-rendered hosts, but the snippets are Rails.

Repository
skills ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Add Agentation visual feedback toolbar to a project. Use when the user asks to "install Agentation", "add the Agentation toolbar", or "set up visual feedback". Covers Rails apps that bundle with webpack into `app/assets/builds` (the RoleModel default) by adding React as a development-only dependency, plus hosts that already bundle React. The same pattern adapts to other server-rendered hosts, but the snippets are Rails.

Triggers from the description

install Agentationadd the Agentation toolbarset up visual feedback
Original author description

Add Agentation visual feedback toolbar to a project. Use when the user asks to "install Agentation", "add the Agentation toolbar", or "set up visual feedback". Covers Rails apps that bundle with webpack into `app/assets/builds` (the RoleModel default) by adding React as a development-only dependency, plus hosts that already bundle React. The same pattern adapts to other server-rendered hosts, but the snippets are Rails.

How it works

  1. Steps
  2. Notes
Original SKILL.md headings · 258 lines, 1,800 words
SKILL.md preview
---
name: agentation
description: Add Agentation visual feedback toolbar to a project. Use when the user asks to "install Agentation", "add the Agentation toolbar", or "set up visual feedback". Covers Rails apps that bundle with webpack into `app/assets/builds` (the RoleModel default) by adding React as a development-only dependency, plus hosts that already bundle React. The same pattern adapts to other server-rendered hosts, but the snippets are Rails.
---

# Agentation Setup

> Adapted from [benjitaylor/agentation](https://github.com/benjitaylor/agentation)
> `skills/agentation`, upstream commit `4a3b08f` (2026-02-18), which covers Next.js
> only. Steps 1, 2 and 7 are upstream's; the non-React host path is RoleModel's
> addition. Re-check against upstream when bumping the `agentation` package — the
> toolbar's internals are not a public API.

Set up the Agentation annotation toolbar in this project.

Agentation ships a single React component. React is therefore required — but it is
required **only in development**, and it must never reach the production bundle.
In a project that already uses React that is automatic. In a project that does not,
add React as a development-only dependency rather than declining to install.

## Steps

1. **Check if already configured** — do this before installing anything
   - Search for `<Agentation` or `from "agentation"` / `from 'agentation'` across the
     project's source directories (`src/`, `app/`, `assets/`, `frontend/`)
   - If found, report that Agentation is already set up and exit

2. **Check if already installed**
   - Look for `agentation` in package.json `dependencies` or `devDependencies`
   - If not found, install it as a **dev dependency**: `npm install -D agentation`
     (or `yarn add -D` / `pnpm add -D` based on the lockfile)

3. **Check for React — add it as a dev dependency if absent**
   - Look for `react` and `react-dom` in package.json `dependencies` **or**
     `devDependencies`
   - If either is already present anywhere, leave it alone — never move an existing
     runtime dependency into devDependencies, and never change its version range
   - **If React is present but below 18**, stop and tell the user. Agentation's peer
     range is `>=18.0.0` and the mount script needs `react-dom/client`, which does not
     exist in 17. Upgrading the host's React is a real decision, not a side effect of
     installing a dev toolbar — do not do it here
   - If absent, install the latest React as dev dependencies — do not pin an older
     major:
     ```bash
     npm install -D react react-dom
     ```
     Agentation's peer range is `>=18`, so whatever `latest` resolves to satisfies
     it. Nothing is being shipped to users here, so there is no reason to hold back
     to an older major.

4. **Detect the host**

   | Host | Signal |
   | ---- | ------ |
   | Non-React host | React was added in step 3 — a server-rendered app (Rails, Django, Laravel, Phoenix) or a plain bundler setup. **This is the common case.** |
   | Host that already bundles React | `react` was already a dependency before step 3 |

   For a non-React host, also identify the bundler (`webpack.config.js`,
   `vite.config.*`, `rollup.config.*`), its **output directory** (webpack `output.path`,
   `app/assets/builds/` or shakapacker's `public/packs/`, Vite's `build.outDir`), and the
   server-rendered layout template that emits `<script>` tags. You need all three — step 7
   verifies against the output directory.

   The snippets in step 5 are written for the RoleModel Rails default: a hand-rolled
   `webpack.config.js` with a module-scope `mode` variable, output to
   `app/assets/builds`, served by sprockets/propshaft. That is the shape they are known
   to work in. Read the project's actual config before pasting — each snippet below
   notes what to do when it differs.

5. **Add the component**

   **Non-React host** (Rails and friends — the path below is the one you almost always
   want) — do NOT add React to the app's existing entry point. Create a
   separate, dev-only bundle entry so the main bundle is untouched:

   a. Write a standalone entry (e.g. `app/javascript/agentation.js`). Use
      `createElement` rather than JSX so the project needs no JSX toolchain config:

   ```js
   // Development-only entry: mounts the Agentation feedback toolbar.
   import { createElement } from 'react'
   import { createRoot } from 'react-dom/client'
   import { Agentation } from 'agentation'

   const CONTAINER_ID = 'agentation-root'
   const ENDPOINT = 'http://localhost:4747' // agentation-mcp HTTP server

   let root = null

   function mount() {
     if (document.getElementById(CONTAINER_ID)) return

     root?.unmount()

     const container = document.createElement('div')
     container.id = CONTAINER_ID
     document.body.appendChild(container)

     root = createRoot(container)
     root.render(createElement(Agentation, { endpoint: ENDPOINT }))
   }

   // Re-mount after client-side navigation that swaps <body>.
   document.addEventListener('turbo:load', mount)   // Turbo / Hotwire
   document.addEventListener('turbo:morph', mount)
   mount()
   ```

   b. Register the entry **only in the bundler's development mode**. This is the real
      production guarantee — the dev dependency alone is not enough. webpack, reusing
      the `mode` variable a RoleModel config already computes near the top of the file:

   ```js
   const isDevelopment = mode === 'development'

   entry: {
     application: './app/javascript/application.js',
     ...(isDevelopment && { agentation: './app/javascript/agentation.js' })
   }
   ```

   That `mode` binding comes from the app's config, not from webpack. If it is not in
   scope — shakapacker's generated config is `generateWebpackConfig()` with no `mode`
   variable, and a plain object export has `mode` only as a key — derive the flag
   directly instead:

   ```js
   const isDevelopment = process.env.RAILS_ENV !== 'production'
   ```

   Shakapacker and Vite also have no top-level `entry` literal to spread into
   (shakapacker returns a built config object; Vite uses `build.rollupOptions.input`).
   Add the entry to whatever those configs actually expose, and keep the dev gate.

   c. Emit the script from the server-rendered layout, gated on the server's
      development environment. Rails/Slim:

   ```slim
   - if Rails.env.development?
     = javascript_include_tag 'agentation', defer: true
   ```

   `javascript_include_tag` is correct when webpack writes to `app/assets/builds` and
   sprockets/propshaft serves it — the RoleModel default. A **shakapacker** app writing
   to `public/packs` needs `javascript_pack_tag 'agentation'` instead;
   `javascript_include_tag` will not resolve a pack, and the toolbar silently never
   loads. Non-Rails hosts (Django, Laravel, Phoenix) use the same two ideas — a
   dev-gated conditional and the framework's own script tag helper — but the helper
   name is theirs, not this one.

   Do not add cache-busting/asset-tracking attributes (e.g. Turbo's
   `data-turbo-track: 'reload'`) to this tag — rebuilding the dev bundle would then
   force full page reloads.

   **Host that already bundles React** — render `<Agentation />` once near the root of
   the tree, behind a `process.env.NODE_ENV === 'development'` check. Import it through a
   dev-only dynamic import rather than a top-level `import`: a top-level import leaves the
   module in the production bundle unless the bundler can prove it side-effect free, and
   the point of this skill is that it never gets there.

6. **Match the host's root font-size**

   Agentation sizes itself in a mix of px and rem against a 16px root. Optics sets
   `html { font-size: 62.5% }` (`1rem = 10px`), so on an Optics app every rem value in
   the toolbar renders at 62.5% while every px value renders correctly — small text and
   tight gaps around full-size icons. `rem` cannot be rebased for a subtree and
   Agentation exposes no sizing custom properties, so bake the rem values to px at build
   time. Skip this step if the host's root font-size is already 16px.

   a. Add a loader:

   ```js
   // config/webpack/agentation-rem-to-px.cjs
   module.exports = (source) =>
     source.replace(/(\d*\.?\d+)rem\b/g, (_, v) => `${parseFloat(v) * 16}px`)
   ```

   b. Register it in the same dev-only branch as the entry, so it cannot reach a
      production build:

   ```js
   ...(isDevelopment ? [{
     test: /node_modules[\\/]agentation[\\/]/,
     loader: path.resolve('config/webpack/agentation-rem-to-px.cjs')
   }] : []),
   ```

   Rebuild, then confirm in the browser console with the annotation dialog open. Expect
   `0`; anything else means the loader did not run:

   ```js
   [...document.querySelectorAll('style')]
     .filter(s => s.textContent.includes('styles-module__'))
     .reduce((n, s) => n + (s.textContent.match(/[\d.]+rem/g) || []).length, 0)
   ```

7. **Confirm and verify**
   - Tell the user the Agentation toolbar component is configured
   - For a non-React host, verify the production boundary before reporting success.
     Run these against the output directory found in step 4 — `$OUT` below is that
     directory (`app/assets/builds`, `public/packs`, `dist`, …), **not** a literal:
     ```bash
     # Build into a clean directory — a leftover dev artifact in $OUT reads as a
     # failure that isn't real, and a wrong $OUT reads as a pass that isn't real.
     # check-ignore refuses to delete anything that isn't generated build output.
     git check-ignore -q "$OUT" || { echo "refusing: $OUT is not gitignored"; exit 1; }
     rm -rf "$OUT" && RAILS_ENV=production npm run build   # or NODE_ENV=production
     ls "$OUT" | grep -i agentation                        # expect: no matches
     ```
     If the bundler writes hashed filenames through a manifest
     (`public/packs/manifest.json`, `.vite/manifest.json`), grep the manifest for an
     `agentation` entry instead of guessing the filename.

     Do **not** try to prove React's absence by grepping the output for `react-dom`.
     Production builds are minified and that string need not survive, so "no matches"
     is not evidence either way. If you want a second signal, compare the total output
     size against a build from before this change — a leaked React DOM adds well over
     100 KB.

     Restore the development build afterward.

8. **Recommend MCP server setup**
   - Explain that for real-time annotation syncing with AI agents, they should also set up the MCP server
   - Recommend one of the following approaches:
     - **Universal (supports 9+ agents including Claude Code, Cursor, Codex, Windsurf, etc.):**
       See [add-mcp](https://github.com/neondatabase/add-mcp) — run `npx add-mcp` and follow the prompts to add `agentation-mcp` as an MCP server
     - **Claude Code only (interactive wizard):**
       Run `agentation-mcp init` after installing the package
   - Tell user to restart their coding agent after MCP setup to load the server
   - Explain that once configured, annotations will sync to the agent automatically

## Notes

- The `NODE_ENV` / bundler-mode / server-env checks ensure Agentation only loads in
  development. In a non-React host, layer all three — the bundler-mode check is the
  one that actually keeps React out of the production bundle.
- Agentation's peer range is `>=18`, so installing React at `latest` is always
  compatible. It declares those peers as **optional**, so a package manager will not
  warn when they are absent — check package.json yourself rather than relying on
  install output.
- `Agentation` renders as a **React portal into `document.body`** and injects its
  `<style>` tags into `<head>`. The styles survive navigation; the portal does not.
  Turbo/Hotwire swaps `document.body`, so the two `turbo:` listeners in step 5 are
  required or the toolbar silently disappears after the first link click. Any other
  host that replaces the body needs the equivalent listener for its own navigation
  event — the sample wires Turbo only.
- Without an `endpoint` prop the toolbar is localStorage + clipboard only. Pass
  `endpoint: "http://localhost:4747"` to sync with `agentation-mcp`. If that server
  is not running, expect a console fetch error on send; annotations still persist
  locally.
- Agentation has no style isolation — no shadow DOM, styles injected as `<style>` tags
  into `<head>`, portal into `document.body`. Step 6 fixes its own sizing, but host
  element selectors still reach it: a bare `button` or `textarea` rule in the app's
  stylesheets will restyle the toolbar's controls. Find the winning rule in devtools and
  scope it out rather than adding an ID-prefixed reset, which outranks Agentation's own
  class rules and trades a wrong focus ring for no focus ring.
- Agentation is licensed PolyForm Shield 1.0.0 — fine for an internal dev tool, but
  worth mentioning in a client codebase.
- The MCP server runs on port 4747 by default for the HTTP server
- MCP server exposes tools like `agentation_get_all_pending`, `agentation_resolve`, and `agentation_watch_annotations`
- Run `agentation-mcp doctor` to verify setup after installing

Versions

RepositoryScoreLicence
This page · rolemodel/skills100MIT
jscraik/Agent-Skills100Apache-2.0

Database snapshot: 13.11.2026 · package version a8e1a8814866 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agentation-self-driving
    Autonomous design critique mode using the Agentation annotation toolbar. Use when the user asks to "critique this page," "add design annotations," "review the UI," "self-driving mode," "auto-annotate," or wants an AI agent to autonomously add design feedback annotations to a web…
  • 86agentation-annotations
    The user leaves fixes for the Claude OS interface through agentation, bound to elements. Use when they ask you to look at their notes, annotations or the fixes they marked.
  • 100sim-agentation
    Work through UI annotations a user drew on an iOS simulator with SimAgentation. Fetch them, find the SwiftUI or UIKit code behind each box, make the change, and close the loop with sim_resolve, sim_dismiss or sim_reply. Use this whenever sim_* tools (sim_get_pending, sim_watch,…
  • 100sim-agentation-sdk
    Add the SimAgentationPlus SDK to an Apple app, so the annotations a user draws in SimAgentation carry the exact Swift file and line of each tagged view, the app's real view tree and its bundle ID. Covers adding the Swift package (Package.swift, XcodeGen, Tuist or a plain…
  • 100rails-conventions
    RoleModel's Rails conventions where they differ from what an agent writes by default: flash wording, the status for failed saves, Simple Form for every form, how route concerns pass the parent type, and two gotchas (`params.expect` with nested attributes, and Lexxy rich-text…
  • 100rails
    Ruby on Rails is a full-stack web framework with ActiveRecord ORM, controllers, views, Active Job, Action Cable and built-in authentication. Use when someone asks to "create a Rails app", "add a model and migration", "build a Rails API endpoint", "add login to Rails", "run…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.