agentation

SKILL.md

Agentation Setup

Set up the toolbar and, when requested, connect it to the user's coding agent.
A visible toolbar and a healthy MCP server do not prove that browser feedback
reaches the agent. Verify that final step before calling setup complete.

Steps

Inspect the project

Read the project's instructions and detect its package manager.

Look for agentation and an existing <Agentation> mount before installing.

If already mounted, inspect its endpoint and current MCP setup. Do not
exit just because the component exists, and do not add a duplicate mount.

Install agentation if missing, using the existing lockfile's package manager.

Choose the connection mode from the request

For MCP or live agent feedback, use the same HTTP server URL as the agent.
The default local server is http://localhost:4747; preserve an existing
custom port or proxy URL. Never assume the browser and agent use the same
machine when the project is remote.

For manual copy/paste only, omit endpoint and explain that feedback remains
in this browser. Do not silently enable a server connection.

If the intended mode is unclear, ask one brief question while inspecting
the existing project. Keep working on independent setup checks.

Add or update the component

For a Next.js App Router project, render in the root layout's body after
children. For Pages Router, render after Component in pages/_app.
Preserve any existing callbacks and options.

import { Agentation } from "agentation";

// Use the actual server URL selected above for MCP sync:
{process.env.NODE_ENV === "development" && (
  <Agentation endpoint="http://localhost:4747" />
)}

The package provides its own client boundary. Keep the application's root
layout server-rendered unless the project has another reason to change it.

Configure the agent when MCP was requested

Use the project's existing MCP client and configuration conventions.

The launch command must include the server subcommand:
npx -y agentation-mcp server.

For supported agents, npx add-mcp "npx -y agentation-mcp server" is one
setup option. For Claude Code, use
claude mcp add agentation -- npx -y agentation-mcp server or the init wizard.

Apply the same custom port to the server command and component endpoint.

Restart or reconnect the agent when its configuration requires it. Do not
create a second HTTP server on a port already owned by the working server.

Verify the complete connection

Run npx agentation-mcp doctor for service diagnostics. For a custom URL,
use doctor --http-url <url> when supported by the installed version.

Open the app and create one clearly identified test annotation through the
toolbar. Read it with agentation_get_all_pending or session-scoped tools.

Check the exact test comment and page, not just a nonzero count or health
response. Leave unrelated annotations alone.

If annotations are empty, check the component endpoint, browser network
failures/CORS, and whether the agent and browser point to the same server.

If browser or MCP tools are unavailable, say exactly which part remains
unverified and give the user this final check. Do not claim live sync works.

Notes

The development guard prevents the toolbar from appearing in production.

Agentation requires React 18 or newer.

Installing the toolbar does not install, configure or connect an MCP server.

Manual copy mode is supported and does not need a running server.