Встановлення агентського скіла

Агентський скіл Santiago — це невеликий набір інструкцій у форматі Markdown, який навчає AI-агента для написання коду (Claude Code, Cursor, Cline, Continue, Windsurf та інших) керувати запущеним браузерним профілем Santiago через локальний HTTP API. Встановіть його один раз на рівні користувача, і будь-який агент із підтримкою скілів/правил зможе автоматизувати ваші профілі. Загальну картину дивіться в Огляді автоматизації, або переходьте одразу до Запуску профілів та HTTP API.

Що таке скіл

Скіл постачається як архів .tar.gz, що містить:

Файл / каталог	Призначення
`SKILL.md`	Визначення скіла: фронтматер (`name`, `description`), інструкції з автоматизації та тригери.
`references/`	Допоміжна документація, яку скіл завантажує за потреби (повний довідник API та посібники з автоматизації).
`README.md`	Інструкції зі встановлення для агента. Не копіюйте цей файл у місце встановлення.

Після встановлення скіл керує локальним демоном на вашій машині. Він не звертається до жодного хмарного сервера — кожен запит іде на http://localhost:7891. Уся підміна відбитка (canvas, WebGL, аудіо, шрифти, WebRTC тощо) виконується автоматично запущеним профілем, а коли в профілі увімкнено гуманізацію, Camoufox додає рухи курсора за кривими Безьє до кожної дії.

Промпт для встановлення (копіювати й вставити)

Найшвидший спосіб встановлення: вставте це повідомлення в будь-якого AI-агента для написання коду. Він завантажить архів, розпакує його, прочитає вкладений README.md і виконає інструкції, щоб розмістити файли в потрібному каталозі для цього агента.

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.

URL архіву завжди вказує на останній реліз:

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

Встановлення вручну

Якщо ви хочете встановити вручну, завантажте та розпакуйте архів, потім скопіюйте SKILL.md і каталог references/ у глобальний каталог скілів/правил вашого агента в домашній теці поточного користувача.

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

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

Шляхи встановлення для кожного агента

Агент	Шлях встановлення
Claude Code	`~/.claude/skills/santiago-browser/`
Cursor	`~/.cursor/rules/santiago-browser/`
Cline / Continue / Windsurf	каталог користувацьких інструкцій / правил агента
Інше	глобальний каталог скілів/правил у форматі Markdown вашого середовища (на рівні користувача, не проєкту)

Якщо ви не впевнені, де ваше середовище зберігає глобальні скіли, запитайте перед копіюванням.

Перевірка встановлення

Після копіювання відкрийте SKILL.md у місці встановлення та переконайтесь, що фронтматер не пошкоджено:

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.

Оновлення та видалення

Оновлення: замініть вміст каталогу встановлення файлами з новішого архіву. Жодних міграцій не потрібно.
Видалення: видаліть каталог santiago-browser/ із місця встановлення.

Як активується скіл

Скіл активується автоматично, коли ви просите агента автоматизувати браузерний профіль Santiago — переходити по сторінках, заповнювати форми, клікати, робити скріншоти, витягувати дані тощо. Спершу мають виконуватись дві умови:

Застосунок Santiago запущено, і демон слухає на http://localhost:7891. Скіл звертається виключно до localhost — агенту не потрібні жодні хмарні облікові дані.
Цільовий профіль запущено (статус running). Запустіть його з інтерфейсу застосунку або через API (див. Запуск профілів). Якщо профіль не запущено, виклики автоматизації повертають 404 PROFILE_NOT_RUNNING.

Скіл очікує ID профілю у змінній середовища з назвою $PROFILE. Вбудований агент отримує ID профілю у своєму системному промпті; зовнішній агент має запитати у вас ID або вивести список доступних профілів і дати вам обрати один із них.

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

PROFILE=<profile-id>

Кожна відповідь демона та ендпоінтів автоматизації має однаковий формат-обгортку:

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

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

