actionbook

Original source / Raw SKILL.md

---
name: actionbook
description: Activate when the user needs to interact with any website — browser automation, web scraping, screenshots, form filling, UI testing, monitoring, or building AI agents. Provides pre-verified page actions with step-by-step instructions and tested selectors.
---

## When to Use This Skill

Activate when the user's request involves interacting with a website:

Activate when the user:
- Needs to do anything on a website ("Send a LinkedIn message", "Book an Airbnb", "Search Google for...")
- Asks how to interact with a site ("How do I post a tweet?", "How to apply on LinkedIn?")
- Wants to fill out forms, click buttons, navigate, search, filter, or browse on a specific site
- Wants to take a screenshot of a web page or monitor changes
- Builds browser-based AI agents, web scrapers, or E2E tests for external websites
- Automates repetitive web tasks (data entry, form submission, content posting)
- Wants to control their existing Chrome browser (Extension mode)


## What Actionbook Provides

Actionbook is a library of **pre-verified page interaction data**. `actionbook search` finds actions matching a task description; `actionbook get "<ID>"` returns a structured document describing a page's purpose, functional capabilities, and DOM structure with inline CSS selectors — eliminating the need for runtime page structure discovery.

## search and get

### search — Find actions by task description

```bash
actionbook search "<query>"                      # Search by task intent
actionbook search "<query>" --domain site.com    # Filter by domain
actionbook search "<query>" --url <url>          # Filter by URL
actionbook search "<query>" -p 2 -s 20           # Pagination
```

**Returns** for each result:
- `ID` — use with `actionbook get "<ID>"` to retrieve full details
- `Type` — `page` (full page) or `area` (page section)
- `Description` — page overview and function summary
- `URL` — page where this action applies
- `Health Score` — selector reliability percentage (0–100%)
- `Updated` — last verified date

### Constructing an effective search query

The `query` string is the **primary signal** for finding the right action. Pack it with the user's full intent — not just a site name or a vague keyword.

**Include in the query:**
1. **Target site** — the website name or domain
2. **Task verb** — what the user wants to do (search, book, post, filter, login, compose, etc.)
3. **Object / context** — what they're acting on (listings, messages, flights, repositories, etc.)
4. **Specific details** — any constraints, filters, or parameters the user mentioned (dates, location, category, language, etc.)

**Rule of thumb:** Rewrite the user's request as a single descriptive sentence and use that as the query.

| User says | Bad query | Good query |
|-----------|-----------|------------|
| "Book an Airbnb in Tokyo for next week" | `"airbnb"` | `"airbnb search listings Tokyo dates check-in check-out guests"` |
| "Search arXiv for recent NLP papers" | `"arxiv search"` | `"arxiv advanced search papers NLP natural language processing recent"` |
| "Send a LinkedIn connection request" | `"linkedin"` | `"linkedin send connection request invite someone"` |
| "Post a tweet with an image" | `"twitter post"` | `"twitter compose new tweet post with image media attachment"` |
| "Filter GitHub issues by label" | `"github issues"` | `"github repository issues filter by label search issues"` |

**When the user provides extra context** (e.g., specific dates, a city name, a topic), fold it into the query even if it won't match a stored action literally — it helps the search engine rank relevant pages higher.

```bash
# User: "Help me apply for a software engineer job on LinkedIn"
actionbook search "linkedin job search apply software engineer application form"

# User: "I need to search for machine learning papers on arXiv"
actionbook search "arxiv advanced search papers machine learning subject category"
```

If `--domain` or `--url` is known, always add them — they narrow results and improve precision.

### get — Retrieve full action details by ID

```bash
# Use the ID from search results directly
actionbook get "arxiv.org:/search/advanced:default"
```

**Returns** a structured document with:

1. **Page URL** — exact URL and query/path parameters
2. **Page Overview** — what the page does
3. **Page Function Summary** — interactive capabilities (e.g., "Search Term Input", "Subject Classification Filtering")
4. **Page Structure Summary** — DOM hierarchy with CSS selectors inline

Selectors appear embedded in the structure description, e.g.:
```
Search Term Form Section: Contains search term input field (input[type="text"]),
field selector dropdown (select[name="searchtype"]), and submit button (button.Search)
```

