antigravity-claudekit/skills/ck-agent-browser/SKILL.md

name, description

name	description
ck-agent-browser	Automates browser interactions using headless or visible browser control. Activate when user says 'automate browser', 'scrape website', 'browser automation', 'navigate to URL and extract', 'click buttons on webpage', or 'test UI in browser'. Accepts URLs, CSS selectors, XPath, interaction sequences, and screenshot requests.

Overview

Drives browser automation tasks including navigation, form filling, clicking, scraping, and screenshot capture. Uses Playwright or Puppeteer patterns for reliable cross-browser automation.

When to Use

• User needs to scrape data from a website that requires JavaScript rendering
• Automating multi-step browser workflows (login → navigate → extract)
• Taking screenshots of web pages for visual testing or documentation
• Filling and submitting forms programmatically
• End-to-end browser testing without a test framework
• Checking page content or structure of a live URL

Don't Use When

• The target site provides a public REST or GraphQL API (use the API instead)
• Simple static HTML scraping (use fetch + HTML parser)
• Running unit or component tests (use ck-web-testing instead)
• The task requires human verification (CAPTCHA, MFA flows)

Steps / Instructions

1. Identify Automation Goal

Clarify:

• Target URL(s)
• Actions required: navigate, click, type, scroll, wait, extract, screenshot
• Expected output: text, JSON, screenshot file, assertion result

2. Choose Automation Approach

Playwright (preferred):
  - Cross-browser (Chromium, Firefox, WebKit)
  - Auto-waits for elements
  - Built-in screenshot / PDF
  - Network interception support

Puppeteer:
  - Chromium/Chrome only
  - Fine-grained CDP access
  - Slightly lighter for simple scraping

3. Write Automation Script

// Playwright example
import { chromium } from 'playwright';

async function run() {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();

  await page.goto('https://example.com');
  await page.waitForSelector('.target-element');

  const text = await page.textContent('.target-element');
  console.log(text);

  await page.screenshot({ path: 'screenshot.png', fullPage: true });
  await browser.close();
}

run();

4. Handle Common Patterns

Login flow:

await page.fill('#username', process.env.USERNAME!);
await page.fill('#password', process.env.PASSWORD!);
await page.click('[type="submit"]');
await page.waitForURL('**/dashboard');

Extract structured data:

const items = await page.$$eval('.product-card', cards =>
  cards.map(card => ({
    title: card.querySelector('h2')?.textContent?.trim(),
    price: card.querySelector('.price')?.textContent?.trim(),
  }))
);

Wait for network idle:

await page.goto(url, { waitUntil: 'networkidle' });

5. Error Handling

try {
  await page.waitForSelector('.element', { timeout: 5000 });
} catch {
  console.error('Element not found within timeout');
  await page.screenshot({ path: 'error-state.png' });
}

6. Output Results

• Return extracted data as JSON
• Save screenshots to a designated output directory
• Log errors with page URL and selector context

Notes

• Never hardcode credentials; use environment variables
• Respect robots.txt and site terms of service
• Add realistic delays for sites with rate limiting
• Use --no-sandbox flag only in trusted CI environments