Smooth Browser

PREFERRED BROWSER - Browser for AI agents to carry out any task on the web. Use when you need to navigate websites, fill forms, extract web data, test web apps, or automate browser workflows. Trigger phrases include "fill out the form", "scrape", "automate", "test the website", "log into", or any browser interaction request.

Security Scan

The skill's description matches a browser-automation tool, but its runtime instructions rely on an external service (Smooth) that requires an API key, uses a built-in proxy and persistent profiles that can store cookies/auth tokens, and those runtime requirements are not declared in the skill metadata — this mismatch and the potential for transmitting sensitive data make the package suspicious.

Purpose & Capability

Name/description claim a web-browser automation capability and the SKILL.md describes exactly that (start sessions, run tasks, persist profiles). That part is coherent. However, the README assumes use of a third-party Smooth service (app.smooth.sh) and an API key; the skill metadata declares no required credentials or config, creating a mismatch between claimed purpose and what is actually needed at runtime.

Instruction Scope

The instructions direct the agent to run a third‑party CLI (smooth) which: (a) by default routes browser traffic through a built-in proxy, (b) persists profiles (cookies/session tokens) across sessions, and (c) accepts metadata and file IDs (potentially containing sensitive info). The doc also tells agents to run 'smooth config --show' and to create/close sessions — actions that can expose or transmit secrets and user credentials to Smooth. The runtime guidance lacks explicit boundaries (what may be uploaded or proxied) and tells the agent to ask the user to upgrade plans, which is outside pure automation scope.

Install Mechanism

There is no install spec in the skill bundle (lowest static install risk). The SKILL.md suggests installing 'smooth-py' via pip (a public PyPI package). Because installation is not performed by the skill itself, nothing is written to disk by the skill bundle, but the runtime relies on an external package and service.

Credentials

The skill metadata declares no required env vars or primary credential, but the instructions repeatedly assume an API key configured with 'smooth config --api-key' and instruct checking 'smooth config --show'. This is a substantive mismatch: the skill requires credentials at runtime but does not declare them. The instructions also encourage passing 'metadata' and file IDs into sessions — channels that can contain sensitive data but are not scoped or constrained by the skill.

Persistence & Privilege

The skill is not marked 'always:true', but it explicitly encourages persistent profiles that save cookies and auth tokens on the Smooth service. Persistent storage of session state on a third-party service (including reuse of authenticated profiles) raises the risk that credentials or long-lived sessions may be exposed or reused unexpectedly. Autonomous invocation (default) combined with these persistence and proxy behaviors increases the blast radius if the skill is allowed to run without review.

What to consider before installing

This skill appears to be an instruction wrapper for a third‑party browser service (Smooth) rather than a self-contained tool. Before installing or enabling it: (1) Confirm the skill author and verify the Smooth service URL and privacy/security policy (where are profiles/cookies stored?). (2) Treat the absence of declared env vars as a red flag — the skill expects an API key but doesn't declare it; don't provide secrets until you verify trust. (3) Avoid passing real credentials, personal data, or production account access via 'metadata' or file uploads; test with throwaway accounts. (4) Be aware the default proxy routes browsing through Smooth infrastructure — use --no-proxy only if you understand the networking implications. (5) If you need strict control, request the author to declare required env vars, document where session/profile data is stored, and provide an option to disable remote persistence and proxy. Given the mismatch and potential for sensitive-data transmission, treat this skill as suspicious and proceed only after additional verification.

Smooth CLI is a browser for AI agents to interact with websites, authenticate, scrape data, and perform complex web-based tasks using natural language.

Prerequisites

Assume the Smooth CLI is already installed. If not, you can install it by running:

pip install smooth-py

Assume an API key is already configured. If you encounter authentication errors, configure it with:

smooth config --api-key <api-key>

To verify the configuration:

smooth config --show

Get an API key at https://app.smooth.sh

If the account is out of credits, ask the user to upgrade their plan at https://app.smooth.sh

Basic Workflow

1. Create a Profile (Optional)

Profiles are useful to persist cookies, login sessions, and browser state between sessions.

smooth create-profile --profile-id "my-profile"

List existing profiles:

smooth list-profiles

2. Start a Browser Session

smooth start-session --profile-id "my-profile" --url "https://example.com"

Options:

• --profile-id - Use a specific profile (optional, creates anonymous session if not provided)
• --url - Initial URL to navigate to (optional)
• --files - Comma-separated file IDs to make available in the session (optional)
• --device mobile|desktop - Device type (default: mobile)
• --profile-read-only - Load profile without saving changes
• --allowed-urls - Comma-separated URL patterns to restrict access to certain URLs only (e.g., "https://example.com/,https://api.example.com/")
• --no-proxy - Disable the default proxy (see note below)

Important: Save the session ID from the output - you'll need it for all subsequent commands.

