# How to Add and Discover New Job Portals Automatically in AI Job Search > Automatically add new job portals using the add portal command and discover them with the scrape command. No manual registration needed for new job portals in AI Job Search. - Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search) - Tags: how-to-guide - Published: 2026-08-26 --- **New job portals are added via the `/add-portal` command, which scaffolds an Agent Skill in `.agents/skills/`, and are discovered automatically when the `/scrape` command glob-searches for [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) files without requiring manual registration.** The MadsLorentzen/ai-job-search repository treats every job board integration as a modular **Agent Skill** that lives in its own folder under `.agents/skills/`. This architecture allows developers to add new portals automatically and discover them at runtime without hard-coded registries or configuration files. The framework relies on a simple contract: any folder containing a valid [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) manifest is automatically incorporated into the scraping pipeline. ## The Agent Skill Contract Every portal integration follows a standardized contract centered around the [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) manifest file. This file declares the skill's **enabled** status, CLI usage patterns, and documentation. The framework discovers these skills by searching for all [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) files under the `.agents/skills/*` directory structure, making registration a matter of file existence rather than explicit configuration. According to the README (lines 325-329), a skill is considered valid and immediately usable as long as its [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) contains the required metadata and the `enabled` flag is set to `true`. ## Adding a New Portal with `/add-portal` The `/add-portal` command automates the creation of a compliant Agent Skill through a four-step process documented in [`.claude/commands/add-portal.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/add-portal.md). ### Scanning the Target Job Board The command first analyzes the target URL to determine search patterns, result page structures, robots.txt rules, and required authentication tokens. The scraper inspects the job board's HTML layout to identify CSS selectors for job titles, descriptions, and pagination controls. ### Scaffolding the Skill Structure It generates a complete directory structure following the convention `-search` with a standardized CLI layout identical to shipped portals. For example, running `/add-portal https://example.com/jobs` creates: ```text .agents/skills/example-search/ ├─ SKILL.md # Declares enabled: true and CLI usage ├─ cli/ │ ├─ src/ │ │ ├─ commands/ │ │ │ ├─ search.ts # Implements portal-specific search logic │ │ │ └─ detail.ts # Handles individual job detail fetching │ │ └─ ... │ └─ tests/ │ └─ ... ``` ### Live Verification The generated CLI executes a test query to verify it can fetch results and produce the expected JSON contract. This validates that the scaffolded code correctly parses the target site's HTML before the skill is considered complete. ### Zero-Configuration Registration Once created, the skill is immediately available because the [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) file contains `enabled: true`. No additional registration steps or edits to central configuration files are required. As noted in the repository documentation, "nothing else has to be modified" after the folder is added. ## Automatic Discovery via `/scrape` The automatic discovery mechanism is implemented in [`.claude/skills/job-scraper/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/SKILL.md) (lines 61-63). When you invoke `/scrape`, the job-scraper skill executes a glob search for `.agents/skills/*/SKILL.md`. For each manifest found, the framework: 1. Parses the `enabled` boolean flag 2. Extracts CLI flags and arguments from the skill documentation 3. Invokes the appropriate command script (e.g., [`cli/src/commands/search.ts`](https://github.com/MadsLorentzen/ai-job-search/blob/main/cli/src/commands/search.ts)) This means newly added portals are instantly part of the scrape pipeline. The discovery logic effectively runs: ```python for skill_path in glob('.agents/skills/*/SKILL.md'): skill = parse_skill_md(skill_path) if skill.enabled: run_cli(skill_path / 'cli' / 'src' / 'commands' / 'search.ts', args) ``` To execute the scrape and discover all enabled portals automatically: ```bash / scrape ``` ## CI Pipeline Integration The continuous integration workflow in [`.github/workflows/ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.github/workflows/ci.yml) (line 187) leverages the same discovery pattern. Because the CI glob-searches for skill directories using the identical pattern as the scraper, any new portal submitted to the repository automatically undergoes type-checking and testing without workflow modifications. The CI pipeline discovers new skills dynamically, ensuring that additions to `.agents/skills/` are immediately validated. ## Summary - **Agent Skills** are self-contained portal integrations living in `.agents/skills/-search/`. - The `/add-portal` command scaffolds new skills by scanning target sites, generating CLI code, and verifying live connectivity. - **Automatic discovery** occurs via glob-searching [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) files, as implemented in [`.claude/skills/job-scraper/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/SKILL.md) (lines 61-63). - No manual registration is required; a skill becomes active when `enabled: true` appears in its manifest. - The CI pipeline automatically tests new skills because it uses the same discovery logic as the production scraper. ## Frequently Asked Questions ### What file enables automatic discovery of a new portal? The `.agents/skills/*/SKILL.md` file serves as the discovery manifest. The job-scraper skill specifically searches for all [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) files under `.agents/skills/` to identify available portals, read their enabled status, and determine their CLI contracts. ### Do I need to restart the framework after adding a portal? No. Because the `/scrape` command performs a fresh glob search for [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) files at runtime, newly added portals are discovered immediately. The framework has no persistent registry that requires reloading or restart cycles. ### How does the scraper know which CLI arguments to pass to a new portal? The scraper parses the [`SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SKILL.md) manifest for each discovered skill to learn the portal's CLI flags and usage patterns. This documentation-driven approach allows the framework to construct the appropriate command-line arguments without hard-coding portal-specific logic. ### Can I disable a portal without deleting its files? Yes. Set `enabled: false` in the portal's `.agents/skills/-search/SKILL.md` file. The discovery mechanism checks this boolean flag before invoking the CLI, allowing you to temporarily exclude portals from the scrape pipeline while preserving the code for future use.