Skills are pre-built Claude Code workflows that wrap common Trawl operations. Drop the @trawlme/skills package into your Claude Code session and Claude can scaffold scraps, manage sessions, capture banners, and run local tests — all driven by natural language. No boilerplate, no manual CLI incantations.

What's a skill?

A Claude Code skill is a scoped, invokable workflow defined in a markdown file with YAML frontmatter. It gives Claude a focused set of instructions and constraints for a specific task — instead of reasoning from scratch, Claude follows the skill's battle-tested recipe.

The @trawlme/skills package bundles five focused skills. Each is installed as a standalone folder in your Claude Code skills directory and auto-discovered when you start a session.

Install

Option 1 — npx (no global install)

# User-level (available across all projects)
npx @trawlme/skills install

# Project-level only
npx @trawlme/skills install --local

# One specific skill
npx @trawlme/skills install trawl-scrap-design

Option 2 — via the CLI (if @trawlme/cli is installed)

trawl skills install          # installs all skills to ~/.claude/skills/
trawl skills install --local  # project-level
trawl skills update           # reinstall to sync with CLI version

Restart Claude Code after install — skills auto-trigger from that point on.

trawl login also bootstraps any bundled skill you don't already have — the one command that installs skills as a side effect of something else, since it's the one intentional human setup moment. It tells you exactly what it installed and reminds you to restart Claude Code. Every other CLI command only ever suggests running trawl skills install; opt out of the login-time install with TRAWL_SKILLS_SYNC=0.

Bundled skills

trawl-scrap-design

Use when: writing or fixing the Puppeteer script that runs inside a Trawl worker.

Covers selector strategy, returnData shape, parameters, anti-patterns (what the worker already handles so you shouldn't duplicate). When a run returns 0 items, ask Claude to fix it — the skill walks through root-cause analysis.

Example prompts:

• "Create a scrap that extracts product names and prices from https://example.com/shop"
• "My scrap returns 0 items since the site redesigned — fix the selector"
• "Why does my scrap fail? Here's the error: ..."

trawl-scrap-account

Use when: the target site requires authentication and you need to scrape behind a login.

Covers three flows: Trawl-managed credentials (username + password stored encrypted, injected as account.username / account.password), BYO-cookies embedded in script (flavour A, quick experiments), and BYO-cookies persisted via the API (flavour B, MFA / SSO / OAuth without giving credentials to Trawl). For flavour B, Claude points you at trawl scraps account session capture <id> — it opens a real Chrome window, you log in there exactly as you normally would (2FA included), and the CLI reads the resulting session over CDP and uploads it. No manual cookie export.

You stay authenticated as yourself throughout — Trawl never sees your credentials, only the resulting session. Responsibility for lawful use of that session stays with you; this isn't legal advice.

When a run reports a login wall, this skill also covers the recovery step: Claude tells you which command to run, you log in, then re-run the scrap. Claude never extracts cookies itself — its own browser tooling can only see non-HttpOnly cookies, which excludes exactly the session cookie that matters on most sites.

Example prompts:

• "Scrape my Shopify admin dashboard — it's behind a login"
• "I don't want to give Trawl my credentials — how do I inject my own cookies?"
• "My scrap says it hit a login wall — what do I do?"

trawl-scrap-local-test

Use when: iterating on a script and wanting to validate it locally before spending proxy budget on the worker.

The harness (scripts/run-local.mjs) injects the same globals as the worker (browser, TRAWL, account, returnData, saveSession), so your script runs unchanged on your machine with headed Chrome. Intentionally uses vanilla puppeteer-core — no fingerprint policy, no proxy — so you're testing script logic, not network surface.

Example prompts:

• "Test my scrap locally before I push it"
• "Debug the returnData shape — run it on my machine"
• "Preview what the scrap would return on https://example.com"

trawl-scrap-banner

Use when: a scrap has shipped to prod and needs a brand-aware 1200×630 banner for the dashboard.

Fetches the site's official logo, composes it over a brand-color gradient, renders via Chrome headless, and uploads via trawl scraps banner. Part of the "Done" convention in the Trawl seed workflow.

Example prompts:

• "Generate a banner for my eBay scrap"
• "Make a banner for scrap 65a1f... — site is Yahoo Finance"

trawl-cli

Use when: managing scraps from the terminal via the @trawlme/cli — listing, creating, running, watching, debugging.

This skill is the Claude-side companion to the CLI. Claude can read your trawl list output, interpret failures, and suggest the right trawl command for the task at hand.

Example prompts:

• "List my failed scraps from last week"
• "Run scrap 65a1f and watch the output"
• "Show me the history for my Amazon price watcher"

Workflow example: build a scrap for an authenticated site

Here's how skills chain together in a real Claude Code session after npx @trawlme/skills install:

User:  Scrape the order history from my Shopify account.
       The page is at https://mystore.myshopify.com/account/orders.
       I don't want to give Trawl my password.

Claude (trawl-scrap-design):
  Creates script skeleton — page.goto(TRAWL.url),
  selects order rows, returns array via returnData().

Claude (trawl-scrap-account — Flavour B):
  Tells you to run `trawl scraps account session capture <id>`.
  A real Chrome window opens — you log in there, then press Enter.
  The CLI reads the session over CDP and uploads it — no cookies
  ever pass through Claude.

Claude (trawl-scrap-local-test):
  Runs scripts/run-local.mjs with the captured session's cookies.
  Confirms returnData shape before you publish.

Claude (trawl-cli):
  trawl scraps create -t "Shopify orders" -u https://...
  Uploads the tested script, sets a daily schedule.

Result: authenticated scrap live in under 10 minutes, zero credentials stored in plain text.

---

See also: CLI · MCP Server · Using Trawl with Claude

Next step → MCP Server