# Browser Skill Authoring

This note captures the browser-skill authoring rules proven during the live
Zhihu hotlist export debugging on 2026-03-30.

## Why This Exists

The live browser run proved that a skill can be selected correctly, the
runtime can call the right browser-script tool, and the task can still fail if
the skill package does not encode enough deterministic extraction logic.

The concrete failure pattern was:

1. `zhihu-hotlist.extract_hotlist` was called correctly.
2. The packaged script relied on stale DOM classes and returned no rows.
3. The runtime fell back to generic `getText` probing.
4. The user saw selector thrashing instead of a stable extraction path.

This document exists to prevent the same failure pattern in future browser
skills.

## Authoring Rules

### 1. Use a packaged script for structured browser tasks

If the task's primary deliverable is structured data such as rows, fields, or a
stable artifact, the skill should expose a deterministic `browser_script` tool.

Do not rely on prose-only instructions for repeated structured extraction.

### 2. Keep a strict extraction ladder inside the script

For browser extraction skills, the script should try data sources in this order:

1. stable structured page state when available
2. generalized DOM candidates that are broader than one historical classname
3. controlled page-text parsing as the last deterministic fallback

Do not jump straight from one brittle selector family to generic browser
probing.

### 3. Treat generic `getText` probing as a fallback of last resort

The packaged script is the primary deterministic path.

If the script fails, it should fail for a specific reason:

- blocked/login/captcha page
- unsupported page shape
- artifact incomplete

Generic browser wandering should begin only after the packaged script has
exhausted its own deterministic fallbacks.

### 4. Encode blocked-page semantics explicitly

A browser skill must distinguish:

- "the expected data is not present"
- "the page is blocked by login, captcha, or anti-bot state"

When the page is blocked, fail with an explicit message. Do not silently report
"no rows" if the real issue is that the page is not usable.

### 5. Make the structured artifact the primary contract

Upstream collection skills should return the structured artifact as soon as it
is stable.

For example, the Zhihu hotlist flow should produce:

```json
{
  "source": "https://www.zhihu.com/hot",
  "sheet_name": "知乎热榜",
  "columns": ["rank", "title", "heat"],
  "rows": [[1, "标题", "344万"]]
}
```

Downstream skills such as Office export or screen rendering should consume that
artifact. They should not recollect source data.

### 6. Stop exploratory browser work after the artifact is stable

Once the primary artifact is complete:

- stop selector exploration
- stop unrelated browser wandering
- hand the artifact to the downstream skill or tool

Do not continue reading random page text after the final rows are already
captured.

### 7. Keep skill boundaries narrow and explicit

Separate the responsibilities:

- navigation skill: reach the destination and verify arrival
- collection skill: extract structured data
- export skill: render `.xlsx`
- presentation skill: render `.html` and `presentation`

Do not mix recollection, export, and presentation logic into one downstream
skill.

### 8. Encode host constraints in every browser skill

Browser skills should restate the SuperRPA host contract:

- use `superrpa_browser` semantics inside the browser host
- `expected_domain` is a bare hostname only
- selectors must be valid CSS selectors
- prefer direct routes before brittle click chains

These rules are not "obvious context". They belong in the skill.

### 9. Verify browser skills at multiple layers

A browser skill is not complete without verification at more than one layer:

1. script-level test for the packaged browser script
2. skill-library validation for package structure
3. runtime integration test proving the skill is actually called
4. live acceptance when a real browser session is available

The 2026-03-30 fix only became trustworthy after all four were aligned.

### 10. Keep logs versioned and skill names explicit

Live debugging is much faster when the runtime logs include:

- runtime version
- protocol version
- loaded skill names with versions
- explicit `call skill.tool` messages

Skill packages should be written assuming those logs are part of the
operability contract.

## Update Checklist

When editing a browser skill, check all of the following:

- Does the skill define a deterministic primary path?
- Does it state when generic probing is allowed?
- Does it distinguish blocked pages from missing data?
- Does it define the primary structured artifact clearly?
- Does it stop downstream skills from recollecting data?
- Does it include verification expectations, not only workflow prose?

If any answer is "no", the skill is still under-specified.