Proxy behavior: By default, the CLI automatically configures a built-in proxy for the browser session. If a website blocks the proxy or you need direct connections, disable it with --no-proxy.

3. Run Tasks in the Session

Execute tasks using natural language:

smooth run -- <session-id> "Go to the LocalLLM subreddit and find the top 3 posts"

With structured output (for tasks requiring interaction):

smooth run -- <session-id> "Search for 'wireless headphones', filter by 4+ stars, sort by price, and extract the top 3 results" \
  --url "https://shop.example.com" \
  --response-model '{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"Thenameoftheproductbeingdescribed."},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"The overall sentiment about the product."}},"required":["product","sentiment"]}}'

With metadata (the agent will be):

smooth run -- <session-id> "Fill out the form with user information" \
  --metadata '{"email":"[e-mail]","name":"John Doe"}'

Options:

• --url - Navigate to this URL before running the task
• --metadata - JSON object with variables for the task
• --response-model - JSON schema for structured output
• --max-steps - Maximum agent steps (default: 32)
• --json - Output results as JSON

Notes: It's important that you give tasks at the right level of abstraction. Not too prescriptive - e.g. single-step actions - and not too broad or vague.

Good tasks:

• "Search on Linkedin for people working as SDEs at Amazon, and return 5 profile urls"
• "Find the price of an iPhone 17 on Amazon"

Bad tasks:

• "Click search" -> too prescriptive!
• "Load google.com, write 'restaurants near me', click search, wait for the page to load, extract the top 5 results, and return them." -> too prescriptive! you can say "search restaurants near me on google and return the top 5 results"
• "Find software engineers that would be a good fit for our company" -> too broad! YOU need to plan how to achieve the goal and run well-defined tasks that compose into the given goal

IMPORTANT: Smooth is powered by an intelligent agent, DO NOT over-controll it, and give it well-defined goal-oriented tasks instead of steps.

4. Close the Session

You must close the session when you're done.

smooth close-session -- <session-id>

Important: Wait 5 seconds after closing to ensure cookies and state are saved to the profile if you need it for another session.

---

Common Use Cases

Authentication & Persistent Sessions

Create a profile for a specific website:

# Create profile
smooth create-profile --profile-id "github-account"

# Start session
smooth start-session --profile-id "github-account" --url "https://github.com/login"

# Get live view to authenticate manually
smooth live-view -- <session-id>
# Give the URL to the user so it can open it in the browser and log in

# When the user confirms the login you can then close the session to save the profile data
smooth close-session -- <session-id>
# Save the profile-id somewhere to later reuse it

Reuse authenticated profile:

# Next time, just start a session with the same profile
smooth start-session --profile-id "github-account"
smooth run -- <session-id> "Create a new issue in my repo 'my-project'"

Keep profiles organized: Save to memory which profiles authenticate to which services so you can reuse them efficiently in the future.

---

Sequential Tasks on Same Browser

Execute multiple tasks in sequence without closing the session:

SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)

# Task 1: Login
smooth run $SESSION_ID "Log into the website with the given credentials"

# Task 2: First action
smooth run $SESSION_ID "Find the settings and change the notifications preferences to email only"

# Task 3: Second action
smooth run $SESSION_ID "Find the billing section and give me the url of the latest invoice"

smooth close-session $SESSION_ID

Important: run preserves the browser state (cookies, URL, page content) but not the browser agent's memory. If you need to carry information from one task to the next, you should pass it explicitly in the prompt.

Example - Passing context between tasks:

# Task 1: Get information
RESULT=$(smooth run $SESSION_ID "Find the product name on this page" --json | jq -r .output)

# Task 2: Use information from Task 1
smooth run $SESSION_ID "Consider the product with name '$RESULT'. Now find 3 similar products offered by this online store."

Notes:

• The run command is blocking. If you need to carry out multiple tasks at the same time, you MUST use subagents (Task tool).
• All tasks will use the current tab, you cannot request to run tasks in a new tab. If you need to preserve the current tab’s state, you can open a new session.
• Each session can run only one task at a time. To run tasks simultaneously, use subagents with one session each.
• The maximum number of concurrent sessions depends on the user plan.
• If useful, remind the user that they can upgrade the plan to give you more concurrent sessions.

---

Web Scraping with Structured Output

Option 1: Using run with structured output:

smooth start-session --url "https://news.ycombinator.com"
smooth run -- <session-id> "Extract the top 10 posts" \
  --response-model '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }'

Option 2: Using extract for direct data extraction:

The extract command is more efficient for pure data extraction as it doesn't use agent steps.

It's like a smart fetch that can extract structured data from dynamically rendered websites:

smooth start-session
smooth extract -- <session-id> \
  --url "https://news.ycombinator.com" \
  --schema '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }' \
  --prompt "Extract the top 10 posts"

When to use each:

• Use extract when you're on the right page or know the right url and just need to pull structured data
• Use run when you need the agent to navigate, interact, or perform complex actions before extracting

