What Is the Purpose of the Skills Component in the AI Job Search Framework?

The Skills component in the AI Job Search Framework is a modular plug-in layer that encapsulates domain-specific capabilities through self-contained SKILL.md definitions, enforces a standard CLI contract for job-portal integration, and enables seamless extensibility without modifying core workflows.

The Skills component serves as the architectural backbone of the MadsLorentzen/ai-job-search repository, isolating domain-specific actions such as job-portal searches and CV generation from the core orchestration logic. By defining capabilities as discrete, discoverable modules, the framework ensures that external dependencies remain encapsulated and interchangeable without requiring modifications to the underlying workflow engine.

Three Core Functions of the Skills Component

The Skills component provides three tightly coupled capabilities that power the framework's domain-specific actions.

Encapsulating Reusable Skill Definitions

Each skill is defined by a self-contained SKILL.md file that acts as the single source of truth for that capability. Located in .agents/skills/<skill-name>/SKILL.md for portal-search skills or .claude/skills/<skill-name>/SKILL.md for application-assistant skills, this metadata file declares the skill name, version, description, and an enabled: boolean flag.

Claude Code reads this metadata to determine whether the skill should be invoked during workflow execution. For example, the job-application-assistant skill defined in .claude/skills/job-application-assistant/SKILL.md drives CV and cover-letter generation through the same contract.

Enforcing a Standard CLI Contract

Every portal skill implements a unified CLI contract located at .agents/skills/<portal>/cli/src/cli.ts. This contract requires:

• Command structure: Standardized search and detail subcommands
• Output formats: Support for json, table, or plain via the --format flag
• Common parameters: Consistent flags for query strings, location filters, and job age limits

Because this interface is identical across all portals, the /scrape workflow can auto-discover and execute any installed skill without additional wiring or configuration.

Enabling Seamless Extensibility

New capabilities are added by creating a skill folder that follows the established contract. The framework provides the /add-portal command, defined in .claude/commands/add-portal.md, to scaffold new portal integrations interactively. This generator creates a new directory under .agents/skills/<new-portal>/, populates a SKILL.md skeleton, and runs a live test query. The scraper then automatically discovers the new skill during the next execution cycle because it adheres to the standard folder structure and metadata format.

Practical Usage Examples

The following examples demonstrate how to interact with the Skills component using the LinkedIn portal skill as a reference.

Running a Portal Search

Execute a search using the standardized CLI interface:

bun run .agents/skills/linkedin-search/cli/src/cli.ts \
  search -q "data engineer" -l "Bengaluru, Karnataka, India" \
  --jobage 30 --format table

This command invokes the search subcommand implemented in .agents/skills/linkedin-search/cli/src/cli.ts, returning results in the requested table format according to the skill's SKILL.md specification.

Disabling a Skill

To prevent a skill from being invoked without removing its files, edit the enabled: flag in its SKILL.md:

enabled: false

The /scrape workflow will skip any portal where this flag is set to false.

Adding a New Portal Skill

Use the built-in scaffolding command to create a new skill:

claude
/add-portal

Follow the interactive prompts to supply the portal's base URL. The generator creates the folder structure under .agents/skills/<new-portal>/ and validates the installation with a live test query.

Summary

• The Skills component acts as a modular plug-in layer that isolates domain-specific capabilities from core workflow logic in the MadsLorentzen/ai-job-search framework.
• Each skill is defined by a self-contained SKILL.md file located in .agents/skills/ or .claude/skills/, which declares metadata and an enabled: toggle.
• Portal skills implement a standardized CLI contract in cli/src/cli.ts, supporting search/detail commands and json|table|plain output formats.
• The /add-portal command scaffolds new skills interactively, enabling plug-and-play extensibility without touching existing code.
• The framework auto-discovers skills at runtime, making the system both thin-pointer (no duplicated configuration) and plug-and-play (drop-in additions).

Frequently Asked Questions

How do I disable a specific portal skill without deleting its files?

Edit the enabled: field in the skill's SKILL.md file to false. The framework checks this flag during the discovery phase of the /scrape workflow and will skip any disabled skills while leaving the source code intact for future reactivation.

What distinguishes portal-search skills from application-assistant skills?

Portal-search skills reside in .agents/skills/ and implement the standardized CLI contract for job-board integration (searching and retrieving listings). Application-assistant skills live in .claude/skills/ and handle document generation tasks such as CV and cover-letter creation, utilizing the same SKILL.md metadata structure but serving different domain functions.

How does the /scrape workflow discover available skills?

The workflow scans the .agents/skills/ directory for subdirectories containing a SKILL.md file. It parses the metadata to verify the enabled: flag is true, then invokes the corresponding CLI entry point located at .agents/skills/<portal>/cli/src/cli.ts. This auto-discovery mechanism requires no manual registration or central configuration files.

Can I integrate non-job-board capabilities using the Skills component?

Yes. The Skills component supports any domain-specific capability that adheres to the metadata contract. Create a new folder under .claude/skills/ with a SKILL.md definition and implement the required interface. The framework will treat it as a first-class skill, available for invocation by Claude Code during workflow execution.

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