Extract CSS selectors from the structure summary for use with browser commands.

## Browser Commands

Quick reference. Full details with all flags and options: [command-reference.md](references/command-reference.md).

### Navigation

```bash
actionbook browser open <url>           # Open URL in new tab
actionbook browser goto <url>           # Navigate current page
actionbook browser back / forward       # History navigation
actionbook browser reload               # Reload page
actionbook browser pages                # List open tabs
actionbook browser switch <page_id>     # Switch tab
actionbook browser close                # Close browser
```

### Interactions

```bash
actionbook browser click "<selector>"          # Click element
actionbook browser fill "<selector>" "text"    # Clear and type
actionbook browser type "<selector>" "text"    # Append text
actionbook browser select "<selector>" "value" # Select dropdown option
actionbook browser hover "<selector>"          # Hover
actionbook browser press Enter                 # Press key
```

### Observation

```bash
actionbook browser text                        # Full page text
actionbook browser text "<selector>"           # Element text
actionbook browser snapshot                    # Accessibility tree (live page structure)
actionbook browser screenshot                  # Save screenshot
actionbook browser screenshot --full-page      # Full page screenshot
actionbook browser wait "<selector>"           # Wait for element
actionbook browser wait-nav                    # Wait for navigation
```

`actionbook browser close` cleans up the browser session. Skip if the user requests the browser remain open.

## Examples

User request: "Search arXiv for papers about Neural Networks, search in titles only"

```bash
# 1. Search — include the full intent: site + task + subject + filter preference
actionbook search "arxiv advanced search papers neural network title field" --domain arxiv.org

# 2. Get details — read Page Structure Summary for selectors
actionbook get "arxiv.org:/search/advanced:default"
# Response includes: input[type="text"], select[name="searchtype"], button.Search, etc.

# 3. Automate using selectors from the response
actionbook browser open "https://arxiv.org/search/advanced"
actionbook browser fill "input[type='text']" "Neural Network"
actionbook browser select "select[name='searchtype']" "title"
actionbook browser click "button.Search"
actionbook browser wait-nav
actionbook browser text
actionbook browser close
```

## Fallback

Actionbook stores page data captured at indexing time. Websites evolve, so selectors may become outdated.

When a selector from `actionbook get` fails at runtime, `actionbook browser snapshot` provides the **live accessibility tree** with current selectors. Use selectors from the snapshot output to retry the interaction.

Selectors used in browser commands should come from `actionbook get` or `actionbook browser snapshot` output in the current session — not from prior knowledge or memory.

If `actionbook search` returns no results for a page, use `snapshot` as the primary source, or fall back to other available tools.

## References

