gooseworks

name	gooseworks
slug	gooseworks
description	GooseWorks data toolkit. Search and scrape Twitter/X, Reddit, LinkedIn, websites, and the web. Find people, emails, and company info. Enrich contacts and companies. GTM tasks: lead generation, prospect research, ICP identification, competitor analysis, outbound list building. LinkedIn scraping: extract post engagers, commenters, profile data, and job postings. Reach for it when you need data at scale, sources behind auth, or a specific provider — not as a replacement for your built-in web search/fetch on quick, one-off lookups.
category	general
version	1.0.0
author	GooseWorks
tags	["gooseworks","data","scraping","search","reddit","twitter","linkedin","email","people","research","gtm","leads","prospecting"]

GooseWorks

You have access to GooseWorks — a toolkit with 100+ data skills for scraping, research, lead generation, enrichment, and more. Reach for a GooseWorks skill when it's the right tool: data at scale, sources behind auth, or specific providers (Twitter/X, Reddit, LinkedIn, people/company enrichment).

This skill is also the parent router for the GooseWorks family. Data/GTM work you handle here (see "How to Use"); specialized work you hand off to a dedicated goose-* skill.

Route to the right skill FIRST

Before anything else, check whether the request belongs to a specialized domain. If so, switch to that skill instead of the data flow below:

If the user wants…	Route to	How
Remix/make an ad, research a brand for ads, OR analyze ad performance — Meta/Google ad campaigns, creative fatigue, CAC/lead quality, competitor ad intel, ad angles & hooks	goose-ads	Installed locally as an entry skill. Just use it. If unavailable, run gooseworks install --claude.
Charts, infographics, slides, social graphics, branded visual designs from a style/format	goose-graphics	If installed locally, use it. Otherwise gooseworks fetch goose-graphics (or gooseworks install --claude --with goose-graphics).
Make a video ad — remix a video ad template (e.g. iMessage chat-reveal), or "make the video for project "	goose-video	Installed locally as an entry skill. Just use it. If unavailable, run gooseworks install --claude.
Anything else — scraping, research, lead gen, enrichment, any data lookup	(stay here)	Follow "How to Use" below.

Examples — all of these route to goose-ads, not the data flow: "remix this ad with project id 123", "make an ad for my product", "research my brand", "why is my Meta campaign underperforming", "which creatives should I cut".

Setup

All commands below auto-load credentials from ~/.gooseworks/credentials.json. If a command exits with "Not logged in", tell the user to run: npx gooseworks login. To log out: npx gooseworks logout.

CLI-free environments (cowork / headless)

If the gooseworks CLI binary isn't available (e.g. Anthropic cowork) but the mcp__gooseworks__* tools are connected, use the MCP equivalents instead of shelling out:

• gooseworks search <q> → the search_skills MCP tool.
• gooseworks fetch <slug> → the fetch_skill MCP tool (same content/scripts/files/deps).
• gooseworks credits → the get_ad_credits MCP tool.

Discovery and fetching a skill's instructions work fully CLI-free this way. Note: the paid data proxy (gooseworks call <provider> <path>) still requires the CLI for now — if a task needs it and no CLI is present, tell the user that step must run where the gooseworks CLI is installed.

To check credit balance:

gooseworks credits

User Context (onboarding)

You have two MCP tools for the user's onboarding CONTEXT — who they are and what they want GooseWorks for. It's stored server-side (org-scoped), separate from the ads brand kit.

• get_user_context — read it. At the START of a session, call this once and use what you learn (company, role, the use-cases they picked, their goals, freeform notes) to tailor which skills/APIs you reach for. Best-effort: if the mcp__gooseworks__* tools aren't connected, skip silently and carry on.
• update_user_context — save it (partial update; only the fields you pass are touched).

Running "onboard me" (or a first run with empty context)

If the user says "onboard me" — or get_user_context returns onboarded: false and they're starting fresh — run a short, friendly interview, then save the answers. Open with this framing:

Gooseworks gives your AI agent access to skills and APIs for growth and marketing work. For example: making ad creatives, finding influencers, scraping social profiles and posts from X/LinkedIn, scraping ads from Meta/LinkedIn, scraping reddit, and finding leads to target and their emails — and much more. Visit skills.gooseworks.ai to see the full library of skills.