Ваша перша автоматизація за 5 хвилин

Цей покроковий приклад проведе вас від запущеного профілю до заповненої та відправленої форми. Базова адреса демона — http://localhost:7891/api; базова адреса автоматизації — http://localhost:7891/api/automation/$PROFILE/<action>.

1. Переконайтесь, що профіль запущено

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

Якщо статус не running, запустіть профіль (це повертає асинхронний 202 і потребує активної ліцензії та вільного конкурентного слоту):

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

Статуси профілю — idle, launching, running та stopping; профіль, що використовується на іншому пристрої, показується як locked.

2. Перейдіть на сторінку

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

3. Зробіть знімок сторінки

Зробіть один знімок, щоб зрозуміти сторінку та визначити кожен елемент, який вам знадобиться, перш ніж діяти.

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

4. Заповніть форму та відправте

fill-page — основний ендпоінт для форм: він заповнює текстові поля та випадні списки комбобоксів і відправляє форму одним викликом на основі координат, що працює навіть на анімованих сторінках чи сторінках з переходами.

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. Зробіть повторний знімок результату

Сторінка змінилася, тож будь-які посилання на елементи з кроку 3 тепер застаріли — зробіть свіжий знімок, щоб прочитати результат.

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

Ось і весь цикл: перехід → знімок → дія → повторний знімок. Агент повторює його за потреби.

Хороші звички, яких дотримується скіл

Ці правила вбудовані в скіл, але їх варто знати, щоб розуміти, що робить агент:

Один знімок — один пакет. Зробіть єдиний знімок, визначте всі цілі, потім надішліть один пакет дій. Не робіть повторний знімок між діями на одній сторінці — лише після переходу, відправки форми на нову сторінку чи модального вікна, що замінює вміст.
evaluate лише для читання. Скіл використовує evaluate тільки для читання DOM (заголовки, текст, обмежувальні прямокутники). Він ніколи не взаємодіє через evaluate (.click(), встановлення .value, відправка форми), бо синтетичні події повертають isTrusted: false та обходять гуманізацію, що відстежують антибот-системи. Щоб взаємодіяти з елементом, знайденим через evaluate, скіл зчитує його координати та використовує mouse/click {x, y}.
Жодного сліпого sleep. Playwright автоматично очікує, а пакетний ендпоінт додає випадковий джитер 80–250 мс між діями, тож скіл ніколи не обгортає виклики у sleep. Коли йому справді потрібно дочекатися сигналу, він використовує дію wait з text/selector/state.
Використовуйте вкладені довідники. Перед діями скіл звіряється зі своїм вкладеним каталогом references/, де є перевірені патерни автоматизації та відомі пастки.

Повний перелік ендпоінтів і довідник полів дивіться в HTTP API та Довіднику API. Поради щодо надійності дивіться в Найкращих практиках.

Вимоги та усунення несправностей

Потрібен платний тариф. Демон перевіряє вашу ліцензію перед запуском чи створенням профілів. Тарифи: Starter ($9/міс, 3 профілі), Pro ($59/міс, 40 профілів), Agency ($149/міс, 300 профілів + команда). Безкоштовного періоду немає — див. Тарифи.
Підтримувані платформи: macOS (Intel та Apple Silicon), Windows та Linux (AppImage). Див. Платформи.

Проблема	Рішення
`404 PROFILE_NOT_RUNNING`	Профіль потрібно спершу запустити (через інтерфейс застосунку або `POST /api/profiles/$PROFILE/launch`).
Скіл не активується	Переконайтесь, що `SKILL.md` лежить за правильним шляхом на рівні користувача для вашого агента, а його фронтматер не пошкоджено.
Connection refused на `localhost:7891`	Застосунок Santiago (і його демон) не запущено. Запустіть застосунок.
Агент обирає не той профіль	Задайте `$PROFILE` явно та скажіть агенту, який профіль використовувати — він не перемкнеться самостійно.