How to Add and Discover New Job Portals Automatically in AI Job Search

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 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 manifest is automatically incorporated into the scraping pipeline.

The Agent Skill Contract

Every portal integration follows a standardized contract centered around the 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 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 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.

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 <portal-name>-search with a standardized CLI layout identical to shipped portals. For example, running /add-portal https://example.com/jobs creates:

.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 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 (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)

This means newly added portals are instantly part of the scrape pipeline. The discovery logic effectively runs:

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:

/ scrape

CI Pipeline Integration

The continuous integration workflow in .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/<portal-name>-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 files, as implemented in .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 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 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 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/<portal-name>-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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}