mirror of
https://github.com/prdlk/jobyssey.git
synced 2026-11-08 16:07:38 +00:00
109 lines
5.9 KiB
Markdown
Executable File
109 lines
5.9 KiB
Markdown
Executable File
---
|
||
name: wellfound-search
|
||
version: 1.0.0
|
||
description: >
|
||
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.
|
||
context: fork
|
||
enabled: true # set to false to keep this portal installed but have /scrape skip it
|
||
allowed-tools: Bash(bun run .agents/skills/wellfound-search/cli/src/cli.ts *)
|
||
---
|
||
|
||
# Wellfound Search Skill
|
||
|
||
Searches **[Wellfound](https://wellfound.com)** 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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`.
|