Puppeteer

Automate Chrome and Chromium with Puppeteer for scraping, testing, screenshots, and browser workflows.

Security Scan

The skill's stated purpose (Puppeteer browser automation) matches the instructions and required binary (node), but several runtime instructions encourage persistent local storage and autonomous actions that are vague or stealthy (e.g., 'Don't ask — just start naturally' and 'Store ... without mentioning file paths to them'), so the package is coherent but contains scope/behavioral smells the user should review before installing.

Purpose & Capability

Name and description align with the instructions: it's an instruction-only Puppeteer helper and correctly requires the 'node' binary. The files (setup, selectors, waiting, memory-template) are consistent with browser automation and nothing requested is obviously unrelated to that purpose.

Instruction Scope

The SKILL.md and setup.md instruct the agent to create and persist data under ~/puppeteer/, to collect 'target sites' and 'preferred patterns', and to 'store in ~/puppeteer/memory.md without mentioning file paths to them.' setup.md also says 'Don't ask — just start naturally.' Those phrases encourage autonomous file creation and hidden storage of potentially sensitive target/site information and selectors. While storing session data is reasonable for automation, the explicit instruction to hide storage details and to proceed without asking is scope-creep and a privacy/consent risk.

Install Mechanism

This is instruction-only (no install spec), which reduces installation risk. However, setup.md suggests running 'npm install puppeteer' or 'puppeteer-core' if missing. Allowing the agent to run npm installs at runtime can introduce arbitrary third-party code; this is proportionate only if the user explicitly consents and the exact package (and version) is controlled. No downloads from untrusted URLs or archives are present in the skill files.

Credentials

The skill requires no environment variables or external credentials in registry metadata, which is proportionate. It does instruct to accept credentials 'per-script' when needed for login flows, but it does not request or justify persistent credential storage or access to unrelated credentials. That said, the instruction to save usage memory (including target sites) could inadvertently collect sensitive data if the user provides it; the skill does not require nor clearly forbid storing credentials in memory.

Persistence & Privilege

The skill expects to create a persistent folder (~ /puppeteer) and keep a memory.md of targets, patterns, and preferences. Persisting automation state is reasonable, but combined with 'don't ask' and 'don't mention file paths to them' guidance it grants the agent leeway to create and hide persistent artifacts. The skill does not request always:true and does not modify other skills, but the concealment guidance raises a persistence/privacy concern.

What to consider before installing

This skill appears to be a legitimate Puppeteer guide, but it includes instructions that let an agent create persistent files and store details about target sites without explicitly asking the user. Before installing or enabling it: (1) require explicit user consent before the agent creates ~/puppeteer or runs npm install; (2) inspect any scripts the agent writes to ~/puppeteer/scripts/ before executing them; (3) refuse to store credentials in memory.md — only provide secrets directly to ephemeral scripts and delete them after use; (4) consider running automation in a sandboxed account or container and restrict network access if you do not trust the skill owner (source is unknown); (5) if you want tighter control, ask the agent to show exact commands it will run (including npm install package names and versions) and to log all created files for user review. These steps reduce the risk of hidden data collection or inadvertent installation of third-party packages.

Setup

On first use, read setup.md for integration guidelines.

When to Use

User needs browser automation: web scraping, E2E testing, PDF generation, screenshots, or any headless Chrome task. Agent handles page navigation, element interaction, waiting strategies, and data extraction.

Architecture

Scripts and outputs in ~/puppeteer/. See memory-template.md for structure.

~/puppeteer/
├── memory.md       # Status + preferences
├── scripts/        # Reusable automation scripts
└── output/         # Screenshots, PDFs, scraped data

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md
Selectors guide	selectors.md
Waiting patterns	waiting.md

Core Rules

1. Always Wait Before Acting

Never click or type immediately after navigation. Always wait for the element:

await page.waitForSelector('#button');
await page.click('#button');

Clicking without waiting causes "element not found" errors 90% of the time.

2. Use Specific Selectors

Prefer stable selectors in this order:

1. [data-testid="submit"] — test attributes (most stable)
2. #unique-id — IDs
3. form button[type="submit"] — semantic combinations
4. .class-name — classes (least stable, changes often)

Avoid: div > div > div > button — breaks on any DOM change.

3. Handle Navigation Explicitly

After clicks that navigate, wait for navigation:

await Promise.all([
  page.waitForNavigation(),
  page.click('a.next-page')
]);

Without this, the script continues before the new page loads.

4. Set Realistic Viewport

Always set viewport for consistent rendering:

await page.setViewport({ width: 1280, height: 800 });

Default viewport is 800x600 — many sites render differently or show mobile views.

5. Handle Popups and Dialogs

Dismiss dialogs before they block interaction:

page.on('dialog', async dialog => {
  await dialog.dismiss(); // or dialog.accept()
});

Unhandled dialogs freeze the script.

6. Close Browser on Errors

Always wrap in try/finally:

const browser = await puppeteer.launch();
try {
  // ... automation code
} finally {
  await browser.close();
}

Leaked browser processes consume memory and ports.

7. Respect Rate Limits

Add delays between requests to avoid blocks:

await page.waitForTimeout(1000 + Math.random() * 2000);

Hammering sites triggers CAPTCHAs and IP bans.

Common Traps

• page.click() on invisible element → fails silently, use waitForSelector with visible: true
• Screenshots of elements off-screen → blank image, scroll into view first
• page.evaluate() returns undefined → cannot return DOM nodes, only serializable data
• Headless blocked by site → use headless: 'new' or set user agent
• Form submit reloads page → page.waitForNavigation() or data is lost
• Shadow DOM elements invisible to selectors → use page.evaluateHandle() to pierce shadow roots
• Cookies not persisting → launch with userDataDir for session persistence

Security & Privacy

Data that stays local:

• All scraped data in ~/puppeteer/output/
• Browser profile in specified userDataDir

This skill does NOT:

• Send scraped data anywhere
• Store credentials (you provide them per-script)
• Access files outside ~/puppeteer/

Related Skills

Install with clawhub install <slug> if user confirms:

• playwright — Cross-browser automation alternative
• chrome — Chrome DevTools and debugging
• web — General web development

Feedback

• If useful: clawhub star puppeteer
• Stay updated: clawhub sync