Stelz browser
Stelz runs persistent browser profiles. You control them through the tools of one stelz mcp connection.
Shared MCP tools is the tool contract, including the control-handle rules.
Requires Stelz 0.6.0 or later. Check with stelz --version.
Install
When a user sends a link to this file and asks you to install it:
- Save this file as
stelz-browser/SKILL.md in your client's skill folder. See Connect your agent.
- If
stelz is missing or older than 0.6.0, or the Stelz MCP tools are missing, follow Agent setup.
Run stelz setup only in a terminal. MCP tools do not download prerequisites.
Do a browser task
Call profile_list({}). Select the profile ID that the task needs.
If that profile is missing, call profile_create({profileId}).
If its browser is stopped, call profile_start({profileId}).
Check readiness in the start result or in profile_status({profileId}):
phase is "ready".
- If
verificationRequired is true, verificationStatus is "verified" and exitIp agrees with the intended route.
If a check fails, do not acquire. Report location to the user and go to Recover.
Call profile_acquire({profileId}). Keep the returned controlHandle with its profile ID. Never write it in reports, configuration, or handoff notes.
Send both fields in each later call for that profile.
Call tab_list to find the startup page. Navigate that tab.
Work on the page with these rules:
- Read a full
tab_snapshot on a new tab, after a navigation, or after resume.
- Click, type, select, and press return a diff, or the full page with
baseline: true. Read it to check the result. Do not call tab_snapshot after an action. If the result says The action completed, the read of the page failed. Read tab_snapshot. Do not repeat the action.
- Target elements by role and name (
target). Use a ref only if the last result showed it.
- If an expected change is not in the diff yet, use
tab_wait. Do not poll with snapshots.
- Use
scope or contains on long pages.
- Ask for a screenshot only when the layout matters.
See Targets, Refs, Observe, Wait, and Snapshots.
When you finish, or before another agent takes over, call profile_release({profileId, controlHandle}). Leave the browser open.
Rules
- Never repeat an action that may have reached the page or that stopped before it finished. Read a fresh snapshot first.
- If another controller holds the profile, do not start another browser or create another profile. Ask the operator to release it.
- For changes that the tools cannot make, ask the operator to use the CLI or UI.
tab_evaluate and tab_init_script work only on a profile that the operator allowed, and only when the connection lists them. If a call says that scripts are off, ask the operator to allow scripts in the CLI or UI. Never try to change this setting. After a tab_evaluate timeout, read a snapshot. Do not run the script again.
- Before you type long text, read Typing to select a
tab_type mode.
- Tell the operator about location warnings in
location.evidence. Never claim a physical location from status, and never bypass a location blocker. See Managed location data.
- If status shows
restartToUpdate: true, tell the user. Restart only when the user asks. Release before the restart, and acquire again after it. See Restart to update.
Human authentication
- When a page needs a person, for example to sign in, call
profile_pause({profileId, controlHandle}).
- Tell the operator what to do in that browser window. Find a profile's windows tells them how to find it.
- Wait for the operator. Then call
profile_resume({profileId, controlHandle}).
- After the resume, read a full
tab_snapshot before the next action.
Do not try to bypass an authentication challenge.
Recover
After an error, call profile_status({profileId}) before another browser action. Then use the procedure for the problem:
Diagnostics, stop, and recovery are operator actions. Never send signals to processes or work around uncertain process ownership.
1---2name: stelz-browser3description: Do browser tasks in persistent Stelz profiles through the Stelz MCP tools (`profile_*` and `tab_*`), with exclusive control, verified readiness, and human authentication. Also use it to install Stelz when a user sends a link to this skill.4metadata:5 source: https://skillmd.com/skills/souljorje/stelz-browser6---78# Stelz browser910Stelz runs persistent browser profiles. You control them through the tools of one `stelz mcp` connection.11[Shared MCP tools](https://github.com/souljorje/stelz/blob/main/docs/mcp.md) is the tool contract, including the control-handle rules.12Requires Stelz 0.6.0 or later. Check with `stelz --version`.1314## Install1516When a user sends a link to this file and asks you to install it:17181. Save this file as `stelz-browser/SKILL.md` in your client's skill folder. See [Connect your agent](https://github.com/souljorje/stelz/blob/main/docs/clients.md).192. If `stelz` is missing or older than 0.6.0, or the Stelz MCP tools are missing, follow [Agent setup](https://github.com/souljorje/stelz/blob/main/docs/bootstrap.md).2021Run `stelz setup` only in a terminal. MCP tools do not download prerequisites.2223## Do a browser task24251. Call `profile_list({})`. Select the profile ID that the task needs.262. If that profile is missing, call `profile_create({profileId})`.273. If its browser is stopped, call `profile_start({profileId})`.284. Check readiness in the start result or in `profile_status({profileId})`:29 - `phase` is `"ready"`.30 - If `verificationRequired` is true, `verificationStatus` is `"verified"` and `exitIp` agrees with the intended route.3132 If a check fails, do not acquire. Report `location` to the user and go to [Recover](#recover).335. Call `profile_acquire({profileId})`. Keep the returned `controlHandle` with its profile ID. Never write it in reports, configuration, or handoff notes.34 Send both fields in each later call for that profile.356. Call `tab_list` to find the startup page. Navigate that tab.367. Work on the page with these rules:37 1. Read a full `tab_snapshot` on a new tab, after a navigation, or after resume.38 2. Click, type, select, and press return a diff, or the full page with `baseline: true`. Read it to check the result. Do not call `tab_snapshot` after an action. If the result says `The action completed`, the read of the page failed. Read `tab_snapshot`. Do not repeat the action.39 3. Target elements by role and name (`target`). Use a ref only if the last result showed it.40 4. If an expected change is not in the diff yet, use `tab_wait`. Do not poll with snapshots.41 5. Use `scope` or `contains` on long pages.42 6. Ask for a screenshot only when the layout matters.4344 See [Targets](https://github.com/souljorje/stelz/blob/main/docs/mcp.md#targets), [Refs](https://github.com/souljorje/stelz/blob/main/docs/mcp.md#refs), [Observe](https://github.com/souljorje/stelz/blob/main/docs/mcp.md#observe), [Wait](https://github.com/souljorje/stelz/blob/main/docs/mcp.md#wait), and [Snapshots](https://github.com/souljorje/stelz/blob/main/docs/mcp.md#snapshots).458. When you finish, or before another agent takes over, call `profile_release({profileId, controlHandle})`. Leave the browser open.4647## Rules4849- Never repeat an action that may have reached the page or that stopped before it finished. Read a fresh snapshot first.50- If another controller holds the profile, do not start another browser or create another profile. Ask the operator to release it.51- For changes that the tools cannot make, ask the operator to use the CLI or UI.52- `tab_evaluate` and `tab_init_script` work only on a profile that the operator allowed, and only when the connection lists them. If a call says that scripts are off, ask the operator to allow scripts in the CLI or UI. Never try to change this setting. After a `tab_evaluate` timeout, read a snapshot. Do not run the script again.53- Before you type long text, read [Typing](https://github.com/souljorje/stelz/blob/main/docs/configuration/typing.md) to select a `tab_type` mode.54- Tell the operator about location warnings in `location.evidence`. Never claim a physical location from status, and never bypass a location blocker. See [Managed location data](https://github.com/souljorje/stelz/blob/main/docs/configuration/network.md#managed-location-data).55- If status shows `restartToUpdate: true`, tell the user. Restart only when the user asks. Release before the restart, and acquire again after it. See [Restart to update](https://github.com/souljorje/stelz/blob/main/docs/troubleshooting/setup.md#restart-to-update).5657## Human authentication58591. When a page needs a person, for example to sign in, call `profile_pause({profileId, controlHandle})`.602. Tell the operator what to do in that browser window. [Find a profile's windows](https://github.com/souljorje/stelz/blob/main/docs/ui.md#find-a-profiles-windows) tells them how to find it.613. Wait for the operator. Then call `profile_resume({profileId, controlHandle})`.624. After the resume, read a full `tab_snapshot` before the next action.6364Do not try to bypass an authentication challenge.6566## Recover6768After an error, call `profile_status({profileId})` before another browser action. Then use the procedure for the problem:6970- [IP verification failed](https://github.com/souljorje/stelz/blob/main/docs/troubleshooting/network.md#ip-verification-failed). After the operator repairs the route, call `profile_recheck({profileId, controlHandle})`.71- [Missing or stale control handle](https://github.com/souljorje/stelz/blob/main/docs/troubleshooting/control.md#missing-or-stale-control-handle).72- [Browser action or IP check timed out](https://github.com/souljorje/stelz/blob/main/docs/troubleshooting/lifetime-and-state.md#browser-action-or-ip-check-timed-out).73- Other problems: [Troubleshooting](https://github.com/souljorje/stelz/blob/main/docs/troubleshooting/index.md).7475Diagnostics, stop, and recovery are operator actions. Never send signals to processes or work around uncertain process ownership.