jobsearch-apply-mcp: Command for Claude Code

/add-portal - Generate a Job-Portal Search Skill for Your Local Market

You are helping the user build a job-portal search skill for a US job board. The repo ships a worked example of the pattern (freehire-search) — this command turns that pattern into a guided workflow: investigate the portal, scaffold the skill from the canonical structure, and test-run a live query before registering anything.

The generator is country-agnostic: it works for any portal in any market and language. The skills it produces are typically market-specific and live in the user's fork (per repo policy, country-specific portal skills are not merged upstream — the generator is the upstream feature, its output is yours).

$ARGUMENTS may contain a subcommand, a portal URL, or nothing.

Follow these steps in order.

---

Step 0: Parse Arguments

• If $ARGUMENTS contains --list: use Glob with .agents/skills/*/SKILL.md, print a table of installed portal skills (name, market from the description, data source from url-reference.md), and stop.
• If $ARGUMENTS contains a URL: treat it as the portal URL and carry it into Step 1.
• Otherwise: start the interview at Step 1.

---

Step 1: Interview - Portal Basics

Ask the user (skip anything already answered by $ARGUMENTS):

1. Portal URL - the job board's public site (e.g. https://www.seek.com.au, https://www.stepstone.de).
2. Skill name - kebab-case, suffixed -search (e.g. seek-search, stepstone-search). Must not collide with an existing folder in .agents/skills/.
3. Coverage - which US regions or job categories the portal covers. This drives the trigger phrases in SKILL.md.
4. A realistic test query - a job title or skill the user would actually search for, used for the live test in Step 4.

---

Step 2: Investigate the Portal

Do reconnaissance before writing any code. Use WebFetch (or curl via Bash) on the portal:

1. Find the search URL pattern. Load the portal's search page, run a search in the URL bar mentally or via fetch, and identify: the search endpoint, the query parameter, and any parameters for location, posting age, and pagination. Prefer a JSON API if one backs the site (check for /api/ XHR endpoints in the page source); otherwise plan to parse the HTML results page.
2. Fetch one search-results response for the test query and identify the per-result fields: id, title, company, location, posting date, and URL. For HTML, note the class names / attributes that anchor each field. For JSON, note the field paths.
3. Find the detail-page pattern - the URL that returns a single posting's full description, and where the description, deadline, employment type, and apply link live in it.
4. Check access requirements and terms.
   • Fetch robots.txt and check whether the search/detail paths are disallowed.
   • If the portal requires login/authentication to view listings, stop: this pattern only works on public pages. Tell the user and suggest checking whether the portal has an official API.
   • If robots.txt disallows the paths or the portal's terms prohibit automated access, tell the user plainly and let them decide whether to proceed for personal use. If they proceed, the generated SKILL.md must carry a prominent personal-use-only warning (keep volume low, no commercial or bulk use, own responsibility). Prefer a portal with an official API where one exists - it is more reliable than parsing markup, and it avoids the question entirely. A free API key is worth the extra setup step.