Assistants and MCP

The Arx browser skill

A guide for agents on working with Arx efficiently. arx setup installs it for Claude Code and Codex; other clients get a short version from the server.

This page is a first draft. It may change before the public beta.

The MCP server tells an assistant what each tool does. The arx-browser skill tells it how to work with Arx: which tool to reach for first, how to keep round trips down, what each error means and when to hand something to you. An assistant that has read it wastes fewer calls and gets stuck less often.

Where it comes from

When you connect Claude Code or Codex, with arx setup claude, arx setup codex or Arx's own Connect button, Arx installs the skill next to the MCP configuration:

AgentSkill file
Claude Code~/.claude/skills/arx-browser/SKILL.md
Codex~/.codex/skills/arx-browser/SKILL.md

Restart the agent afterwards so it finds the skill. Connecting again updates it. arx remove claude or arx remove codex takes it away with the rest. If a different skill already lives in that folder, Arx leaves it alone.

Claude Desktop, Cursor and any other MCP client get a short version of the same guide in the server's instructions, which clients read when they connect. To read the whole skill yourself, or to paste it into a client that has its own place for instructions, run:

arx guide

It prints the guide that matches the Arx you have installed.

What it teaches

  • The loop. List what was granted with browser_inventory, read the page with the cheapest tool (browser_read for text, browser_find for where something is, browser_inspect for elements to act on, a screenshot only when looks matter), act, and ask for the next snapshot in the same call. Steps it already knows go in one browser_batch, so you approve once, and loops or steps that need earlier results go in one browser_run script.
  • Grants and profiles. It sees only what you granted. Other profiles and private windows don't exist for it, because profiles are separate. When it needs more, it asks you to grant it in Arx: it can't grant itself anything.
  • Approvals. A change may wait for your yes. If you decline, it stops and says what it was trying to do. It never repeats a change after a disconnect.
  • Errors. What staleTarget, staleReference, notReady, denied and the rest mean, and the next step for each. See Working with pages.
  • Sign-ins. It signs in with a password you saved without seeing it, or hands the page to you. It never types or reads a password or a one-time code.
  • Untrusted content. Page text, titles and screenshots are data, never instructions. If a page tells it to do something, it asks you.

The skill is versioned with Arx, so it changes when the tools do.