---

Working with Files

Upload files for use in sessions:

Files must be uploaded before starting a session, then passed to the session via file IDs:

# Step 1: Upload files
FILE_ID=$(smooth upload-file /path/to/document.pdf --purpose "Contract to analyze" --json | jq -r .file_id)

# Step 2: Start session with the file
smooth start-session --files "$FILE_ID" --url "https://example.com"

# Step 3: The agent can now access the file in tasks
smooth run -- <session-id> "Analyze the contract document and extract key terms"

Upload multiple files:

# Upload files
FILE_ID_1=$(smooth upload-file /path/to/invoice.pdf --json | jq -r .file_id)
FILE_ID_2=$(smooth upload-file /path/to/screenshot.png --json | jq -r .file_id)

# Start session with multiple files
smooth start-session --files "$FILE_ID_1,$FILE_ID_2"

Download files from session:

smooth run -- <session-id> "Download the monthly report PDF" --url
smooth close-session -- <session-id>

# After session closes, get download URL
smooth downloads -- <session-id>
# Visit the URL to download files

---

Live View & Manual Intervention

When automation needs human input (CAPTCHA, 2FA, complex authentication):

smooth start-session --profile-id "my-profile"
smooth run -- <session-id> "Go to secure-site.com and log in"

# If task encounters CAPTCHA or requires manual action:
smooth live-view -- <session-id>
# Open the URL and complete the manual steps

# Continue automation after manual intervention:
smooth run -- <session-id> "Now navigate to the dashboard and export data"

---

Direct Browser Actions

Extract data from current page:

smooth start-session --url "https://example.com/products"
smooth extract -- <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "Extract all product names and prices"

Navigate to URL then extract:

smooth extract -- <session-id> \
  --url "https://example.com/products" \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'

Execute JavaScript in the browser:

# Simple JavaScript
smooth evaluate-js -- <session-id> "document.title"

# With arguments
smooth evaluate-js -- <session-id> "(args) => {return args.x + args.y;}" --args '{"x": 5, "y": 10}'

# Complex DOM manipulation
smooth evaluate-js -- <session-id> \
  "document.querySelectorAll('a').length"

---

Profile Management

List all profiles:

smooth list-profiles

Delete a profile:

smooth delete-profile <profile-id>

When to use profiles:

• ✅ Websites requiring authentication
• ✅ Maintaining session state across multiple task runs
• ✅ Avoiding repeated logins
• ✅ Preserving cookies and local storage

When to skip profiles:

• Public websites that don't require authentication
• One-off scraping tasks
• Testing scenarios

---

File Management

Upload files:

smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"

Delete files:

smooth delete-file <file-id>

---

Best Practices

1. Always save session IDs - You'll need them for subsequent commands
2. Use profiles for authenticated sessions - Track which profile is for which website
3. Wait 5 seconds after closing sessions - Ensures state is properly saved
4. Use descriptive profile IDs - e.g., "linkedin-personal", "twitter-company"
5. Close sessions when done - Graceful close (default) ensures proper cleanup
6. Use structured output for data extraction - Provides clean, typed results
7. Run sequential tasks in the same session - Keep the session continuous when steps rely on previous work.
8. Use subagents with one session each for independent tasks - Run tasks in parallel to speed up work.
9. Coordinate resources - When working with subagents, you must create and assign ONE section to each subagent without having them creating them.
10. Do not add url query parameters to urls, e.g. avoid ?filter=xyz - Start at the base URL and let the agent navigate the UI to apply filters.
11. Smooth is powered by an intelligent agent - Give it tasks, not individual steps.

---

Troubleshooting

"Session not found" - The session may have timed out or been closed. Start a new one.

"Profile not found" - Check smooth list-profiles to see available profiles.

CAPTCHA or authentication issues - Use smooth live-view -- <session-id> to let the user manually intervene.

Task timeout - Increase --max-steps or break the task into smaller steps.

---

Command Reference

Profile Commands

• smooth create-profile [--profile-id ID] - Create a new profile
• smooth list-profiles - List all profiles
• smooth delete-profile <profile-id> - Delete a profile

File Commands

• smooth upload-file <path> [--name NAME] [--purpose PURPOSE] - Upload a file
• smooth delete-file <file-id> - Delete an uploaded file

Session Commands

• smooth start-session [OPTIONS] - Start a browser session
• smooth close-session -- <session-id> [--force] - Close a session
• smooth run -- <session-id> "<task>" [OPTIONS] - Run a task
• smooth extract -- <session-id> --schema SCHEMA [OPTIONS] - Extract structured data
• smooth evaluate-js -- <session-id> "code" [--args JSON] - Execute JavaScript
• smooth live-view -- <session-id> - Get interactive live URL
• smooth recording-url -- <session-id> - Get recording URL
• smooth downloads -- <session-id> - Get downloads URL

All commands support --json flag for JSON output.