| Reference | Description |
|-----------|-------------|
| [command-reference.md](references/command-reference.md) | Complete command reference with all flags and options |
| [authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, session persistence |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/command-reference.md

```markdown
# actionbook Command Reference

Complete reference for all `actionbook` CLI commands.

## Action Search & Retrieval

### search - Search for action manuals

```bash
actionbook search "<query>"                    # Basic keyword search
actionbook search "<query>" --domain site.com  # Filter by domain
actionbook search "<query>" --url <url>        # Filter by specific URL
actionbook search "<query>" -p 2               # Page 2 (default: 1)
actionbook search "<query>" -s 20              # 20 results per page (default: 10, max: 100)
actionbook search "<query>" --domain site.com --url <url> -p 1 -s 5  # Combined
```

Returns area IDs with descriptions and relevance scores. Use the area_id with `actionbook get` to fetch full details.

### get - Get action details by area ID

```bash
actionbook get "<area_id>"
# area_id format: "site.com:/path:area_name"
# Examples:
#   actionbook get "airbnb.com:/:default"
#   actionbook get "github.com:/login:form"
#   actionbook get "arxiv.org:/search/advanced:default"
```

Returns complete action manual with CSS/XPath selectors, element types, and allowed methods.

### sources - List and search sources

```bash
actionbook sources list                        # List all available sources
actionbook sources search "<query>"            # Search sources by keyword
```

## Browser Automation

### Navigation

```bash
actionbook browser open <url>                  # Open URL in new tab
actionbook browser goto <url>                  # Navigate current page to URL
actionbook browser goto <url> --timeout 5000   # Custom navigation timeout (default: 30000ms)
actionbook browser back                        # Go back in history
actionbook browser forward                     # Go forward in history
actionbook browser reload                      # Reload current page
actionbook browser pages                       # List all open pages/tabs
actionbook browser switch <page_id>            # Switch to specific page by ID
actionbook browser close                       # Close the browser
actionbook browser restart                     # Restart the browser
actionbook browser connect <endpoint>          # Connect to existing browser (CDP port or ws:// URL)
actionbook browser status                      # Show detected browsers and session status
```

### Element Interactions

All interaction commands take CSS selectors. Use selectors from Action Manuals or from `snapshot` output.

```bash
actionbook browser click "<selector>"                  # Click element
actionbook browser click "<selector>" --wait 1000      # Wait 1s for element, then click
actionbook browser fill "<selector>" "text"            # Clear element, then type text
actionbook browser fill "<selector>" "text" --wait 500 # Wait for element, then fill
actionbook browser type "<selector>" "text"            # Type text (append, no clear)
actionbook browser type "<selector>" "text" --wait 500 # Wait for element, then type
actionbook browser select "<selector>" "value"         # Select dropdown option by value
actionbook browser hover "<selector>"                  # Hover over element
actionbook browser focus "<selector>"                  # Focus on element
actionbook browser press <key>                         # Press keyboard key
# Key examples: Enter, Tab, Escape, ArrowDown, ArrowUp, Backspace, Delete, Space
```

### Information Retrieval

```bash
actionbook browser text                        # Get full page text content
actionbook browser text "<selector>"           # Get text of specific element
actionbook browser html                        # Get full page HTML
actionbook browser html "<selector>"           # Get outer HTML of specific element
actionbook browser snapshot                    # Get accessibility snapshot (tree structure)
actionbook browser viewport                    # Get viewport dimensions
```

### Wait Conditions

```bash
actionbook browser wait "<selector>"                   # Wait for element to appear
actionbook browser wait "<selector>" --timeout 5000    # Custom timeout (default: 30000ms)
actionbook browser wait-nav                            # Wait for navigation to complete
actionbook browser wait-nav --timeout 10000            # Custom navigation timeout
```

### Screenshots & Export

```bash
actionbook browser screenshot                  # Save as screenshot.png
actionbook browser screenshot output.png       # Save to custom path
actionbook browser screenshot --full-page      # Full page screenshot
actionbook browser pdf output.pdf              # Export page as PDF
```

### JavaScript & DOM Inspection

```bash
actionbook browser eval "document.title"               # Execute JavaScript, return result
actionbook browser eval "document.querySelectorAll('a').length"
actionbook browser inspect <x> <y>                     # Inspect DOM element at viewport coordinates
actionbook browser inspect <x> <y> --desc "login btn"  # With description hint
```

### Cookie Management

```bash
actionbook browser cookies                     # List all cookies (default)
actionbook browser cookies list                # List all cookies
actionbook browser cookies get "<name>"        # Get specific cookie by name
actionbook browser cookies set "<name>" "<value>"              # Set cookie
actionbook browser cookies set "<name>" "<value>" --domain ".example.com"  # Set with domain
actionbook browser cookies delete "<name>"     # Delete specific cookie
actionbook browser cookies clear               # Clear all cookies
```

## Configuration

### config - Manage settings

```bash
actionbook config show                         # Display full configuration
actionbook config get <key>                    # Get specific config value
actionbook config set <key> <value>            # Set config value
actionbook config edit                         # Open config in $EDITOR
actionbook config path                         # Show config file location
```

**Config keys:**
- `api.base_url` - API endpoint (default: https://api.actionbook.dev)
- `api.api_key` - API authentication key
- `browser.executable` - Browser path override
- `browser.default_profile` - Default profile name
- `browser.headless` - Headless mode (true/false)

### profile - Manage browser profiles

```bash
actionbook profile list                        # List all profiles
actionbook profile create <name>               # Create new profile
actionbook profile create <name> --cdp-port 9222  # With specific CDP port
actionbook profile delete <name>               # Delete profile
actionbook profile show <name>                 # Show profile details
```

## Global Flags

These flags can be used with any command:

```bash
actionbook --json <command>                    # Output in JSON format
actionbook --headless <command>                # Run browser in headless mode
actionbook --verbose <command>                 # Enable verbose logging
actionbook -P <profile> <command>              # Use specific browser profile
actionbook --cdp <port|url> <command>          # Connect via CDP port or WebSocket URL
actionbook --browser-path <path> <command>     # Override browser executable path
```

## Environment Variables

```bash
ACTIONBOOK_API_URL="https://api.actionbook.dev"  # API endpoint
ACTIONBOOK_API_KEY="your-key"                     # API authentication key
ACTIONBOOK_BROWSER_PATH="/path/to/chrome"         # Browser executable
ACTIONBOOK_CDP="9222"                             # CDP port or WebSocket URL
ACTIONBOOK_PROFILE="default"                      # Default profile name
ACTIONBOOK_HEADLESS="true"                        # Headless mode
```

## Practical Examples

### Form Submission

```bash
actionbook browser open "https://example.com/form"
actionbook browser snapshot
# Read the snapshot to find selectors

actionbook browser fill "#email" "[email protected]"
actionbook browser fill "#password" "password123"
actionbook browser click "button[type=submit]"
actionbook browser wait-nav
actionbook browser text "h1"  # Check result
```

### Multi-page Navigation

```bash
actionbook browser open "https://example.com"
actionbook browser click "a[href='/products']"
actionbook browser wait-nav
actionbook browser click ".product-card:first-child a"
actionbook browser wait-nav
actionbook browser text ".product-details"
actionbook browser screenshot product.png
```

### Data Extraction

```bash
actionbook browser open "https://example.com/data"
actionbook browser wait-nav
actionbook browser text ".results-table"       # Get table text
actionbook browser eval "JSON.stringify([...document.querySelectorAll('.item')].map(e => e.textContent))"
actionbook browser close
```

### Connect to Existing Browser

```bash
# Start Chrome with debugging port
# google-chrome --remote-debugging-port=9222

actionbook browser connect 9222
actionbook browser pages
actionbook browser snapshot
```

```

### references/authentication.md

```markdown
# Authentication Patterns

Patterns for handling login flows, session persistence, and authenticated browsing using the Actionbook Rust CLI.

## Basic Login Flow

```bash
# Open login page
actionbook browser open "https://app.example.com/login"
actionbook browser wait-nav

# Take snapshot to identify form elements
actionbook browser snapshot

# Fill credentials using CSS selectors from snapshot
actionbook browser fill "#email" "$APP_USERNAME"
actionbook browser fill "#password" "$APP_PASSWORD"

# Submit
actionbook browser click "button[type=submit]"
actionbook browser wait-nav

# Verify login succeeded by checking the current URL
actionbook browser eval "window.location.href"
```

## Profile-Based Session Persistence

Profiles provide isolated browser sessions with separate cookies and storage. Use profiles to persist authentication across CLI invocations.

```bash
# Create a dedicated profile for the target site
actionbook profile create myapp

# Login using that profile
actionbook -P myapp browser open "https://app.example.com/login"
actionbook -P myapp browser wait-nav
actionbook -P myapp browser snapshot
actionbook -P myapp browser fill "#email" "$APP_USERNAME"
actionbook -P myapp browser fill "#password" "$APP_PASSWORD"
actionbook -P myapp browser click "button[type=submit]"
actionbook -P myapp browser wait-nav

# Later: reuse the profile — session cookies are preserved
actionbook -P myapp browser open "https://app.example.com/dashboard"
actionbook -P myapp browser wait-nav
actionbook -P myapp browser text "h1"  # Should show dashboard content

# List and inspect profiles
actionbook profile list
actionbook profile show myapp
```

## OAuth / SSO Flows

For OAuth redirects, use snapshot at each step to identify form elements:

```bash
# Start OAuth flow
actionbook browser open "https://app.example.com/auth/google"
actionbook browser wait-nav

# Google sign-in page — snapshot to find form elements
actionbook browser snapshot
actionbook browser fill "input[type=email]" "$GOOGLE_EMAIL"
actionbook browser click "#identifierNext"
actionbook browser wait-nav

# Password step
actionbook browser snapshot
actionbook browser fill "input[type=password]" "$GOOGLE_PASSWORD"
actionbook browser click "#passwordNext"
actionbook browser wait-nav

# Wait for redirect back to app (OAuth redirects can be slow)
actionbook browser eval "window.location.href"  # Should be app.example.com
```

## Two-Factor Authentication

Handle 2FA by running in headed mode (the default) and waiting for manual input:

```bash
# Login with credentials (browser is visible by default)
actionbook browser open "https://app.example.com/login"
actionbook browser wait-nav
actionbook browser snapshot
actionbook browser fill "#email" "$APP_USERNAME"
actionbook browser fill "#password" "$APP_PASSWORD"
actionbook browser click "button[type=submit]"
actionbook browser wait-nav

# Wait for user to complete 2FA manually
# Use a long timeout and wait for an element only present after 2FA
actionbook browser wait ".dashboard-header" --timeout 120000
```

## Cookie-Based Auth

Manually set authentication cookies:

```bash
# Open the target domain first (cookies need a page context)
actionbook browser open "https://app.example.com"
actionbook browser wait-nav

# Set auth cookie (use environment variable for the token value)
actionbook browser cookies set "session_token" "$SESSION_TOKEN" --domain ".example.com"

# Navigate to protected page
actionbook browser goto "https://app.example.com/dashboard"
actionbook browser wait-nav
```

## Token Refresh Handling

For sessions with expiring tokens:

```bash
#!/bin/bash
# Wrapper that handles token refresh using profiles

PROFILE="myapp"

# Try navigating directly with existing profile session
actionbook -P "$PROFILE" browser open "https://app.example.com/dashboard"
actionbook -P "$PROFILE" browser wait-nav

# Check if session is still valid via URL
URL=$(actionbook -P "$PROFILE" browser eval "window.location.href")
if [[ "$URL" == *"/login"* ]]; then
    echo "Session expired, re-authenticating..."

    # Perform fresh login
    actionbook -P "$PROFILE" browser snapshot
    actionbook -P "$PROFILE" browser fill "#email" "$APP_USERNAME"
    actionbook -P "$PROFILE" browser fill "#password" "$APP_PASSWORD"
    actionbook -P "$PROFILE" browser click "button[type=submit]"
    actionbook -P "$PROFILE" browser wait-nav
fi
```

## Security Best Practices

1. **Use environment variables for credentials** — source from a `.env` file, not inline
   ```bash
   # Load from .env file (avoid typing secrets in the terminal)
   source .env  # contains APP_USERNAME, APP_PASSWORD
   actionbook browser fill "#email" "$APP_USERNAME"
   actionbook browser fill "#password" "$APP_PASSWORD"
   ```

2. **Protect profile directories** — profiles store cookies and session data on disk
   ```bash
   # Profile data is equivalent to passwords — restrict access
   chmod 700 ~/.config/actionbook/
   ```

3. **Clean up sessions after automation**
   ```bash
   actionbook browser cookies clear
   actionbook browser close
   ```

4. **Delete profiles when no longer needed**
   ```bash
   actionbook profile delete myapp
   ```

5. **Use headless mode for CI/CD** (no visible browser)
   ```bash
   actionbook --headless browser open "https://app.example.com/login"
   # ... login and perform actions ...
   actionbook browser close
   ```

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "adcentury",
  "slug": "actionbook",
  "displayName": "Actionbook",
  "latest": {
    "version": "0.1.1",
    "publishedAt": 1770995370792,
    "commit": "https://github.com/openclaw/skills/commit/7f549b442c113ad7ec092dddf16f3addd6456f42"
  },
  "history": [
    {
      "version": "0.1.0",
      "publishedAt": 1770776570017,
      "commit": "https://github.com/openclaw/skills/commit/6fa6c370bb0fd1a2b4ea21291124b18fb85f85a5"
    }
  ]
}

```