agentation — Skillopedia

agentation is the rendered-UI feedback bridge in this repo. Use it when a human needs to click the actual UI, attach feedback to the exact element or region they mean, and pass a structured packet to the coding agent. The main job is annotation routing : choose the right annotation mode, capture precise evidence, then hand the fix loop to the right adjacent skill or agent runtime. When to use this skill Use when the task needs one or more of these: - a human reviewer pointing at a real UI element instead of describing it vaguely - structured feedback packets with selectors, element paths, bou…

\\n# agentation MCP Server\\n[[mcp_servers]]\\nname = \"agentation\"\\ncommand = \"npx\"\\nargs = [\"-y\", \"agentation-mcp\", \"server\"]\\n'\n\n if [[ -f \"$CODEX_CFG\" ]]; then\n if grep -q '\"agentation\"\\|name = \"agentation\"' \"$CODEX_CFG\" 2>/dev/null; then\n warn \"Codex CLI: agentation already in $CODEX_CFG — skipping\"\n else\n printf '%s' \"$CODEX_ENTRY\" >> \"$CODEX_CFG\"\n ok \"Codex CLI: appended to $CODEX_CFG\"\n fi\n else\n printf '%s' \"$CODEX_ENTRY\" > \"$CODEX_CFG\"\n ok \"Codex CLI: created $CODEX_CFG\"\n fi\n echo \"\"\nfi\n\n# ─── Gemini CLI (~/.gemini/settings.json) ─────────────────────────────────\nif [[ \"$SETUP_GEMINI\" == \"true\" ]]; then\n info \"Setting up Gemini CLI...\"\n GEMINI_DIR=\"$HOME/.gemini\"\n GEMINI_CFG=\"$GEMINI_DIR/settings.json\"\n mkdir -p \"$GEMINI_DIR\"\n\n MCP_JSON='{\"command\":\"npx\",\"args\":[\"-y\",\"agentation-mcp\",\"server\"]}'\n\n if [[ -f \"$GEMINI_CFG\" ]]; then\n if command -v jq &>/dev/null; then\n MERGED=$(jq --argjson entry \"$MCP_JSON\" '.mcpServers.agentation = $entry' \"$GEMINI_CFG\" 2>/dev/null)\n if [[ -n \"$MERGED\" ]]; then\n echo \"$MERGED\" > \"$GEMINI_CFG\"\n ok \"Gemini CLI: merged into $GEMINI_CFG\"\n else\n warn \"Gemini CLI: jq merge failed — add manually\"\n fi\n else\n warn \"Gemini CLI: jq not found — add manually to $GEMINI_CFG:\"\n echo ' \"mcpServers\": { \"agentation\": { \"command\": \"npx\", \"args\": [\"-y\", \"agentation-mcp\", \"server\"] } }'\n fi\n else\n cat > \"$GEMINI_CFG\" \u003c\u003c'EOF'\n{\n \"mcpServers\": {\n \"agentation\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"agentation-mcp\", \"server\"]\n }\n }\n}\nEOF\n ok \"Gemini CLI: created $GEMINI_CFG\"\n fi\n echo \"\"\nfi\n\n# ─── OpenCode (~/.config/opencode/opencode.json) ──────────────────────────\nif [[ \"$SETUP_OPENCODE\" == \"true\" ]]; then\n info \"Setting up OpenCode...\"\n OC_DIR=\"$HOME/.config/opencode\"\n OC_CFG=\"$OC_DIR/opencode.json\"\n mkdir -p \"$OC_DIR\"\n\n MCP_ENTRY='{\"type\":\"local\",\"command\":[\"npx\",\"-y\",\"agentation-mcp\",\"server\"]}'\n\n if [[ -f \"$OC_CFG\" ]]; then\n if command -v jq &>/dev/null; then\n MERGED=$(jq --argjson entry \"$MCP_ENTRY\" '.mcp.agentation = $entry' \"$OC_CFG\" 2>/dev/null)\n if [[ -n \"$MERGED\" ]]; then\n echo \"$MERGED\" > \"$OC_CFG\"\n ok \"OpenCode: merged into $OC_CFG\"\n else\n warn \"OpenCode: jq merge failed — add manually\"\n fi\n else\n warn \"OpenCode: jq not found — add manually to $OC_CFG:\"\n echo ' \"mcp\": { \"agentation\": { \"type\": \"local\", \"command\": [\"npx\", \"-y\", \"agentation-mcp\", \"server\"] } }'\n fi\n else\n cat > \"$OC_CFG\" \u003c\u003c'EOF'\n{\n \"mcp\": {\n \"agentation\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"agentation-mcp\", \"server\"]\n }\n }\n}\nEOF\n ok \"OpenCode: created $OC_CFG\"\n fi\n echo \"\"\nfi\n\n# ─── Done ─────────────────────────────────────────────────────────────────\necho \"╔══════════════════════════════════════════╗\"\necho \"║ Setup Complete ║\"\necho \"╚══════════════════════════════════════════╝\"\necho \"\"\necho \"Next steps:\"\necho \" 1. Restart your agent(s)\"\necho \" 2. Start agentation MCP server: npx agentation-mcp server\"\necho \" 3. Add to your app: import { Agentation } from 'agentation'\"\necho \" \u003cAgentation endpoint=\\\"http://localhost:4747\\\" />\"\necho \"\"\necho \"Available MCP tools: agentation_watch_annotations, agentation_resolve, agentation_acknowledge, ...\"\necho \"Run 'npx agentation-mcp doctor' to verify.\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":7342,"content_sha256":"f345d8c2b6fdb8e5161f4b1be1f293d7540039939939f2dbadc82cdbc1610f03"},{"filename":"scripts/verify-loop.sh","content":"#!/usr/bin/env bash\n# verify-loop.sh — Integration test for agentation watch loop\n# Tests: server health, annotation CRUD, ACK-RESOLVE cycle, error cases\n# Usage: bash verify-loop.sh [--quick] (--quick skips phase 4 error tests)\nset -euo pipefail\n\nGREEN='\\033[0;32m'; RED='\\033[0;31m'; YELLOW='\\033[1;33m'; NC='\\033[0m'\npass() { echo -e \"${GREEN}PASS${NC} $*\"; }\nfail() { echo -e \"${RED}FAIL${NC} $*\"; FAILURES=$((FAILURES + 1)); }\ninfo() { echo -e \"${YELLOW}....${NC} $*\"; }\n\nFAILURES=0\nBASE_URL=\"http://localhost:4747\"\nQUICK=false\n[[ \"${1:-}\" == \"--quick\" ]] && QUICK=true\n\necho \"\"\necho \"agentation Watch Loop — Integration Test\"\necho \"=========================================\"\necho \"\"\n\n# ── Phase 1: Server Health ──────────────────────────────────────────────────\n\necho \"Phase 1: Server Health\"\necho \"──────────────────────\"\n\ninfo \"1a. Health check\"\nif curl -sf --connect-timeout 3 \"${BASE_URL}/health\" >/dev/null 2>&1; then\n pass \"GET /health — server reachable\"\nelse\n fail \"GET /health — server not reachable. Start with: npx agentation-mcp server\"\n echo \"\"\n echo \"Cannot continue without server. Exiting.\"\n exit 1\nfi\n\ninfo \"1b. Status check\"\nSTATUS=$(curl -sf \"${BASE_URL}/status\" 2>/dev/null || echo \"\")\nif [[ -n \"$STATUS\" ]]; then\n pass \"GET /status — returns server metadata\"\nelse\n fail \"GET /status — empty response\"\nfi\n\ninfo \"1c. Baseline pending check\"\nPENDING=$(curl -sf \"${BASE_URL}/pending\" 2>/dev/null || echo '{\"count\":-1}')\nBASELINE_COUNT=$(echo \"$PENDING\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('count',-1))\" 2>/dev/null || echo -1)\nif [[ \"$BASELINE_COUNT\" -ge 0 ]]; then\n pass \"GET /pending — baseline count: ${BASELINE_COUNT}\"\nelse\n fail \"GET /pending — invalid response\"\nfi\n\necho \"\"\n\n# ── Phase 2: Session & Annotation CRUD ──────────────────────────────────────\n\necho \"Phase 2: Annotation CRUD\"\necho \"────────────────────────\"\n\ninfo \"2a. Create session\"\nSESSION_RESP=$(curl -sf -X POST \"${BASE_URL}/sessions\" -H \"Content-Type: application/json\" -d '{}' 2>/dev/null || echo \"\")\nSESSION_ID=$(echo \"$SESSION_RESP\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('id',''))\" 2>/dev/null || echo \"\")\nif [[ -n \"$SESSION_ID\" ]]; then\n pass \"POST /sessions — created session: ${SESSION_ID:0:12}...\"\nelse\n fail \"POST /sessions — failed to create session\"\n echo \"Cannot continue without session. Exiting.\"\n exit 1\nfi\n\ninfo \"2b. Create annotation\"\nANN_RESP=$(curl -sf -X POST \"${BASE_URL}/sessions/${SESSION_ID}/annotations\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"comment\\\":\\\"Test: change button color\\\",\\\"element\\\":\\\"button\\\",\\\"elementPath\\\":\\\"body > main > button.cta\\\",\\\"x\\\":50,\\\"y\\\":100}\" 2>/dev/null || echo \"\")\nANN_ID=$(echo \"$ANN_RESP\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('id',''))\" 2>/dev/null || echo \"\")\nif [[ -n \"$ANN_ID\" ]]; then\n pass \"POST annotation — created: ${ANN_ID:0:12}...\"\nelse\n fail \"POST annotation — failed\"\nfi\n\ninfo \"2c. Verify pending count = 1\"\nP_COUNT=$(curl -sf \"${BASE_URL}/sessions/${SESSION_ID}/pending\" 2>/dev/null \\\n | python3 -c \"import sys,json; print(json.load(sys.stdin).get('count',0))\" 2>/dev/null || echo 0)\nif [[ \"$P_COUNT\" -eq 1 ]]; then\n pass \"GET /sessions/:id/pending — count: 1\"\nelse\n fail \"GET /sessions/:id/pending — expected 1, got ${P_COUNT}\"\nfi\n\necho \"\"\n\n# ── Phase 3: ACK-RESOLVE Cycle ──────────────────────────────────────────────\n\necho \"Phase 3: ACK-RESOLVE Cycle\"\necho \"──────────────────────────\"\n\ninfo \"3a. Acknowledge annotation\"\nACK_RESP=$(curl -sf -X PATCH \"${BASE_URL}/annotations/${ANN_ID}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\":\"acknowledged\"}' 2>/dev/null || echo \"\")\nACK_STATUS=$(echo \"$ACK_RESP\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('status',''))\" 2>/dev/null || echo \"\")\nif [[ \"$ACK_STATUS\" == \"acknowledged\" ]]; then\n pass \"PATCH acknowledged — status: acknowledged\"\nelse\n fail \"PATCH acknowledged — expected 'acknowledged', got '${ACK_STATUS}'\"\nfi\n\ninfo \"3b. Resolve annotation\"\nRES_RESP=$(curl -sf -X PATCH \"${BASE_URL}/annotations/${ANN_ID}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\":\"resolved\",\"resolution\":\"Changed button color to #3b82f6\"}' 2>/dev/null || echo \"\")\nRES_STATUS=$(echo \"$RES_RESP\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('status',''))\" 2>/dev/null || echo \"\")\nif [[ \"$RES_STATUS\" == \"resolved\" ]]; then\n pass \"PATCH resolved — status: resolved\"\nelse\n fail \"PATCH resolved — expected 'resolved', got '${RES_STATUS}'\"\nfi\n\ninfo \"3c. Verify pending count = 0\"\nFINAL_COUNT=$(curl -sf \"${BASE_URL}/sessions/${SESSION_ID}/pending\" 2>/dev/null \\\n | python3 -c \"import sys,json; print(json.load(sys.stdin).get('count',0))\" 2>/dev/null || echo -1)\nif [[ \"$FINAL_COUNT\" -eq 0 ]]; then\n pass \"GET pending after resolve — count: 0 (all resolved)\"\nelse\n fail \"GET pending after resolve — expected 0, got ${FINAL_COUNT}\"\nfi\n\necho \"\"\n\n# ── Phase 4: Error Cases ────────────────────────────────────────────────────\n\nif ! $QUICK; then\n echo \"Phase 4: Error Cases\"\n echo \"────────────────────\"\n\n info \"4a. Invalid annotation ID\"\n HTTP_CODE=$(curl -sf -o /dev/null -w \"%{http_code}\" -X PATCH \"${BASE_URL}/annotations/nonexistent-id-12345\" \\\n -H \"Content-Type: application/json\" -d '{\"status\":\"acknowledged\"}' 2>/dev/null || echo \"000\")\n if [[ \"$HTTP_CODE\" == \"404\" || \"$HTTP_CODE\" == \"400\" ]]; then\n pass \"Invalid ID — HTTP ${HTTP_CODE} (expected 4xx)\"\n else\n fail \"Invalid ID — expected 4xx, got HTTP ${HTTP_CODE}\"\n fi\n\n info \"4b. GET non-existent session\"\n HTTP_CODE=$(curl -sf -o /dev/null -w \"%{http_code}\" \"${BASE_URL}/sessions/nonexistent-session-12345\" 2>/dev/null || echo \"000\")\n if [[ \"$HTTP_CODE\" == \"404\" || \"$HTTP_CODE\" == \"400\" ]]; then\n pass \"Non-existent session — HTTP ${HTTP_CODE} (expected 4xx)\"\n else\n fail \"Non-existent session — expected 4xx, got HTTP ${HTTP_CODE}\"\n fi\n\n echo \"\"\nfi\n\n# ── Summary ─────────────────────────────────────────────────────────────────\n\necho \"=========================================\"\nif [[ \"$FAILURES\" -eq 0 ]]; then\n echo -e \"${GREEN}ALL TESTS PASSED${NC}\"\n echo \"\"\n echo \"agentation watch loop is working correctly.\"\n echo \"MCP tool agentation_watch_annotations should function end-to-end.\"\nelse\n echo -e \"${RED}${FAILURES} TEST(S) FAILED${NC}\"\n echo \"\"\n echo \"Fix the issues above and re-run: bash verify-loop.sh\"\nfi\necho \"\"\nexit $FAILURES\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":7151,"content_sha256":"456010bee0beeb5aa687f8ec9f7d5cf34f47513584eb5b4f75ebac7ce84250ca"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"agentation","type":"text"}]},{"type":"paragraph","content":[{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the ","type":"text"},{"text":"rendered-UI feedback bridge","type":"text","marks":[{"type":"strong"}]},{"text":" in this repo.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use it when a human needs to click the actual UI, attach feedback to the exact element or region they mean, and pass a structured packet to the coding agent. The main job is ","type":"text"},{"text":"annotation routing","type":"text","marks":[{"type":"strong"}]},{"text":": choose the right annotation mode, capture precise evidence, then hand the fix loop to the right adjacent skill or agent runtime.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to use this skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the task needs one or more of these:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a human reviewer pointing at a real UI element instead of describing it vaguely","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"structured feedback packets with selectors, element paths, bounding boxes, or copied markdown","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a local copy-paste review loop between a browser and a coding agent","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"an MCP-backed sync/watch loop where new annotations flow into the agent context automatically","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a self-driving critique/fix loop that still starts from rendered UI evidence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"platform setup for passing pending UI annotations into Claude Code, Codex, Gemini CLI, or OpenCode","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" use ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" by default for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fresh-session browser verification or deterministic regression checks → ","type":"text"},{"text":"browser-harness","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"running-browser, logged-in, or extension-dependent browser reuse → ","type":"text"},{"text":"playwriter","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plan review, diff approval, or visual sign-off on a proposed artifact → ","type":"text"},{"text":"plannotator","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generic design-system, accessibility, or heuristic audits without a concrete rendered UI packet","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick routing rule","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"If the job needs...","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Human clicks the UI and leaves exact feedback for the agent","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Browser verification in a clean repeatable session","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"browser-harness","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The user's already-open browser, cookies, or logged-in tabs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"playwriter","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Review or approval of a plan/diff before execution","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"plannotator","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Instructions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Choose the right annotation mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Pick ","type":"text"},{"text":"one","type":"text","marks":[{"type":"strong"}]},{"text":" mode before touching setup details:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mode","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use when","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Output","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Copy-paste review","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"One reviewer wants to annotate UI and paste the packet into chat","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"a structured markdown packet","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Synced watch loop","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"New annotations should appear in the agent workflow automatically","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"pending-annotation queue + loop","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Self-driving critique","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"An agent/browser loop will generate or consume annotations repeatedly","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"a review/fix loop packet","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Platform setup","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The core problem is wiring the annotation bridge into Claude/Codex/Gemini/OpenCode","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"a setup checklist and config target","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If the task is really “test the website” or “drive the logged-in browser,” route out first and only come back to ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" if exact human UI feedback is the missing piece.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Keep the browser boundary explicit","type":"text"}]},{"type":"paragraph","content":[{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" replace the browser runtime choice.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"browser-harness","type":"text","marks":[{"type":"code_inline"}]},{"text":" when you want a clean disposable verification browser.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"playwriter","type":"text","marks":[{"type":"code_inline"}]},{"text":" when you must reuse the user's real browser session.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" once there is a rendered page that a human or loop should annotate precisely.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Follow the core loop","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prepare the rendered UI","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose the correct browser/runtime skill first if needed.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add the Agentation toolbar","type":"text","marks":[{"type":"strong"}]},{"text":" to the app in development.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pick the annotation mode","type":"text","marks":[{"type":"strong"}]},{"text":": copy-paste, watch loop, self-driving, or setup.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Capture one concrete UI packet","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hand the packet to the coding agent","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-verify after the fix","type":"text","marks":[{"type":"strong"}]},{"text":" using the same review lane.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Use the fastest safe install path","type":"text"}]},{"type":"paragraph","content":[{"text":"For most setups, the practical order is:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# React toolbar\nnpm install agentation -D\n\n# MCP bridge / auto-registration for supported agents\nnpx add-mcp \"npx -y agentation-mcp server\"\n\n# verify the bridge\nnpx agentation-mcp doctor","type":"text"}]},{"type":"paragraph","content":[{"text":"Claude Code users can also install the upstream official skill when that is the simplest way to bootstrap the experience:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npx skills add benjitaylor/agentation -g\n# then use /agentation in Claude Code","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Use a minimal toolbar integration first","type":"text"}]},{"type":"paragraph","content":[{"text":"Start with the smallest useful embed:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"tsx"},"content":[{"text":"import { Agentation } from 'agentation';\n\nfunction App() {\n return (\n \u003c>\n \u003cYourApp />\n {process.env.NODE_ENV === 'development' && \u003cAgentation />}\n \u003c/>\n )\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Only add ","type":"text"},{"text":"endpoint","type":"text","marks":[{"type":"code_inline"}]},{"text":", callbacks, or webhook behavior when the chosen mode actually needs them.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 6: Choose the right handoff pattern","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"A. Copy-paste review","type":"text"}]},{"type":"paragraph","content":[{"text":"Use when a human is actively reviewing the page and pasting the packet into an agent chat.","type":"text"}]},{"type":"paragraph","content":[{"text":"Good for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"quick bug/UI polish rounds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"one-off targeted fixes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"low-setup collaboration","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"B. Synced watch loop","type":"text"}]},{"type":"paragraph","content":[{"text":"Use when the agent should poll or ingest pending annotations continuously.","type":"text"}]},{"type":"paragraph","content":[{"text":"Good for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"repeated QA/fix passes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"designer ↔ agent loops","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"local review queues during active frontend work","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use the bundled verification script before trusting the loop:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bash .agent-skills/agentation/scripts/verify-loop.sh","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"C. Self-driving critique","type":"text"}]},{"type":"paragraph","content":[{"text":"Use when an agent/browser loop is reviewing UI repeatedly and ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the structured feedback packet, not the browser runtime itself.","type":"text"}]},{"type":"paragraph","content":[{"text":"Typical shape:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"browser tool captures current state","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" encodes concrete feedback targets","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"coding agent applies the fix","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"browser tool re-checks the result","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7: Keep platform setup narrow","type":"text"}]},{"type":"paragraph","content":[{"text":"When the request is really about platform wiring, answer only:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"where the config lives","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"how ","type":"text"},{"text":"agentation-mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" is registered","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"how pending annotations enter the agent loop","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"how to verify the setup","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Push the platform-specific config blocks into the references instead of bloating the main workflow.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Scripts","type":"text"}]},{"type":"paragraph","content":[{"text":"Prefer the bundled scripts before retyping long commands:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Script","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"scripts/setup-agentation-mcp.sh","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Register the MCP bridge for supported agents","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"scripts/verify-loop.sh","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Validate annotation queue / ACK → RESOLVE style watch-loop behavior","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 1: Human reviewer wants exact UI feedback","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt: \"I can point at the broken checkout button, but I don't want to describe selectors manually.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Expected behavior: choose ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":", recommend copy-paste review or sync mode, keep browser-runtime choice separate.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 2: Browser verification is the real job","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt: \"Run a repeatable headless UI regression check and compare the results.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Expected behavior: route to ","type":"text"},{"text":"browser-harness","type":"text","marks":[{"type":"code_inline"}]},{"text":", not ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":", unless human annotation becomes a follow-up step.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 3: Logged-in browser reuse","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt: \"Use the browser I'm already signed into and let me annotate a billing page issue.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Expected behavior: route the browser runtime to ","type":"text"},{"text":"playwriter","type":"text","marks":[{"type":"code_inline"}]},{"text":", then use ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the annotation packet.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 4: Planning review, not UI review","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt: \"Open the generated plan in a browser so I can approve or reject steps before coding starts.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Expected behavior: route to ","type":"text"},{"text":"plannotator","type":"text","marks":[{"type":"code_inline"}]},{"text":", because the artifact is a plan/diff rather than a rendered UI issue.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best practices","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pick the browser/runtime lane first; ","type":"text"},{"text":"agentation","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the feedback bridge, not every browser tool.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer one annotation mode at a time instead of mixing copy-paste, watch loop, and platform setup in a single answer.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep the first integration minimal; only add hooks, callbacks, or webhooks when the workflow needs them.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-verify after fixes with the same review lane that produced the annotation.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treat exact UI feedback as the deliverable — not a giant dump of install permutations.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Route out aggressively when the task is really plan review, fresh-browser verification, or running-browser reuse.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"paragraph","content":[{"text":"Deep-dive docs in this skill:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"modes-and-routing","type":"text","marks":[{"type":"link","attrs":{"href":"./references/modes-and-routing.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"platform-setup-and-hooks","type":"text","marks":[{"type":"link","attrs":{"href":"./references/platform-setup-and-hooks.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"watch-loop-and-self-driving","type":"text","marks":[{"type":"link","attrs":{"href":"./references/watch-loop-and-self-driving.md","title":null}}]}]}]}]},{"type":"paragraph","content":[{"text":"Primary sources:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://github.com/benjitaylor/agentation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://agentation.com","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.npmjs.com/package/agentation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.npmjs.com/package/agentation-mcp","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Metadata","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version: 1.1.0","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Last updated: 2026-04-15","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scope: exact rendered-UI feedback packets, watch loops, and platform handoff for coding agents","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"agentation","author":"@skillopedia","source":{"stars":22,"repo_name":"oh-my-skills","origin_url":"https://github.com/akillness/oh-my-skills/blob/HEAD/.agent-skills/agentation/SKILL.md","repo_owner":"akillness","body_sha256":"48f9bcb5e9bcf3b71215e4ff41708251f88e5e6014b6a4ca6266db2b4e9ad63f","cluster_key":"35fcc5ddc7a3a4e9cb95b7d7ebf2edb512b677ede98998c01ad39d33f4ba74c5","clean_bundle":{"format":"clean-skill-bundle-v1","source":"akillness/oh-my-skills/.agent-skills/agentation/SKILL.md","attachments":[{"id":"c0fc2a37-7e96-5d38-a95c-d523dedbe905","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c0fc2a37-7e96-5d38-a95c-d523dedbe905/attachment.toon","path":"SKILL.toon","size":576,"sha256":"1c81b4f2d2ede49168198243892911794f9dea51908d6a5382ac5f5928dd619d","contentType":"text/plain; charset=utf-8"},{"id":"d3dec320-534f-5aec-9d7b-4a792d36e652","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d3dec320-534f-5aec-9d7b-4a792d36e652/attachment.json","path":"evals/evals.json","size":2166,"sha256":"e9dd528a2340fe5ada7003fa846683752bea3c1e92f17b93678366d9b3ebcd5f","contentType":"application/json; charset=utf-8"},{"id":"7ebe92da-207b-56f2-afff-162a2893c9e1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7ebe92da-207b-56f2-afff-162a2893c9e1/attachment.md","path":"references/modes-and-routing.md","size":2392,"sha256":"38f15364afef010bb64d2d08bf256b232d9e45f3ab82873720d12dd24a779135","contentType":"text/markdown; charset=utf-8"},{"id":"39ff47ba-0cba-5a51-8e2d-109628dc4d22","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/39ff47ba-0cba-5a51-8e2d-109628dc4d22/attachment.md","path":"references/platform-setup-and-hooks.md","size":1999,"sha256":"b8366b942165cf5dd0d193f3ce0455e26a28c09ed17908259f8dfe86d0bb4380","contentType":"text/markdown; charset=utf-8"},{"id":"d82ca365-8d5b-59dd-959d-38de640e5006","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d82ca365-8d5b-59dd-959d-38de640e5006/attachment.md","path":"references/watch-loop-and-self-driving.md","size":1647,"sha256":"3302bff69baff238d86d6c04971c65c466d16ac35b13cbf774adf7b0ee506453","contentType":"text/markdown; charset=utf-8"},{"id":"20137c67-d9e4-5ef0-8d19-dc6aa7a07b37","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/20137c67-d9e4-5ef0-8d19-dc6aa7a07b37/attachment.sh","path":"scripts/setup-agentation-mcp.sh","size":7342,"sha256":"f345d8c2b6fdb8e5161f4b1be1f293d7540039939939f2dbadc82cdbc1610f03","contentType":"application/x-sh; charset=utf-8"},{"id":"9f7637fb-3117-5044-b6cf-6e1ebb537b6f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9f7637fb-3117-5044-b6cf-6e1ebb537b6f/attachment.sh","path":"scripts/verify-loop.sh","size":7151,"sha256":"456010bee0beeb5aa687f8ec9f7d5cf34f47513584eb5b4f75ebac7ce84250ca","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"5ad02641e1099d1e8ecda62125b99adce8efcd60bc605e080ec41cce792cd558","attachment_count":7,"text_attachments":6,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":1,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":".agent-skills/agentation/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"browser-automation-scraping","category_label":"Browser"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"browser-automation-scraping","metadata":{"tags":"ui-feedback, browser-annotation, visual-feedback, mcp, react, ai-agent, design-review, css-selector","source":"benjitaylor/agentation","keyword":"agentation","version":"1.1.0","platforms":"Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Windsurf, ChatGPT"},"import_tag":"clean-skills-v1","description":"Capture exact rendered-UI feedback and hand it to an agent as selectors, element paths, and structured annotation packets. Use when a human needs to point at a real UI issue, run a sync/watch loop, or wire browser feedback into Claude Code, Codex, Gemini CLI, or OpenCode. Not for fresh-session browser verification (`browser-harness`), running-browser reuse (`playwriter`), or plan/diff approval (`plannotator`).\n","allowed-tools":"Read Write Bash Grep Glob","compatibility":"React 18+, Node.js 18+"}},"renderedAt":1782982093267}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.