@vpxa/aikit 0.1.144 → 0.1.145

package/scaffold/dist/definitions/skills/browser-use.mjs

@@ -1,6 +1,6 @@
 var e=[{file:`SKILL.md`,content:`---
 name: browser-use
-description: "Browser automation for AI agents using AI Kit's owned \`browser\` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) \`web_fetch\` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that \`web_fetch\` cannot handle, (5) user asks to browse, scrape, test, or automate a website. Uses AI Kit's owned Chromium runtime — no external MCP server dependency."
+description: "Browser automation for AI agents using AI Kit's owned \`browser\` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) \`web_fetch\` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that \`web_fetch\` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency."
 metadata:
   category: cross-cutting
   domain: general
@@ -52,16 +52,16 @@ Use AI Kit's owned \`browser\` MCP tool to solve authentication barriers, extrac
 
 ## Browser Action Reference
 
-| Action | Purpose | Key Fields |
+| Action | Purpose | Key Params |
 |--------|---------|------------|
-| \`open\` | Open a page in AI Kit's owned browser runtime | \`url\`, \`mode?\`, \`waitUntil?\` |
-| \`read\` | Return accessibility snapshot with refs and visible structure | \`pageId\` |
-| \`act\` | Interact with the page: click, type, press, hover, drag, select | \`pageId\`, \`kind\`, selector/ref/text/key fields |
-| \`navigate\` | Go to URL, back, forward, reload, or wait for navigation | \`pageId\`, \`url?\`, \`type?\`, \`waitFor?\` |
-| \`eval\` | Run sandboxed JavaScript in the page context | \`pageId\`, \`code\` |
-| \`screenshot\` | Capture page or element screenshot | \`pageId\`, selector/ref fields |
-| \`dialog\` | Accept or dismiss modal dialogs and related prompts | \`pageId\`, \`accept\`, \`promptText?\` |
-| \`session\` | List open pages, close a page, or export cookies | \`sessionAction\`, \`pageId?\` |
+| \`open\` | Launch browser page | \`url\`, \`mode\` (\`ui\`/\`headless\`/\`panel\`), \`waitUntil\` |
+| \`read\` | Extract page content | \`pageId\`, \`readMode\` (\`snapshot\`/\`dom\`/\`markdown\`/\`text\`), \`selector\` |
+| \`act\` | DOM interactions | \`pageId\`, \`kind\` (\`click\`/\`type\`/\`press\`/\`hover\`/\`drag\`/\`select\`/\`scroll\`/\`upload\`) |
+| \`navigate\` | Page navigation | \`pageId\`, \`url\`/\`type\`/\`selector\` |
+| \`eval\` | Execute JavaScript | \`pageId\`, \`code\` |
+| \`screenshot\` | Capture screenshots | \`pageId\`, \`selector\`, \`fullPage\`, \`clip\`, \`format\`, \`quality\` |
+| \`dialog\` | Handle dialogs | \`pageId\`, \`accept\`, \`promptText\` |
+| \`session\` | Session management | \`sessionAction\` (\`list\`/\`close\`/\`cookies\`/\`set-cookie\`/\`delete-cookie\`/\`clear-cookies\`/\`get-storage\`/\`set-storage\`/\`clear-storage\`) |
 
 ## Core Workflow
 
@@ -129,6 +129,640 @@ await browser({ action: 'session', sessionAction: 'close', pageId })
 
 Use cookie export only when the user explicitly needs session transfer back into CLI tools.
 
+## Read Modes
+
+### Get ARIA snapshot (default)
+
+\`\`\`
+browser({ action: 'read', pageId })
+browser({ action: 'read', pageId, readMode: 'snapshot' })
+\`\`\`
+
+### Get page as clean markdown
+
+\`\`\`
+browser({ action: 'read', pageId, readMode: 'markdown' })
+\`\`\`
+
+### Get HTML content (full page or scoped)
+
+\`\`\`
+browser({ action: 'read', pageId, readMode: 'dom' })
+browser({ action: 'read', pageId, readMode: 'dom', selector: 'main' })
+\`\`\`
+
+### Get plain text
+
+\`\`\`
+browser({ action: 'read', pageId, readMode: 'text', selector: '.article-content' })
+\`\`\`
+
+## Advanced Screenshots
+
+### Capture specific region
+
+\`\`\`
+browser({ action: 'screenshot', pageId, clip: { x: 0, y: 0, width: 800, height: 600 } })
+\`\`\`
+
+### JPEG format with quality
+
+\`\`\`
+browser({ action: 'screenshot', pageId, format: 'jpeg', quality: 80 })
+\`\`\`
+
+### Element screenshot with format
+
+\`\`\`
+browser({ action: 'screenshot', pageId, selector: '.chart', format: 'png' })
+\`\`\`
+
+## Cookie Management
+
+### Set cookies
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'set-cookie', confirm: true, cookies: [{ name: 'token', value: 'abc', domain: '.example.com', path: '/' }] })
+\`\`\`
+
+### Delete specific cookie
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'delete-cookie', confirm: true, name: 'tracking' })
+\`\`\`
+
+### Clear all cookies
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'clear-cookies', confirm: true })
+\`\`\`
+
+## Storage Access
+
+### Read all localStorage
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'get-storage', pageId, storageType: 'localStorage' })
+\`\`\`
+
+### Read specific key
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'get-storage', pageId, storageType: 'localStorage', storageKey: 'user-preferences' })
+\`\`\`
+
+### Set storage value
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'set-storage', pageId, storageType: 'localStorage', storageKey: 'theme', storageValue: 'dark' })
+\`\`\`
+
+### Clear sessionStorage
+
+\`\`\`
+browser({ action: 'session', sessionAction: 'clear-storage', pageId, storageType: 'sessionStorage' })
+\`\`\`
+
+## Scroll and Upload
+
+### Scroll down
+
+\`\`\`
+browser({ action: 'act', pageId, kind: 'scroll', value: 'down 500' })
+\`\`\`
+
+### Scroll to top/bottom
+
+\`\`\`
+browser({ action: 'act', pageId, kind: 'scroll', value: 'top' })
+browser({ action: 'act', pageId, kind: 'scroll', value: 'bottom' })
+\`\`\`
+
+### Scroll element into view
+
+\`\`\`
+browser({ action: 'act', pageId, kind: 'scroll', selector: '#target-element' })
+\`\`\`
+
+### Upload file
+
+\`\`\`
+browser({ action: 'act', pageId, kind: 'upload', selector: 'input[type="file"]', value: '/path/to/file.pdf' })
+\`\`\`
+
+### Upload multiple files
+
+\`\`\`
+browser({ action: 'act', pageId, kind: 'upload', selector: 'input[type="file"]', value: '["/path/file1.pdf", "/path/file2.pdf"]' })
+\`\`\`
+
+## Browser Automation Recipes
+
+The browser tool is the foundation for multi-step web automation. Use this section to standardize recipes that domain-specific skills can consume, extend, and execute without inventing their own browser workflow format.
+
+### Recipe Format
+
+A browser recipe is a markdown workflow with explicit metadata, variables, steps, and cleanup.
+
+#### Metadata
+
+- **Name** — Human-readable recipe name
+- **Trigger** — When the recipe should be used
+- **Target** — Domain, URL family, or app surface it operates on
+- **Mode** — \`headless\`, \`ui\`, or \`panel\`
+- **Requires Auth** — \`yes\` or \`no\`
+- **Destructive** — \`yes\` or \`no\`; destructive recipes require explicit user confirmation before execution
+
+#### Variables
+
+Define placeholders the agent must resolve before starting.
+
+- \`{{url}}\` — target URL
+- \`{{username}}\` — login or account identifier
+- \`{{file_path}}\` — file path for uploads
+
+For each variable, document what it means, whether the agent can infer it or must ask the user, whether it is sensitive, and an example value when that removes ambiguity.
+
+#### Steps
+
+Each numbered step should include:
+
+1. **Action** — exact \`browser(...)\` call
+2. **Verify** — how to confirm the action succeeded
+3. **On Failure** — recovery path if verification fails
+4. **Extract** — data to capture for later steps or the final result
+
+#### Cleanup
+
+Cleanup always runs, even when earlier steps fail. Close pages, export only user-approved session state, and leave the browser runtime in a known state.
+
+#### Recipe Skeleton
+
+\`\`\`markdown
+# Recipe: <Name>
+
+## Metadata
+- Name: <Human-readable name>
+- Trigger: <When to use it>
+- Target: <Domain or URL family>
+- Mode: headless
+- Requires Auth: no
+- Destructive: no
+
+## Variables
+- \`{{url}}\` — Target URL
+- \`{{selector}}\` — Primary element selector
+
+## Steps
+1. Open target
+   - Action: \`browser({ action: 'open', url: '{{url}}', mode: 'headless' })\`
+   - Verify: Browser returns a \`pageId\`
+   - On Failure: Retry once with \`waitUntil: 'load'\` or \`mode: 'ui'\`
+   - Extract: Save \`pageId\`
+
+2. Inspect page
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: Expected controls or content appear in output
+   - On Failure: Reload and re-read
+   - Extract: Save refs, selectors, visible labels
+
+## Cleanup
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+\`\`\`
+
+### Recipe Templates
+
+#### Recipe: Submit Web Form
+
+**Variables**
+
+- \`{{url}}\` — form page URL
+- \`{{fields}}\` — field values keyed by selector or control ref
+
+**Steps**
+
+1. Open page
+   - Action: \`browser({ action: 'open', url: '{{url}}', mode: 'headless', waitUntil: 'domcontentloaded' })\`
+   - Verify: Browser returns a \`pageId\`
+   - On Failure: Retry once with \`waitUntil: 'load'\` or \`mode: 'ui'\`
+   - Extract: Save \`pageId\`
+
+2. Read form structure
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: Form fields and submit button appear in output
+   - On Failure: Re-read after reload or scope the read with a form selector
+   - Extract: Required fields, labels, visible validation hints, selectors or refs
+
+3. Fill fields
+   - Action: For text inputs, use \`browser({ action: 'act', pageId, kind: 'type', selector: fieldSelector, text: value })\`
+   - Action: For dropdowns, use \`browser({ action: 'act', pageId, kind: 'select', selector: fieldSelector, value: optionValue })\`
+   - Action: For checkboxes or radio buttons, use \`browser({ action: 'act', pageId, kind: 'click', selector: fieldSelector })\`
+   - Verify: Re-read affected fields or take a screenshot after the batch
+   - On Failure: Re-read page, correct the selector, retry the failed field once
+   - Extract: Inline validation messages and any server-provided field defaults
+
+4. Verify form state
+   - Action: \`browser({ action: 'screenshot', pageId, fullPage: true })\`
+   - Verify: Screenshot shows required fields populated as expected
+   - On Failure: Read visible validation messages with \`browser({ action: 'read', pageId, readMode: 'text' })\`
+   - Extract: Evidence screenshot for the final report
+
+5. Submit
+   - Action: \`browser({ action: 'act', pageId, kind: 'click', selector: 'button[type="submit"]' })\`
+   - Verify: \`browser({ action: 'read', pageId, readMode: 'text' })\` shows a success message or the page navigates to a confirmation state
+   - On Failure: Inspect validation errors, fix fields, retry once
+   - Extract: Success text, destination URL, confirmation number if present
+
+6. Capture result
+   - Action: \`browser({ action: 'read', pageId, readMode: 'markdown' })\`
+   - Verify: Output contains the expected success state
+   - On Failure: Fall back to \`readMode: 'text'\`
+   - Extract: Confirmation content for downstream skills
+
+**Cleanup**
+
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+#### Recipe: Extract Data from Web Page
+
+**Variables**
+
+- \`{{url}}\` — target page URL
+- \`{{data_selector}}\` — selector for the content to extract
+- \`{{pagination_selector}}\` — selector for the next-page control, when pagination exists
+
+**Steps**
+
+1. Open page
+   - Action: \`browser({ action: 'open', url: '{{url}}', mode: 'headless' })\`
+   - Verify: Browser returns a \`pageId\`
+   - On Failure: Retry with \`waitUntil: 'networkidle'\`
+   - Extract: Save \`pageId\`
+
+2. Extract content
+   - Action: \`browser({ action: 'read', pageId, readMode: 'markdown', selector: '{{data_selector}}' })\`
+   - Verify: Output is non-empty and scoped to the requested selector
+   - On Failure: Re-run with \`readMode: 'text'\` or confirm the selector with a snapshot read
+   - Extract: Store extracted content for the current page
+
+3. Check for pagination
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: Snapshot shows either a next-page control or a clear end state
+   - On Failure: Reload once, then re-read
+   - Extract: Whether \`{{pagination_selector}}\` exists and appears enabled
+
+4. Advance when another page exists
+   - Action: If \`{{pagination_selector}}\` is present and enabled, run \`browser({ action: 'act', pageId, kind: 'click', selector: '{{pagination_selector}}' })\`
+   - Verify: \`browser({ action: 'navigate', pageId, type: 'waitFor', selector: '{{data_selector}}', timeoutMs: 30000 })\`
+   - On Failure: Reload page and retry pagination once
+   - Extract: Updated page content, page count, or cursor state
+
+5. Repeat until no more pages
+   - Action: Return to step 2 after successful pagination
+   - Verify: Loop exits only when the next-page control is missing or disabled
+   - On Failure: Stop and report partial results
+   - Extract: Aggregate page-by-page results
+
+**Cleanup**
+
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+#### Recipe: Upload File to Web Service
+
+**Variables**
+
+- \`{{url}}\` — upload page URL
+- \`{{file_path}}\` — local file path to upload
+- \`{{file_input_selector}}\` — file input selector, usually \`input[type="file"]\`
+
+**Steps**
+
+1. Open upload page
+   - Action: \`browser({ action: 'open', url: '{{url}}', mode: 'headless' })\`
+   - Verify: Upload page loads successfully
+   - On Failure: Retry with \`mode: 'ui'\`
+   - Extract: Save \`pageId\`
+
+2. Inspect upload controls
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: File input and submit controls are present
+   - On Failure: Re-read after reload or refine the selector
+   - Extract: Confirm the file input selector and submit control
+
+3. Upload file
+   - Action: \`browser({ action: 'act', pageId, kind: 'upload', selector: '{{file_input_selector}}', value: '{{file_path}}' })\`
+   - Verify: Selected filename appears in the page or read output
+   - On Failure: Verify the file exists, confirm the selector targets a real \`<input type="file">\`, retry once
+   - Extract: Selected filename and any client-side validation message
+
+4. Submit upload
+   - Action: \`browser({ action: 'act', pageId, kind: 'click', selector: '.upload-submit' })\`
+   - Verify: \`browser({ action: 'navigate', pageId, type: 'waitFor', selector: '.upload-success', timeoutMs: 30000 })\`
+   - On Failure: Read the page for upload errors, then retry once if recoverable
+   - Extract: Completion state and resulting URL if visible
+
+5. Verify upload
+   - Action: \`browser({ action: 'read', pageId, readMode: 'text' })\`
+   - Verify: Output includes upload confirmation
+   - On Failure: Take a screenshot and report an ambiguous completion state
+   - Extract: Confirmation text, file URL, or server response summary
+
+**Cleanup**
+
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+#### Recipe: Authenticated Web Task
+
+**Variables**
+
+- \`{{login_url}}\` — login page URL
+- \`{{target_url}}\` — target page after login
+- \`{{username}}\` — account identifier, ask the user if not already known
+- \`{{password}}\` — sensitive; do not store or echo it, and prefer having the user type it directly in the browser UI
+
+**Steps**
+
+1. Open login page
+   - Action: \`browser({ action: 'open', url: '{{login_url}}', mode: 'ui', waitUntil: 'domcontentloaded' })\`
+   - Verify: Login page is visible
+   - On Failure: Retry with \`waitUntil: 'load'\`
+   - Extract: Save \`pageId\`
+
+2. Read login form
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: Username, password, and submit controls are visible
+   - On Failure: Reload and re-read, or ask the user to describe the current page state
+   - Extract: Login selectors, SSO options, and challenge indicators
+
+3. Enter credentials
+   - Action: Ask the user for \`{{username}}\` if needed, then run \`browser({ action: 'act', pageId, kind: 'type', selector: usernameSelector, text: '{{username}}' })\`
+   - Action: Have the user type the password directly in the visible browser when possible
+   - Action: After the user confirms password entry, run \`browser({ action: 'act', pageId, kind: 'click', selector: submitSelector })\`
+   - Verify: Page advances to a post-login state
+   - On Failure: Re-read and classify the blocker as invalid credentials, 2FA, CAPTCHA, or selector mismatch
+   - Extract: Login result state
+
+4. Handle post-login challenges
+   - Action: \`browser({ action: 'read', pageId, readMode: 'snapshot' })\`
+   - Verify: Output shows whether 2FA, CAPTCHA, consent, or success is present
+   - On Failure: Take a screenshot and ask the user what they see
+   - Extract: Challenge type and controls needed to continue
+   - If 2FA appears: ask the user for the code or have them enter it directly in the UI, then continue
+   - If CAPTCHA appears: ask the user to solve it manually, then continue
+
+5. Navigate to target
+   - Action: \`browser({ action: 'navigate', pageId, url: '{{target_url}}' })\`
+   - Verify: Target page loads and expected content appears
+   - On Failure: Retry once after a fresh read or follow the app's redirect path manually
+   - Extract: Final URL and target page state
+
+6. Perform task-specific work
+   - Action: Insert task-specific browser steps using the same Action / Verify / On Failure / Extract pattern
+   - Verify: Task-specific completion criteria hold
+   - On Failure: Stop after two failed recoveries and report the current state to the user
+   - Extract: Requested result data
+
+**Cleanup**
+
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+#### Recipe: Monitor Web Page for Changes
+
+**Variables**
+
+- \`{{url}}\` — page to monitor
+- \`{{watch_selector}}\` — selector for the watched element
+- \`{{interval_ms}}\` — time between checks in milliseconds
+
+**Steps**
+
+1. Open page
+   - Action: \`browser({ action: 'open', url: '{{url}}', mode: 'headless' })\`
+   - Verify: Browser returns a \`pageId\`
+   - On Failure: Retry with \`mode: 'ui'\`
+   - Extract: Save \`pageId\`
+
+2. Capture baseline
+   - Action: \`browser({ action: 'read', pageId, readMode: 'text', selector: '{{watch_selector}}' })\`
+   - Verify: Baseline content is non-empty
+   - On Failure: Confirm the selector with a snapshot read
+   - Extract: Baseline content for later comparison
+
+3. Wait and re-check
+   - Action: \`browser({ action: 'eval', pageId, code: 'await new Promise((resolve) => setTimeout(resolve, {{interval_ms}}))' })\`
+   - Action: \`browser({ action: 'navigate', pageId, type: 'reload' })\`
+   - Action: \`browser({ action: 'read', pageId, readMode: 'text', selector: '{{watch_selector}}' })\`
+   - Verify: New content is captured successfully
+   - On Failure: Reload again and retry once
+   - Extract: Current content for diffing
+
+4. Compare against baseline
+   - Action: Compare the current content with the stored baseline outside the browser call
+   - Verify: Comparison is deterministic
+   - On Failure: Re-run the text read once to rule out a partial load
+   - Extract: Changed or unchanged state
+   - If changed: report it to the user and capture \`browser({ action: 'screenshot', pageId, selector: '{{watch_selector}}' })\`
+   - If unchanged: return to step 3
+
+**Cleanup**
+
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+### Execution Protocol
+
+When an agent receives a browser recipe to execute:
+
+1. **Resolve variables** — ask the user for all unresolved \`{{variables}}\`, and explicitly flag which ones are sensitive.
+2. **Pre-flight the environment** — if the recipe requires auth, destructive actions, uploads, or cookie export, warn the user before starting.
+3. **Run sequentially on each page** — within one page, execute Action → Verify → On Failure → Extract in order. Shared DOM state is not parallel-safe.
+4. **Stop after two failed recoveries on the same step** — report the current state, what failed, and what the user can do next.
+5. **Run cleanup even on failure** — always close pages unless the user asked to keep the session open.
+6. **Summarize results** — report what was completed, what data was extracted, and which steps were skipped or blocked.
+
+### Error Recovery Strategies
+
+| Error | Recovery |
+|-------|----------|
+| Element not found | Re-read with \`readMode: 'snapshot'\`, adjust selector or ref, then retry once |
+| Page timeout | Reload page, wait for a more specific selector, then retry |
+| Navigation failed | Verify target URL, try \`waitUntil: 'load'\` on open or \`type: 'waitFor'\` on navigate |
+| Auth required | Switch to \`mode: 'ui'\`, follow the auth pattern, and let the user handle secrets directly |
+| CAPTCHA or human check | Stop and ask the user to solve it manually, then continue from the next read |
+| File upload failed | Verify local file path, confirm the selector targets a real file input, retry once |
+| Storage access denied | Fall back to a narrow \`eval\` call only when browser session storage APIs are blocked |
+| Network error | Wait briefly, reload, retry once, then report partial progress |
+
+### Building Skills on Browser Primitives
+
+\`browser-use\` is the foundation skill. Domain-specific skills such as deployment planners, release-note generators, internal admin workflows, or authenticated data collectors should depend on it instead of redefining browser semantics.
+
+When another skill ships browser automation, it should treat this section as the shared contract.
+
+#### Domain Skill Architecture
+
+\`browser-use\` provides the primitives. Domain skills provide the workflow.
+
+A domain skill built on top of browser automation should follow this architecture:
+
+- The domain skill has its own \`SKILL.md\` that explains what business task it automates, such as creating deployment release notes from GitHub PRs.
+- Browser recipes live inside that skill, either embedded directly in \`SKILL.md\` or stored as reusable docs under the skill's \`references/\` directory.
+- The domain skill references \`browser-use\` for browser action semantics, security rules, auth escalation, and recovery patterns instead of redefining them.
+- The domain skill guides the LLM through the end-to-end workflow, including when to gather inputs, when to run browser recipes, when to switch tools, and how to format the final output.
+- Browser recipes handle web interaction details. The domain skill handles business intent, sequencing, domain-specific validation, and final deliverables.
+
+This separation matters because a teammate usually does not want "a browser script." They want a skill for a business outcome such as deployment planning, release-note generation, status monitoring, or internal-tool automation. The domain skill explains the outcome and uses browser recipes as implementation building blocks.
+
+#### Example: Deployment Release Notes Skill
+
+A teammate wants a skill that automates creating release notes by scraping GitHub PRs, commit history, and linked tickets. Here is how the skill's \`SKILL.md\` would be structured:
+
+\`\`\`markdown
+# Deployment Release Notes - Automated Release Documentation
+
+Generate deployment release notes by collecting PR descriptions, commit messages, and linked tickets from GitHub, then formatting them into a structured release document.
+
+**When to use:** Before a deployment, when the team needs a summary of changes, or when creating a changelog for stakeholders.
+
+**Prerequisites:**
+- \`browser-use\` skill loaded (provides browser automation primitives and recipe format)
+- Access to the GitHub repository (may require auth)
+
+## Workflow
+
+### Step 1: Gather Context
+- Ask the user for: repository URL, release branch/tag, previous release tag
+- Determine if GitHub auth is needed (private repo -> use Authenticated Web Task recipe from browser-use)
+
+### Step 2: Collect PR Data
+Follow this browser recipe:
+
+# Recipe: Extract GitHub PRs Between Tags
+
+## Metadata
+- Name: GitHub PR Extraction
+- Trigger: Need to list merged PRs between two git tags
+- Target: github.com or GitHub Enterprise
+- Mode: headless (public repos) or ui (private repos needing auth)
+- Requires Auth: depends on repo visibility
+- Destructive: no
+
+## Variables
+- \`{{repo_url}}\` - GitHub repository URL (e.g., https://github.com/org/repo)
+- \`{{base_tag}}\` - Previous release tag
+- \`{{head_tag}}\` - New release tag
+
+## Steps
+1. Open compare page
+   - Action: \`browser({ action: 'open', url: '{{repo_url}}/compare/{{base_tag}}...{{head_tag}}', mode: 'headless' })\`
+   - Verify: Page loads with comparison content
+   - On Failure: Switch to \`mode: 'ui'\` for auth, follow browser-use auth pattern
+   - Extract: Save \`pageId\`
+
+2. Extract PR list
+   - Action: \`browser({ action: 'read', pageId, readMode: 'markdown', selector: '.js-commits-list-item, .pr-list' })\`
+   - Verify: Output contains commit or PR references
+   - On Failure: Try \`readMode: 'dom'\` and parse HTML, or use the commits tab instead
+   - Extract: List of PRs with titles, numbers, authors
+
+3. For each PR, extract details
+   - Action: \`browser({ action: 'navigate', pageId, url: '{{repo_url}}/pull/{{pr_number}}' })\`
+   - Action: \`browser({ action: 'read', pageId, readMode: 'markdown', selector: '.comment-body' })\`
+   - Verify: PR description is captured
+   - On Failure: Fall back to \`readMode: 'text'\`
+   - Extract: PR title, description, labels, linked issues
+
+## Cleanup
+- \`browser({ action: 'session', sessionAction: 'close', pageId })\`
+
+### Step 3: Collect Linked Tickets (Optional)
+If PRs reference JIRA or ticket URLs, follow the Data Extraction recipe from browser-use to scrape ticket titles and statuses.
+
+### Step 4: Format Release Notes
+Using the collected data, generate a structured release document:
+- Group changes by category (features, fixes, chores) based on PR labels or commit prefixes
+- Include PR links, authors, and ticket references
+- Add deployment metadata (date, branch, tag range)
+
+### Step 5: Output
+Present the release notes to the user. Offer to:
+- Copy to clipboard
+- Save as markdown file
+- Create a GitHub Release draft (requires additional browser recipe)
+
+## Error Handling
+- If GitHub auth is needed, follow browser-use auth patterns (switch to ui mode, let user handle SSO or 2FA)
+- If PR extraction returns empty results, verify the tag names exist and the compare URL is correct
+- If the ticket system is unreachable, skip ticket enrichment and note it in the output
+\`\`\`
+
+This example shows the pattern: the domain skill orchestrates the workflow, deciding what to collect and how to format it, while \`browser-use\` provides the primitives for opening pages, reading content, handling auth, and recovering from common browser failures.
+
+#### How to Help Users Create Domain Skills
+
+When a user asks you to create a skill that automates a web-based workflow, follow this process:
+
+1. **Identify the workflow** - Ask what manual steps the user currently performs, which websites or web apps are involved, and what data they need to extract or actions they need to perform.
+2. **Map to recipes** - Break the workflow into discrete browser recipes. Each recipe should handle one website or one logical browser task. For example, extracting PRs from GitHub is one recipe, while formatting release notes is a separate non-browser step.
+3. **Check for reusable recipes** - Reuse and adapt the templates in this skill first: Form Submission, Data Extraction, File Upload, Authenticated Web Task, and Monitor Web Page. Do not write everything from scratch when an existing pattern already fits.
+4. **Structure the skill** - Give the user a skill layout that separates the main workflow from reusable references:
+
+\`\`\`text
+my-automation-skill/
+   SKILL.md
+   references/
+      recipe-github-extract-prs.md
+      recipe-jira-get-tickets.md
+\`\`\`
+
+5. **Write the SKILL.md** - Include these sections:
+   - **Header** - What the skill does, when to use it, and prerequisites. Always list \`browser-use\` when browser recipes are part of the workflow.
+   - **Workflow** - Numbered high-level steps that mix browser recipes with non-browser reasoning, formatting, summarization, or file generation.
+   - **Embedded recipes** - Put workflow-specific browser tasks inline when they are tightly coupled to that skill.
+   - **Referenced recipes** - Link to reusable docs under \`references/\` when the same recipe may be reused across multiple skills.
+   - **Error handling** - Describe domain-specific recovery, such as what to do when auth fails, data is missing, or target pages change.
+   - **Output** - State what artifact the skill produces and how it should be delivered to the user.
+6. **Test the skill** - Run each recipe in \`mode: 'ui'\` first to validate selectors, flow, and auth handling. Only switch to \`headless\` after the browser interactions are proven stable.
+7. **Register the skill** - Add it to \`scaffold/definitions/plugins.mjs\` so it deploys with \`aikit init\`.
+
+#### Domain Skill Ideas
+
+These are examples of skills teams could build on top of \`browser-use\`:
+
+| Skill | What it automates | Key recipes used |
+|-------|-------------------|------------------|
+| Deployment Release Notes | Scrape PRs, commits, and tickets into a formatted changelog | Authenticated Web Task, Data Extraction |
+| Deployment Plan Creator | Gather service dependencies, change scope, and risk inputs from internal tools | Data Extraction, Form Submission |
+| Status Page Monitor | Watch status pages and summarize changes | Monitor Web Page |
+| Form Auto-filler | Pre-fill repetitive internal forms such as expense reports or time sheets | Form Submission, Authenticated Web Task |
+| Screenshot Documentation | Capture annotated screenshots of UI flows for docs | Multi-page navigation, screenshots |
+| Competitive Analysis | Extract pricing, feature lists, and positioning details from public sites | Data Extraction, pagination |
+| Internal Tool Automation | Automate admin workflows in internal web apps that have no API | Authenticated Web Task, Form Submission |
+
+Use this guidance when you are helping a user create a new skill: describe the business workflow first, identify which browser recipes it needs, and keep browser-specific details aligned with the primitives and safety model documented here.
+
+#### Naming Convention
+
+- Use \`recipe-{domain}-{action}.md\` for reusable standalone recipe docs.
+- Store reusable examples in the consuming skill's \`references/\` directory.
+- Match the recipe title to the user-facing capability, not the implementation detail.
+
+#### Quality Checklist
+
+- [ ] Variables documented, including sensitivity and whether the agent may infer them
+- [ ] Every step includes Action, Verify, On Failure, and Extract
+- [ ] Auth and destructive behavior are declared in metadata
+- [ ] Cleanup is present and closes browser pages unless a kept-open session is intentional
+- [ ] Recovery paths stop after bounded retries instead of looping indefinitely
+- [ ] Recipe was exercised in \`mode: 'ui'\` at least once
+
+#### Composition Notes
+
+- Keep steps small enough that one read, screenshot, or selector wait can verify them.
+- Prefer \`readMode: 'snapshot'\` to discover controls, \`readMode: 'text'\` to verify outcomes, and \`readMode: 'markdown'\` to capture extracted content.
+- Use \`navigate({ type: 'waitFor', selector, timeoutMs })\` instead of timing guesses when a page transition has a concrete ready signal.
+- Use \`eval\` only for narrow gaps the built-in actions cannot cover.
+- Follow [references/auth-patterns.md](references/auth-patterns.md) for SSO, OAuth, CAPTCHA, or 2FA flows.
+
 ## Security Model (HARD GATE)
 
 - AI Kit enforces URL allowlisting before page navigation; respect denials instead of trying alternate bypasses.
@@ -173,17 +807,28 @@ This keeps the viewing workflow inside the same owned runtime.
 | CAPTCHA appears | Ask the user to solve it manually, then continue from \`read\` |
 | Need to inspect cookies | Use \`browser({ action: 'session', sessionAction: 'cookies', pageId })\` and warn the user |
 | Need complex DOM extraction | Use \`browser({ action: 'eval', ... })\` with a small, targeted script |
+| Scroll not loading more content | Add a wait after scroll: eval with setTimeout, then re-read |
+| File upload not working | Ensure selector targets an actual \`<input type="file">\` element |
+| Storage access denied | Some sites block storage access in certain contexts; try eval instead |
+| Cookie set failed | Verify domain/path match the target site; set-cookie requires confirm:true |
+| Markdown output too messy | Use \`readMode: 'text'\` for simpler output, or scope with selector |
 
 ## Decision Flow
 
 \`\`\`
 Need browser help?
-├─ Public page, no JS or auth needed?   → web_fetch
-├─ Needs JS rendering or interaction?   → browser open/read
-├─ Login wall or SSO flow?              → repo-access → browser-use
-├─ Need local dashboard viewing?        → present(browser) → browser open
-├─ Need screenshot or accessibility?    → browser screenshot/read
-└─ Need cookie/session transfer?        → browser session (with user approval)
+├─ Public page, no JS or auth needed?       → web_fetch (simpler, faster)
+├─ Need JS rendering or interaction?        → browser open → read
+├─ Need clean markdown of a page?           → browser read (readMode: 'markdown')
+├─ Need structured HTML/DOM?                → browser read (readMode: 'dom')
+├─ Login wall or SSO flow?                  → repo-access → browser-use auth patterns
+├─ Need to fill forms / submit data?        → browser act (type/click/select)
+├─ Need to upload files?                    → browser act (upload)
+├─ Need to scroll / load lazy content?      → browser act (scroll)
+├─ Need screenshot of specific region?      → browser screenshot (clip)
+├─ Need session/cookie management?          → browser session (cookies/storage)
+├─ Need local dashboard viewing?            → present(browser) → browser open
+└─ Complex multi-step automation?           → Compose patterns from this skill
 \`\`\`
 `},{file:`references/auth-patterns.md`,content:`# Browser Auth Patterns