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.

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, validation, 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).

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?"
• "Set up session reuse so the scrap doesn't re-login on every run"

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 scraps 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):
  Guides you through exporting cookies from your logged-in browser,
  pushes them to account.session.cookies via the persistence endpoint.
  Rewrites the script header to inject cookies before navigation.

Claude (trawl-scrap-local-test):
  Runs scripts/run-local.mjs with your exported 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