OpenWeb#

Agent-native way to access any website. Bridging agent CLI and web GUI through API.

Load Discipline#

• Do not read every file in this folder.
• Start with SKILL.md. Follow one route at a time.

Use Existing Site#

1. Find the site#

bash

openweb sites                        # list all available sites

If the site has no package, do NOT say "unsupported." Route to add-site/guide.md.

2. Check readiness#

bash

openweb <site>                       # transport, auth, operations list

• Requires browser: yes — browser auto-starts when needed; no manual setup required
• Requires login: yes — user must be logged in via their browser session

3. Read site notes#

Prefer site docs when they exist in your workspace:

• Source repo: read src/sites/<site>/SKILL.md for workflows and intent mapping, then src/sites/<site>/DOC.md for internals.
• Shipped/runtime package: only DOC.md, specs, manifest, examples, and adapters are guaranteed. Per-site SKILL.md and PROGRESS.md are source-tree docs and are not shipped into $OPENWEB_HOME/sites/<site>/.

If only the shipped package is available, rely on openweb <site>, openweb <site> <op>, examples, and DOC.md.

4. Inspect the operation#

bash

openweb <site> <op>                  # params, response shape, permission tier
openweb <site> <op> --example        # real example params from fixtures

Check the operation's permission tier before executing:

TierDefaultBehaviorreadallowGET-like operations — execute freelywritepromptCreates/updates — ask user before executingdeletepromptDestructive — ask user before executingtransactdenyFinancial/irreversible — always skip

5. Execute#

bash

openweb <site> <op> '{"key":"value"}'    # stdout=JSON, stderr=JSON error

Auto-spill: responses over 4096 bytes write to a temp file.

openweb <site> exec <op> '{...}' is equivalent — exec can be omitted when the third arg is JSON.

6. On failure#

Errors on stderr include failureClass:

failureClassActionneeds_browserBrowser auto-starts; if it fails, check Chrome installation. Fallback: openweb browser start``needs_login``openweb login <site> then openweb browser restart``needs_pageOpen a tab to the site URLbot_blocked``openweb browser restart --no-headless, user solves CAPTCHA in visible browser, then retry. For persistent sites, set "browser": {"headless": false} in configpermission_deniedUpdate permissions in $OPENWEB_HOME/config.json``permission_requiredAsk user for confirmation, then retryretriableWait a few seconds, retry (max 2)fatalDon't retry — fix params or check site name

If the table above doesn't resolve it, read references/troubleshooting.md.

7. Missing site or coverage#

Site doesn't exist or lacks needed operations? Read add-site/guide.md.

Add / Expand / Upgrade Site#

Read add-site/guide.md

Fix a Problem#

Read references/troubleshooting.md

File Map#

All paths relative to skills/openweb/.

add-site/ (workflow — load in sequence)#

FileLoad whenadd-site/guide.mdEntry point for add/expand workflowadd-site/probe.mdProbe step: CDP browser-side discoveryadd-site/capture.mdCapture step: recording browser trafficadd-site/review.mdReview step: reading analysis-summary.jsonadd-site/curate-operations.mdCurate: naming, noise, params, permissionsadd-site/curate-runtime.mdCurate: auth, transport, extractionadd-site/curate-schemas.mdCurate: response schemas, examples, PIIadd-site/verify.mdVerify: runtime + spec + doc loopadd-site/document.mdDocument: per-site SKILL.md + DOC.md + PROGRESS.md, knowledge updates

references/ (lookup — load independently)#

FileLoad whenreferences/cli.mdCLI command syntax, flags, stdout/stderrreferences/x-openweb.mdFull x-openweb field schemareferences/troubleshooting.mdSomething broke — classify, diagnose, fix

knowledge/ (patterns — load at decision points)#

FileLoad whenknowledge/archetypes.mdExpected operations by site categoryknowledge/auth-routing.mdAuth type unknown — signal-to-family lookupknowledge/auth-primitives.mdConfiguring auth — config and gotchasknowledge/bot-detection.mdTransport/capture decisionsknowledge/extraction.mdExtraction signals — SSR/DOM patternsknowledge/graphql.mdGraphQL — persisted queries, batchingknowledge/ws.mdWebSocket — message/connection patternsknowledge/adapter-recipes.mdAdapter patterns, code templates, pitfallsknowledge/transport-upgrade.mdTransport tier decisions, node feasibility, API discovery