name	browse
triggers	["browse","website","web page","scrape","screenshot","url","http","visit","open page","fetch page","web search","look up","check the site"]
description	Web browsing and scraping via headless browser
cli	true
companion_skills	["untrusted_input"]
requires_capability	["browser"]

Web Browsing

Headless browser for fetching pages that need JavaScript rendering or bot detection bypass. For simple static pages or APIs, prefer curl or httpx — they're faster.

Reach for render first. It returns the page as markdown, so headings, list position and link URLs arrive together — which is what lets you tell an article link from footer chrome. get returns flattened text with every URL stripped out, and links returns a position-stripped list where nav items and articles look identical. Use those two only when you specifically want plain text or a bare link list.

Commands

# Render a page to markdown — the default read path
istota-skill browse render "https://example.com"                    # whole page (hubs, index pages)
istota-skill browse render "https://example.com/story" --mode article  # main content only (article bodies)
istota-skill browse render "https://example.com" --keep-session
istota-skill browse render --session <id>                           # re-render what a session already holds
istota-skill browse render "https://example.com" --max-chars 250000 # raise the markdown budget

# Fetch a page as plain text + a flat link list
istota-skill browse get "https://example.com"
istota-skill browse get "https://example.com" --keep-session --timeout 60
istota-skill browse get "https://example.com" --wait-for "article.content"

# Navigate within an existing session (preserves cookies, referrer, state)
istota-skill browse get "https://example.com/page2" --session <id>
istota-skill browse render "https://example.com/page2" --session <id>

# Fetch only links (no page text)
istota-skill browse links "https://example.com"
istota-skill browse links "https://example.com" --selector "nav a"

# Screenshot
istota-skill browse screenshot "https://example.com" -o /tmp/page.png
istota-skill browse screenshot --session <id> -o /tmp/page.png --full-page

# Extract by CSS selector
istota-skill browse extract "https://example.com" -s "article"
istota-skill browse extract --session <id> -s ".price" --limit 50 --max-chars 80000

# Interact with existing session (click, fill forms, scroll)
istota-skill browse interact <id> --click ".button"
istota-skill browse interact <id> --fill "#email=user@example.com"
istota-skill browse interact <id> --scroll down --scroll-amount 1000

# Close session
istota-skill browse close <id>

Output format

render:

{"status": "ok", "url": "...", "title": "...", "mode": "full", "requested_mode": "article",
 "markdown": "## Top stories\n\n* [Headline](https://site.example/2026/07/26/story.html)\n...",
 "chars": 20539, "truncated": false, "notes": ["..."], "session_id": "..."}

Every URL in the markdown is already absolute — use them exactly as given. mode is what actually ran, which can differ from what you asked for: a URL shaped like a section front is rendered in full unless the page turns out to hold one dominant article, because isolating "the article" on an index page throws the headline grid away; a page with no article in it falls back to full too. Either way notes says what happened. truncated means you hit --max-chars; re-run with a bigger budget or --mode article.

get:

{"status": "ok", "title": "...", "url": "...", "text": "...", "links": [{"text": "...", "href": "..."}], "session_id": "..."}

links here are relative or absolute exactly as the page wrote them. session_id is only present with --keep-session. extract returns {"status": "ok", "selector": "...", "count": N, "elements": [{"text": "...", "html": "...", "href": "...", ...}]}.

Researching articles from news sites

Render the hub/index page with --keep-session:
```
istota-skill browse render "https://www.theguardian.com/world" --keep-session
```
The markdown gives you headlines with their URLs, under the section headings they sit beneath. Pick the articles you want.
Render each article in the same session, in article mode:
```
istota-skill browse render "https://www.theguardian.com/world/2026/jul/26/story" --session <id> --mode article
```
Same tab, so cookies, referrer and session state carry over. Article mode drops nav, ads and related-links so you get the body.
Close the session when done:
```
istota-skill browse close <session_id>
```

This works the same on every site — Reuters, Le Monde, Der Spiegel, AP, BBC, NPR — with no per-site knowledge. If a hub looks like nothing but section names, you are almost certainly looking at get output rather than render output.

When a hub still looks empty

Check you used render, not get. A JS-rendered index page reads as bare section names through get because the URLs are gone.
Scroll for click-to-load / infinite-scroll hubs, then re-render the same session:
```
istota-skill browse interact <session_id> --scroll down --scroll-amount 2000
istota-skill browse render --session <session_id>
```
Max 3 scroll rounds — stop and use what you have.
Only then reach for a CSS selector. extract / links --selector still work when you know a site's markup, but selectors rot on every redesign — treat them as a last resort, not the first move:
```
istota-skill browse links "https://www.theguardian.com/world" --selector "a[data-link-name='article']"
```
Common patterns: a[data-link-name], a[data-testid], a[data-link-type], h3 a, article a.

Rules

Run browse commands yourself. Always execute istota-skill browse directly in Bash. Never delegate browsing to a subtask or subagent — they lose the session context and skill instructions, leading to repeated failures.

URLs: Never construct, guess, or modify URLs. Take them from render markdown (already absolute) or from a links/extract href (combine with the site origin when relative). If a fetch fails, skip it — do not retry with a guessed variant.

Failures: If a site returns an error, empty content, captcha, or no session_id — try once more. If it fails twice, skip that site and use an alternative source.

No debugging: Never read the browse skill source code, inspect docker containers, curl the browser API directly, test session internals, or debug the browser infrastructure. If the CLI fails, move on.

Scrolling: Max 3 rounds. Infinite feeds never end.

Captcha handling

If a response has "status": "captcha", tell the user and provide the vnc_url. Wait for them to solve it, then retry with --session <session_id>.

Fallback for web tools

When WebSearch or WebFetch aren't available, use istota-skill browse as a fallback — it always works since it runs {BOT_NAME}'s own headless browser.

Notes

Sessions expire after 10 minutes of inactivity — always close them when done
Anti-fingerprinting (stealth mode) is enabled by default
Budgets are caller-raisable: render --max-chars (default 100,000), get --max-chars / --max-links (50,000 / 100), extract --max-chars / --limit (25,000 per element / 20 elements)