Install the agent skill

The Santiago agent skill is a small bundle of Markdown instructions that teaches an AI coding agent (Claude Code, Cursor, Cline, Continue, Windsurf, and others) how to drive a running Santiago browser profile through the local HTTP API. Install it once at the user level and any agent that supports skills/rules can automate your profiles. See Automation overview for the big picture, or jump straight to Launch profiles and the HTTP API.

What the skill is

The skill ships as a .tar.gz archive containing:

File / directory	Purpose
SKILL.md	The skill definition: frontmatter (name, description), automation instructions, and triggers.
references/	Supporting docs the skill loads on demand (full API reference and automation guides).
README.md	Install instructions for the agent. Do not copy this into the install location.

Once installed, the skill drives the local daemon on your machine. It does not talk to any cloud server — every request goes to http://localhost:7891. All fingerprint spoofing (canvas, WebGL, audio, fonts, WebRTC, etc.) is handled automatically by the running profile, and when the profile has humanize enabled, Camoufox adds bezier-curve cursor movements to every action.

The skill is stateless

There is no migration or local state to manage. Updating is just replacing the files in the install directory with the contents of a newer archive.

Copy-paste install prompt

The fastest way to install: paste this message into any AI coding agent. It downloads the archive, extracts it, reads the bundled README.md, and follows the instructions to place the files in the right directory for that agent.

Install prompt — paste into Claude Code / Cursor / Cline / etc.

Install the Santiago Browser automation skill from:
https://downloads.santiago-browser.com/skill/latest/santiago-browser-skill.tar.gz

Download this archive, extract it, read README.md inside and follow its instructions. If it's already installed, just update the files.

The archive URL always points at the latest release:

Skill archive (latest)

https://downloads.santiago-browser.com/skill/latest/santiago-browser-skill.tar.gz

Manual install

If you prefer to install by hand, download and extract the archive, then copy SKILL.md and the references/ directory into your agent’s global skills/rules location in the current user’s home directory.

Download and extract

curl -fsSL https://downloads.santiago-browser.com/skill/latest/santiago-browser-skill.tar.gz \
  -o santiago-browser-skill.tar.gz
tar -xzf santiago-browser-skill.tar.gz
ls    # SKILL.md  references/  README.md

Install for Claude Code

mkdir -p ~/.claude/skills/santiago-browser
cp -R SKILL.md references ~/.claude/skills/santiago-browser/

Install globally, never project-local

Always install into the user-level (global) skills/rules directory, not a project’s local rules. Preserve the structure — references/ must stay a subdirectory next to SKILL.md. Do not copy README.md into the install location.

Install paths per agent

Agent	Install path
Claude Code	~/.claude/skills/santiago-browser/
Cursor	~/.cursor/rules/santiago-browser/
Cline / Continue / Windsurf	the agent’s custom-instructions / rules directory
Other	your runtime’s global Markdown skills/rules directory (user-level, not project-level)

If you are unsure where your runtime stores global skills, ask before copying.

Verify the install

After copying, open SKILL.md at the install location and confirm the frontmatter is intact:

SKILL.md frontmatter

name: santiago-browser
description: Control a running Santiago anti-detect browser profile via HTTP API. Use when the user needs to navigate pages, fill forms, click buttons, take screenshots, extract data, or automate any browser task inside a Santiago profile.

Updating and uninstalling

• Update: replace the contents of the install directory with the files from a newer archive. No migration needed.
• Uninstall: delete the santiago-browser/ directory from the install location.

How the skill activates

The skill activates automatically when you ask the agent to automate a Santiago browser profile — navigate pages, fill forms, click, screenshot, extract data, and so on. Two things must be true first:

1. The Santiago app is running and the daemon is listening on http://localhost:7891. The skill only ever calls localhost — the agent does not need any cloud credentials.
2. A target profile is launched (status running). Launch it from the app UI or via the API (see Launch profiles). If the profile is not running, automation calls return 404 PROFILE_NOT_RUNNING.

The skill expects the profile ID in an environment variable named $PROFILE. An embedded agent receives the profile ID in its system prompt; an external agent should ask you for the ID or list available profiles and let you pick one.

Find a profile ID

curl -s localhost:7891/api/profiles | jq '.data[] | {id, name, status}'

Pin the profile for the session

PROFILE=<profile-id>

Strict profile scope

