Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MadsLorentzen/ai-job-search/llms.txt

Use this file to discover all available pages before exploring further.

The framework ships with search skills for four Danish job portals — Jobindex, Jobnet, Akademikernes Jobbank, and Jobdanmark — plus the country-agnostic linkedin-search skill that works for any market. If your job market uses different portals, /add-portal lets you add them. Give it a public job board URL and it investigates the portal’s search structure, scaffolds a complete CLI skill matching the architecture of the shipped tools, and test-runs a live query before registering anything. The generator is country-agnostic; the skills it produces are market-specific and live in your fork.

​
Usage

/add-portal
/add-portal https://www.seek.com.au
/add-portal --list
With no arguments, /add-portal starts an interview to collect the portal details. Passing a URL skips straight to the investigation step. --list prints a table of all portal skills currently installed in .agents/skills/.

​
How It Works

1

Interview: portal basics

/add-portal collects four things: the portal URL, a skill name in kebab-case with a -search suffix (e.g. seek-search, stepstone-search), the market and language the portal covers — including local-language trigger phrases for the skill definition — and a realistic test query (a job title or skill you’d actually search for) used for the live test later.
2

Investigate the portal

Before writing any code, /add-portal fetches the portal and does reconnaissance: it identifies the search URL pattern, query parameters (keyword, location, posting age, pagination), and result fields (id, title, company, location, date, url). It also finds the detail-page pattern — the URL structure for a single posting and where the description, deadline, and apply link live. Finally, it checks robots.txt and the portal’s terms of service to determine access rules.
3

Scaffold the skill

Using the canonical linkedin-search skill as the structural reference, /add-portal generates a complete skill directory at .agents/skills/<name>/:
<name>/
├── SKILL.md              # Skill definition with trigger phrases
├── url-reference.md      # Endpoint documentation from the investigation
└── cli/
    ├── package.json
    ├── tsconfig.json
    ├── README.md
    ├── src/
    │   ├── cli.ts        # Arg parsing, help text, command dispatch
    │   ├── helpers.ts    # Fetch with backoff, parsers, error writer
    │   └── commands/
    │       ├── search.ts
    │       └── detail.ts
    └── tests/
        └── helpers.ts    # runCLI + parseJSON test utilities
All generated skills follow the same command contract as the shipped tools: search and detail commands, standard flags (--query, --jobage, --page, --limit, --format, and --location where the portal supports it), JSON output with { "meta": { "count", "page" }, "results": [...] }, and errors on stderr as { "error": "...", "code": "..." } with exit code 1. This contract makes every generated skill interchangeable with the built-in ones for /scrape.
4

Test and register

/add-portal installs dev types, runs a typecheck, then executes a live search with the test query and verifies that titles, companies, and URLs come back populated. It also runs detail on one result from the search. If any field comes back null or garbled, parsers are fixed and the test re-runs. The full test suite must pass before the skill is registered to .agents/skills/. Optionally, the portal can be added to the search strategy in .claude/skills/job-scraper/search-queries.md so /scrape includes it automatically.

​
Access Rules

Auth-walled portals are declined — /add-portal only works with portals whose job listings are publicly accessible without logging in. If a portal requires authentication to view listings, the command will stop and suggest checking whether the portal has an official public API instead.Portals with restrictive robots.txt entries or terms that prohibit automated access are flagged, and the decision is left to you. If you proceed, the generated SKILL.md will carry a prominent personal-use-only warning (matching the tone of linkedin-search): keep request volume low, no commercial or bulk use, your own responsibility.

​
Generated Skill Structure

Every skill generated by /add-portal follows this directory layout: 
.agents/skills/<name>/
├── SKILL.md            # Name, description with trigger phrases, allowed tools, usage examples
├── url-reference.md    # Search endpoint, parameters table, response structure, parsing anchors
└── cli/
    ├── package.json    # name: <portal>-cli, type: module, scripts: start/test/typecheck
    ├── tsconfig.json
    ├── README.md
    ├── src/
    │   ├── cli.ts
    │   ├── helpers.ts
    │   └── commands/
    │       ├── search.ts
    │       └── detail.ts
    └── tests/
        └── helpers.ts
By default, generated skills have zero runtime dependencies — they run with plain bun and use fetch plus regex parsing, so bun install only pulls TypeScript dev types. A parsing library is only added when the portal’s markup genuinely requires it, and that decision is documented in the README. The url-reference.md file is particularly important: it records the specific endpoints, parameter names, and HTML/JSON field anchors discovered during investigation, so that if the portal changes its markup later, you know exactly what to update.

​
Country-Agnostic Starting Point

The linkedin-search skill included in the framework is a zero-dependency universal starting point for any market. Because it uses LinkedIn’s public, unauthenticated jobs-guest endpoints and accepts search location as an explicit flag (-l), it works anywhere: 
bun run .agents/skills/linkedin-search/cli/src/cli.ts search -q "data engineer" -l "Berlin, Germany"
bun run .agents/skills/linkedin-search/cli/src/cli.ts search -q "software engineer" -l "Remote"
If you want broad international coverage without building a market-specific portal first, linkedin-search is the place to start. Keep request volume low — automated access is against LinkedIn’s Terms of Service, and the skill carries a personal-use-only warning. For the full reference of built-in portals, see Job Portals.

Build docs developers (and LLMs) love

Get started for freeTalk to us