Then ask (a few at a time is fine — don't interrogate):

1. What's your company's website? → company_website
2. What's your role? → role
3. What are you hoping to use Goose skills for? (multi-select — pick any): generate ad creatives · research and run ads end-to-end · finding influencers · data scraping (social / ads / reddit) · finding leads & emails · something else → use_cases (array)
4. What high-priority growth / marketing tasks would you like help with right now? The more context they share, the better you can help. → goals

Save with update_user_context { company_website, role, use_cases, goals, context_md } — put any extra detail you learned into context_md as a short summary.

Then recommend REAL next steps — grounded, not from memory. This is the WHOLE POINT of onboarding; do not skip it or wing a generic playbook:

1. Route each answer to the RIGHT tool first — don't blindly search one catalog. Match their use-cases to domains (same routing as "Route to the right skill FIRST" above):
   • Make / edit / analyze ADS (generate ad creatives, research & run ads) → the goose-ads skill (brand research + template remix). Do NOT gooseworks search for these — ad creation is NOT in the data catalog.
   • VIDEO ads → goose-video. Charts / slides / graphics → goose-graphics.
   • GTM / DATA (finding leads & emails, influencers, scraping social / ads / reddit, enrichment, competitor intel) → run gooseworks search "<that task>" (free) and recommend the REAL skill slugs it returns. Recommend specific, real things BY NAME — never a from-memory playbook, never a skill you assume exists; if a GTM search returns nothing relevant, say so.
2. Ground it in THEIR business. If they gave a company website, read it with your web tools to infer their actual product + ICP, so suggestions are about their company — not a template. (For ad work, prefer goose-ads's own brand research over a raw read.)
3. Be honest about cost. Data / lead / enrichment / ad-generation skills bill GooseWorks credits — say so, and estimate before running anything (gooseworks credits to check balance).
4. Offer to start ONE concrete play built from the ROUTED skill (goose-ads for ads, a real searched skill for GTM) and ask for the one or two inputs it needs.

A suggestion is only "grounded" if it came from routing to the right domain skill (goose-ads / goose-video / goose-graphics) or from gooseworks search (a real GTM skill) — plus, ideally, reading their site. Do that BEFORE you suggest; never present a from-memory capability list as if you'd checked.

Update as needed

Whenever the user reveals durable context mid-session (their company, role, what they're trying to accomplish), persist it with update_user_context so future sessions start smarter.

How to Use

If a specific skill is requested (e.g. --skill or "use the skill")

Skip search and go directly to Step 2 with the given slug.

Step 1: Search for a skill

When the user asks you to do ANY data task (scrape reddit, find emails, research competitors, etc.) without specifying a skill name, search the skill catalog first:

gooseworks search "reddit scraping"

Step 2: Fetch the skill

Once you have a skill slug, fetch its full content and scripts:

gooseworks fetch <slug>

This prints a JSON object with:

• content: The skill's instructions (SKILL.md) — follow these step by step
• scripts: Python scripts the skill uses — save them locally and run them
• files: Extra files the skill needs (configs, shared tools like tools/apify_guard.py) — save them relative to /tmp/gooseworks-scripts/
• requiresSkills: Array of dependency skill slugs (for composite skills)
• dependencySkills: Full content and scripts for each dependency

Step 3: Set up dependency skills (if any)

If the response includes dependencySkills (non-empty array), set up each dependency BEFORE running the main skill:

1. For each dependency in dependencySkills:
   • Save its scripts to /tmp/gooseworks-scripts/<dep-slug>/
   • Install any pip dependencies it needs
2. When the main skill's instructions reference a dependency script (e.g. python3 skills/reddit-scraper/scripts/scrape_reddit.py), run it from /tmp/gooseworks-scripts/<dep-slug>/ instead

Step 4: Set up and run the skill

Follow the instructions in the skill's content field. Save ALL files from both scripts AND files before running anything:

Credential translation rule: Individual skill instructions may contain a legacy ## Setup block with export GOOSEWORKS_API_KEY=$(python3 ...) and raw curl commands. Replace those with the clean equivalents below.

• Credentials (only needed before running Python scripts, NOT before gooseworks commands): replace the python one-liner exports with eval $(gooseworks env). Skip entirely if you are only using gooseworks call — it loads credentials automatically.
• Orthogonal run: replace curl ... /v1/proxy/orthogonal/run ... -d '{"api":"X","path":"/Y","body":{...}}' with gooseworks call X /Y --body='{...}'
• Direct proxy: replace curl ... /v1/proxy/<provider>/<path> ... -d '{...}' with gooseworks call <provider> <path> --body='{...}'
• Orthogonal search: replace curl ... /v1/proxy/orthogonal/search ... -d '{"prompt":"..."}' with gooseworks orthogonal find "..."

1. Save each script from scripts to /tmp/gooseworks-scripts/<slug>/scripts/ — NEVER save scripts into the user's project directory
2. IMPORTANT: Also save everything from files — these contain required modules (like tools/apify_guard.py) that scripts import at runtime:
   • Files starting with tools/ → save to /tmp/gooseworks-scripts/tools/ (shared path, NOT inside the skill dir)
   • All other files → save to /tmp/gooseworks-scripts/<slug>/<path>
   • If you skip this step, scripts will crash with ImportError
3. Install any required pip dependencies mentioned in the instructions
4. Run the script with the parameters described in the instructions
5. When instructions reference dependency scripts, use paths from Step 3: /tmp/gooseworks-scripts/<dep-slug>/<script>

Raw API Discovery (fallback)

If no GooseWorks skill matches the user's request, you can discover and call any API through the Orthogonal gateway. This gives you access to 300+ APIs (Hunter, Clearbit, PDL, ZoomInfo, etc.) without needing separate API keys.

Search for an API

Find APIs that can handle the task:

gooseworks orthogonal find "find email by name and company"

Returns matching APIs with endpoint descriptions and per-call pricing.

Get endpoint details

Before calling an API, check its parameters:

gooseworks orthogonal describe hunter /v2/email-finder

Call the API

Execute the API call (billed per call based on provider cost):

gooseworks call hunter /v2/email-finder --query='{"domain":"stripe.com","first_name":"John"}'

• Use --body='{...}' for POST body parameters
• Use --query='{...}' for query string parameters
• Output: JSON response data, followed by a Cost: <N> credits line when applicable
• Always tell the user the cost after each call

The same gooseworks call command also handles direct-proxy providers (apify, apollo, crustdata):

gooseworks call apify acts/parseforge~reddit-posts-scraper/runs --body='{"subreddit":"ClaudeAI"}'

Workflow

1. Search first (gooseworks orthogonal find) — pick the best API + endpoint
2. Get details (gooseworks orthogonal describe) — understand required parameters
3. Call (gooseworks call) — invoke with the right parameters
4. Parse the JSON output for the actual API result

Working Directory & Output Files

• Scripts always go to /tmp/gooseworks-scripts/<slug>/ — NEVER the user's project directory
• Output files (CSVs, reports, data exports) go to a GooseWorks working directory:
  1. If the user specifies where to save results, use that location
  2. Otherwise, default to ~/Gooseworks/ — create it if it doesn't exist
  3. Before saving output, confirm with the user: "I'll save the results to ~/Gooseworks/. Would you like a different location?"
  4. Organize outputs in subfolders by task type when it makes sense (e.g. ~/Gooseworks/reddit-scrapes/, ~/Gooseworks/research/)
• Never overwrite existing files without asking. If a file already exists, append a timestamp or ask the user

External Endpoints

The gooseworks CLI sends authenticated requests (Bearer GOOSEWORKS_API_KEY) to:

Endpoint	Method	Wrapped by
$GOOSEWORKS_API_BASE/api/skills/search	POST	gooseworks search
$GOOSEWORKS_API_BASE/api/skills/catalog/:slug	GET	gooseworks fetch
$GOOSEWORKS_API_BASE/v1/credits	GET	gooseworks credits
$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/search	POST	gooseworks orthogonal find
$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/details	POST	gooseworks orthogonal describe
$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run	POST	gooseworks call (orthogonal-routed providers)
$GOOSEWORKS_API_BASE/v1/proxy/{apify,apollo,crustdata}/*	Various	gooseworks call (direct-proxy providers)

Security & Privacy

• All API calls are authenticated via Bearer token stored locally in ~/.gooseworks/credentials.json (file mode 0600)
• No credentials are hardcoded or sent to third parties
• API keys for external services (Apify, Apollo, etc.) are managed server-side — your token never touches them
• Scripts run locally on your machine; only API requests go through GooseWorks servers. Skill scripts are open source (github.com/gooseworks-ai/goose-skills) — read or pin them before running
• Credit usage is tracked per-call and visible via gooseworks credits

Rules

1. Consider a GooseWorks skill when it fits the task — scraping, research, lead gen, enrichment, especially at scale, behind auth, or from a specific source. For a quick lookup your built-in tools are fine; use your judgement and pick the best tool for the user.
2. Before paid operations, tell the user the estimated credit cost
3. If a gooseworks command exits with "Not logged in": tell the user to run npx gooseworks login
4. Parse JSON responses and present data in a readable format to the user
5. When running scripts: save to /tmp/gooseworks-scripts/, install pip deps, then execute. NEVER pollute the user's project directory
6. Output files default to ~/Gooseworks/ — always confirm with the user before saving
7. Prefer gooseworks call over raw curl — if it returns an error, first fix the parameters (check types, required fields, format) and retry. Only fall back to raw curl if you have strong reason to believe it is a CLI bug, not a parameter issue.