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.
- Author
- rolemodel ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
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
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
- Steps
- Notes
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
| Repository | Score | Licence |
|---|---|---|
| This page · rolemodel/skills | 100 | MIT |
| jscraik/Agent-Skills | 100 | Apache-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…