Skip to main content

Documentation Index

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

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

/add-portal generates a job portal search skill for any job board in any market. The repository ships with four Danish portals (Jobindex, Jobbank, Jobdanmark, Jobnet) and one country-agnostic skill (LinkedIn public listings), but the pattern is designed to be replicated. Give /add-portal a portal URL and a test query and it will investigate the site, scaffold a TypeScript CLI skill with the same structure and output contract as the shipped ones, and run a live query to verify the parsers work before registering anything. The generator is upstream; the skill it produces is yours and lives in your fork.

​
Syntax

/add-portal
/add-portal <url>
/add-portal --list
InvocationBehavior
/add-portalStarts the interview to collect portal URL, skill name, market, and test query
/add-portal <url>Skips the URL question and uses the provided URL
/add-portal --listPrints a table of all installed portal skills (name, market, data source)

​
How it works

1

Interview

/add-portal collects four pieces of information (skipping anything provided in the command arguments):
  1. Portal URL: the job board’s public site (for example, https://www.seek.com.au)
  2. Skill name: kebab-case, suffixed -search (for example, seek-search); must not collide with an existing folder in .agents/skills/
  3. Market and language: which country or region the portal covers and what language its postings use; this drives the trigger phrases in SKILL.md
  4. Test query: a realistic job title or skill to use for the live verification in step 4
2

Investigate the portal

Before writing any code, /add-portal fetches the portal and records everything the parsers will need:
  • Search URL pattern: the search endpoint, query parameter, and any parameters for location, posting age, and pagination. If a JSON API backs the site, that is preferred over HTML parsing.
  • Result structure: per-result fields in a search results page (id, title, company, location, date, and url). For HTML, the class names or attributes that anchor each field. For JSON, the field paths.
  • Detail page pattern: the URL that returns a single posting’s full description, and where the description, deadline, employment type, and apply link live.
  • Access requirements: robots.txt is checked against the search and detail paths.
Auth-walled portals are declined. If the portal requires login to view listings, /add-portal stops and suggests checking whether the portal has an official public API.Restrictive terms or disallowed paths are reported to you, and if you choose to proceed, the generated SKILL.md carries a prominent personal-use-only warning, matching the tone of the linkedin-search skill’s warning section.
3

Scaffold the skill

Using the linkedin-search skill as the canonical reference (zero-dependency, country-agnostic), /add-portal creates .agents/skills/<name>/ with this structure:
<name>/
├── SKILL.md              # Skill definition with trigger phrases in English and market language
├── url-reference.md      # Endpoint documentation from the investigation step
└── 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
Every generated skill honors the portal-skill contract that makes skills interchangeable with the shipped ones:
  • Commands: search and detail <id|url>
  • Search flags: --query/-q, --jobage <days>, --page <n>, --limit <n>, --format json|table|plain (default json); --location/-l if the portal supports it
  • JSON output shape: { "meta": { "count": ..., "page": ... }, "results": [...] } with at least id, title, company, location, date, url per result (missing values are null, never omitted)
  • Errors: written to stderr as { "error": "...", "code": "..." }, exit code 1
  • Dependencies: zero runtime dependencies by default, using plain bun + fetch + regex parsing, matching linkedin-search
4

Test-run a live query (mandatory)

/add-portal never registers a portal skill without verifying it against real data. Markup assumptions from the investigation step routinely miss quirks that only appear live.
cd .agents/skills/<name>/cli && bun install && bun run typecheck
bun run src/cli.ts search -q "<test query>" --limit 5 --format table
The results are checked: titles and companies are populated (not empty strings or HTML fragments), URLs resolve to the portal, and dates parse. Then detail is verified on one id from the results.If fields come back null or garbled, the parsers in helpers.ts are fixed and the query is re-run. The test suite is also run with bun run test. Volume is kept low during iteration./add-portal does not proceed to registration until search, detail, and tests all pass.
5

Register and confirm

If you want the new portal included in /scrape searches, /add-portal adds site-specific queries to .claude/skills/job-scraper/search-queries.md.The skill auto-triggers from its SKILL.md description, so no other wiring is needed.The confirmation message includes the live test result count, the data source endpoint summary, any personal-use warning, and the command to run the skill directly.

​
LinkedIn as the worked example

The linkedin-search skill (.agents/skills/linkedin-search/) is the canonical reference for this pattern. It is country-agnostic (LinkedIn operates globally), carries a personal-use-only warning, and uses zero runtime dependencies. When /add-portal scaffolds a new skill, it copies the architecture of linkedin-search, not its LinkedIn-specific parsing logic.
Per upstream repository policy, market-specific portal skills are not merged upstream. The generator is the upstream feature, and its output belongs in your fork. If a portal changes its markup later, url-reference.md records the parsing anchors you need to update.

/scrape

Use your new portal skill in a job search run

/setup

Configure which portals and queries /scrape uses

/add-template

Register a custom LaTeX template alongside your portal skills

Build docs developers (and LLMs) love

Get started for freeTalk to us