jobyssey/.agents/skills/wellfound-search/SKILL.md

name, version, description, context, enabled, allowed-tools

name	version	description	context	enabled	allowed-tools
wellfound-search	1.0.0	Use this skill to search public startup job listings on Wellfound (wellfound.com, formerly AngelList Talent) by role and US city or remote, or to look up one Wellfound posting. Covers the US startup market (seed to late stage), English postings, with stated compensation ranges and equity on most listings. Trigger phrases: startup jobs, wellfound, angellist jobs, founding engineer openings, "senior engineer jobs at startups in New York", YC startup jobs, remote startup engineering roles.	fork	true	Bash(bun run .agents/skills/wellfound-search/cli/src/cli.ts *)

Wellfound Search Skill

Searches Wellfound startup job listings through its public, robots-allowed SEO landing pages (/role/l/<role>/<city> and /role/r/<role> for remote). No authentication, zero runtime dependencies (bun + fetch + JSON).

⚠️ Personal use only

Wellfound's robots.txt allows the role landing pages this skill reads but disallows /search and the internal /_jobs/ API, and its terms of service restrict automated bulk access. This skill reads one public page per query, the same page a browser loads. Keep volume low (a handful of queries per run, never a crawl), do not use it for commercial or bulk collection, and accept that you run it on your own responsibility.

How the data works (read before interpreting results)

• A role page returns the 20 startups Wellfound ranks for that role + location, each with up to ~3 "highlighted" listings (≈ 50-60 jobs). The highlighted listings are not all for the queried role, so by default the CLI keeps only titles sharing a token with your query; pass --all-listings to see everything (useful for "what else is this company hiring").
• No server-side pagination is exposed: --page other than 1 errors. Widen coverage by varying the role wording (backend engineer, software engineer, senior software engineer, founding engineer, blockchain engineer) and the city.
• /search?q= free-text is disallowed by robots.txt, so --query is slugified into the role path. Use role titles, not skills ("golang" will 404 → empty results).
• Search results already carry the full description (Markdown), compensation (e.g. $172k – $253k), remote, jobType, and the ATS source. detail is only needed for the schema.org view (structured salary, employment type, apply URL).

Commands

Search

bun run .agents/skills/wellfound-search/cli/src/cli.ts search -q "<role>" [flags]

• -q, --query <role>: required. Role title; slugified (e.g. senior software engineer → senior-software-engineer).
• -l, --location <city>: city name or slug (new-york, "San Francisco", austin). Omit, or pass --remote, for the remote page.
• --remote: use /role/r/<role> (remote-anywhere listings, mostly US-remote).
• --jobage <days>: keep jobs whose liveStartAt is within N days (client-side).
• -n, --limit <n>: client-side cap. Results are sorted newest first.
• --format json|table|plain: default json.
• --no-description: JSON without description bodies (discovery pass).
• --all-listings: disable the title-token filter.
• --page <n>: only 1 is accepted (see above).

Detail

bun run .agents/skills/wellfound-search/cli/src/cli.ts detail <id|url> [--format json|plain]

id must be <id>-<slug> (e.g. 4586203-senior-software-engineer) or the full https://wellfound.com/jobs/<id>-<slug> URL copied from a search result's url; Wellfound 404s on a bare numeric id or a wrong slug. Returns title, company, location, posted date, employment type, structured salary, apply URL, and the description as plain text.

Usage examples

# Senior SWE roles at NYC startups posted in the last 14 days
bun run .agents/skills/wellfound-search/cli/src/cli.ts search -q "senior software engineer" --location new-york --jobage 14 --format table

# Founding engineer roles, remote
bun run .agents/skills/wellfound-search/cli/src/cli.ts search -q "founding engineer" --remote --format table

# Blockchain engineers in San Francisco, everything those startups are hiring
bun run .agents/skills/wellfound-search/cli/src/cli.ts search -q "blockchain engineer" --location "San Francisco" --all-listings --format table

# Backend roles, JSON without descriptions, top 10
bun run .agents/skills/wellfound-search/cli/src/cli.ts search -q "backend engineer" --location new-york --limit 10 --no-description

# One posting in full
bun run .agents/skills/wellfound-search/cli/src/cli.ts detail 4586203-senior-software-engineer --format plain

Output

Format	Best for
json	Default; { "meta": { "count", "page", "source" }, "results": [...] }, each with id, title, company, location, date, url, description, compensation, remote, jobType, companySlug, companySize, ats (missing = null)
table	Quick scan: title, company, location, compensation, date, URL
plain	One line per job

Errors go to stderr as { "error": "...", "code": "..." } with exit code 1 (NO_QUERY, BAD_ARG, SEARCH_FAILED, PARSE_FAILED, NOT_FOUND, DETAIL_FAILED).

Notes

• A role/location combination Wellfound has no landing page for returns HTTP 404; the CLI then emits an empty results array (exit 0), not an error.
• location in results is the listing's own locationNames (may list several cities); remote: true listings with no city show Remote.
• date is derived from the epoch liveStartAt; Wellfound re-bumps listings, so it is "last went live", not first posted.
• Wellfound sits behind Cloudflare; an honest UA has been fine at low volume. A 429 triggers backoff (up to 6 retries); persistent 429s mean back off for the day.
• Parsing anchors and the Apollo cache shape are documented in url-reference.md.