Align skills with Agent Skills spec (agentskills.io)

[shrey150]

Summary

Aligns both skills with the Agent Skills spec, rewrites the browser skill commands to match the actual CLI, and adds OpenClaw plugin metadata for discoverability.

Spec alignment

• Remove setup.json — no agent reads it; only SKILL.md is loaded into context
• Rename browser-automation/ to browser/ — spec requires directory name to match the name frontmatter field
• Quote compatibility YAML value — the : set substring caused a strictyaml parse error
• Rewrite functions description — moved trigger keywords into the frontmatter description
• Split functions/SKILL.md into SKILL.md + REFERENCE.md for progressive disclosure
• Remove redundant "When to Use" body section from functions
• Add license: MIT and LICENSE.txt to both skills
• Add table of contents to browser/REFERENCE.md (535 lines; spec recommends TOC for files >100 lines)
• Condense browser/EXAMPLES.md from 8 repetitive examples to 4 diverse ones

CLI command rewrite (critical fix)

The SKILL.md documented commands that do not exist in the browse CLI (navigate, act, extract, observe). These were Stagehand SDK concepts, not actual CLI commands. Agents were running nonexistent commands and falling back to guessing.

• Replace all command docs with actual CLI syntax from browse --help
• Documented commands: open, snapshot, screenshot, click <ref>, type, fill, select, press, scroll, wait, get, stop
• Removed fake commands: navigate, act, extract, observe, close
• Added snapshot-first workflow — snapshot is fast/structured, screenshot is slow/expensive. Old best practices said "screenshot after every command" which wasted vision tokens
• Added typical workflow section showing the recommended open → snapshot → click → snapshot loop
• Fixed quick example to use real commands

Discoverability improvements

• Expand browser skill description with anti-bot stealth, automatic CAPTCHA solving, residential proxy, and bot detection trigger phrases for ClawHub semantic search and agent tool selection
• Expand mode comparison table — break out CAPTCHA solving, residential proxies, and session persistence as separate rows

OpenClaw plugin metadata

• Add metadata.openclaw.requires.bins — gates the skill on the browse CLI being installed
• Add metadata.openclaw.install — tells OpenClaw how to auto-install the CLI (npm install -g @browserbasehq/browse-cli)
• Add homepage — improves trust score on ClawHub
• Do NOT gate on env vars — local mode works without Browserbase API keys

Local vs remote mode guidance

• Rewrite "Environment Selection" section with clear guidance on when to use each mode:
  • Local (default): no keys needed, for dev/simple pages/trusted sites
  • Remote (Browserbase): for protected sites, CAPTCHAs, bot detection, Cloudflare, geo-restricted content

Troubleshooting

• Zombie daemon fix: browse stop doesn't always kill the daemon. Added pkill -f "browse.*daemon" fallback for "No active page" errors

Validation

Both skills pass skills-ref validate:

$ skills-ref validate skills/browser
Valid skill: skills/browser

$ skills-ref validate skills/functions
Valid skill: skills/functions

Test plan

• Run skills-ref validate against both skill directories
• Verify all documented commands match browse --help output
• Test snapshot-first workflow: browse open <url> → browse snapshot → browse click <ref> → browse stop
• Verify zombie daemon recovery: kill daemon mid-session, confirm pkill fallback works
• Confirm metadata.openclaw.requires.bins correctly gates the skill when browse is not on PATH
• Publish to ClawHub (clawhub publish ./skills/browser/ --slug browse --version 2.0.0) and verify semantic search surfaces it for "captcha", "anti-bot", "protected website" queries

---

Note

Low Risk
Documentation/metadata-only changes that primarily rename/restructure skills and update CLI examples; low risk aside from potential broken links if consumers still reference the removed browser-automation paths.

Overview
Updates the marketplace and README to replace the old browser-automation skill with a new spec-compliant browser skill, including refreshed positioning around Browserbase remote sessions (stealth/CAPTCHA/proxies).

Replaces the previous Stagehand-style browser command documentation/examples with the actual browse CLI workflow (snapshot-first, daemon/session commands) and adds OpenClaw installation/requirements metadata plus MIT licensing.

Refactors the functions skill docs by moving trigger language into frontmatter, adding MIT licensing, and splitting deeper invocation/pattern/troubleshooting content into a new REFERENCE.md for progressive disclosure.

^{Written by Cursor Bugbot for commit acc6cc3. This will update automatically on new commits. Configure here.}

[Kylejeong2]

A few nits to resolve. Is the assumption for Functions that Claude Code or the Agent is going to generate code to run?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[Kylejeong2]

@cursoragent can you review this PR

[cursor]

Short answer: mostly good. I fixed the one real issue and pushed.

• Re: “not on npm” — @browserbasehq/browse-cli isn’t resolvable on npm. I removed the auto-install from the OpenClaw metadata and made the skill gate purely on the browse binary being present. Also removed the explicit npm install -g @browserbasehq/browse-cli text from compatibility/setup. Commit: 5b74333.
• Paths are fine now: .claude-plugin/marketplace.json points to ./skills/browser and README.md links to skills/browser/SKILL.md.
• Year is already 2026 in both skills/*/LICENSE.txt.
• Minor doc tweak: generalized one reference note that mentioned a specific “browse-cli v0.1.4”.

If/when the browse CLI is published, we can reintroduce the install stanza:

• Add back metadata.openclaw.install with the correct npm package and bins: [browse].
• Restore the setup hint to install via npm.

I’ve pushed the fixes to fix/skill-setup-frontmatter.

  

[Kylejeong2]

Approved, would ask Peyton to test first before merging and breaking live version