The skill is instructed to work strictly inside the profile you specify. It will not switch to, stop, or launch a different profile on its own — even if another profile seems to fit the task better. If the specified profile is wrong (wrong region/language, not running), the agent stops and asks you rather than picking a different one.

Every response from the daemon and automation endpoints follows the same envelope:

Response envelope

{ "ok": true, "data": { } }

Error envelope

{ "ok": false, "error": { "code": "PROFILE_NOT_RUNNING", "message": "..." } }

Your first automation in 5 minutes

This walkthrough takes you from a launched profile to a filled-and-submitted form. The daemon base is http://localhost:7891/api; the automation base is http://localhost:7891/api/automation/$PROFILE/<action>.

1. Confirm a profile is running

Check status

curl -s localhost:7891/api/profiles/$PROFILE/status | jq .data.status

If the status is not running, launch it (this returns an async 202 and needs an active license plus a free concurrent slot):

Launch the profile

curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

Profile statuses are idle, launching, running, and stopping; a profile in use on another device shows as locked.

2. Navigate to a page

Navigate

curl -s localhost:7891/api/automation/$PROFILE/navigate -X POST \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

3. Snapshot the page

Take one snapshot to understand the page and identify every element you need before acting.

Snapshot

curl -s localhost:7891/api/automation/$PROFILE/snapshot -X POST | jq -r .data.snapshot

4. Fill the form and submit

fill-page is the primary endpoint for forms: it fills text inputs and combobox dropdowns and submits, all in one coordinate-based call that works on animated/transitioning pages.

Fill and submit a form

curl -s localhost:7891/api/automation/$PROFILE/fill-page -X POST \
  -H 'Content-Type: application/json' -d '{
    "fields": [
      {"selector": "#email", "value": "user@example.com"},
      {"selector": "#password", "value": "secret123"},
      {"selector": "[role=combobox]", "value": "Option A", "type": "combobox"}
    ],
    "submit": {"text": "Sign in"},
    "waitAfterSubmit": 2000
  }'

5. Re-snapshot the result

The page has changed, so any element refs from step 3 are now stale — take a fresh snapshot to read the result.

Re-snapshot after submit

curl -s localhost:7891/api/automation/$PROFILE/snapshot -X POST | jq -r .data.snapshot

That is the full loop: navigate → snapshot → act → re-snapshot. The agent repeats it as needed.

Good habits the skill follows

These rules are built into the skill, but they are worth knowing so you understand what the agent is doing:

• One snapshot, one batch. Take a single snapshot, identify all targets, then send one batch of actions. Do not re-snapshot between actions on the same page — only after navigation, form submission to a new page, or a modal that replaces content.
• evaluate is read-only. The skill uses evaluate only to read the DOM (titles, text, bounding rects). It never interacts via evaluate (.click(), setting .value, form submit) because synthetic events report isTrusted: false and bypass humanize, which antibot systems flag. To interact with an element found via evaluate, the skill reads its coordinates and uses mouse/click {x, y}.
• No blind sleep. Playwright auto-waits and the batch endpoint adds random 80–250 ms jitter between actions, so the skill never wraps calls in sleep. When it genuinely needs to wait for a signal it uses the wait action with text/selector/state.
• Use the bundled references. The skill consults its bundled references/ for tested automation patterns and known traps before acting.

For the full endpoint list and field reference, see the HTTP API and API reference. For reliability tips, see Best practices.

Requirements and troubleshooting

• A paid plan is required. The daemon checks your license before launching or creating profiles. Plans: Starter ($9/mo, 3 profiles), Pro ($59/mo, 40 profiles), Agency ($149/mo, 300 profiles + team). There is no free trial — see Plans.
• Supported platforms: macOS (Intel and Apple Silicon), Windows, and Linux (AppImage). See Platforms.

Problem	Fix
404 PROFILE_NOT_RUNNING	The profile must be launched first (via the app UI or POST /api/profiles/$PROFILE/launch).
Skill doesn’t activate	Confirm SKILL.md is in the correct user-level path for your agent and its frontmatter is intact.
Connection refused on localhost:7891	The Santiago app (and its daemon) is not running. Start the app.
Agent picks the wrong profile	Set $PROFILE explicitly and tell the agent which profile to use — it will not switch on its own.

Need help?

If you get stuck, reach support on Telegram at t.me/santiago_browser, or browse Common errors and the FAQ.