Where Are the Canonical Specifications for AI Agent Runtimes Stored in the AI Job Search Framework?

The canonical specifications for AI agent runtimes in the AI Job Search Framework are stored in the .claude directory at the repository root, implementing a Thin-Pointer design that serves as a single source of truth for all agent implementations.

The MadsLorentzen/ai-job-search repository eliminates configuration drift across multiple AI platforms through centralized specification management. Instead of embedding workflow logic locally, runtimes—including Claude Code, Google Antigravity, Codex, Cursor, and Gemini CLI—dynamically load instructions from this canonical location. This architecture ensures that updates to job scraping protocols, application workflows, or candidate profiles propagate instantly to every connected agent.

The .claude Directory Structure

The repository root contains a .claude directory that organizes all agent specifications into five distinct categories. According to the source code analysis, this structure implements the Thin-Pointer principle documented in AGENTS.md, requiring all runtimes to import from these files rather than duplicate them.

• Workflow specifications — Stored directly in .claude/, these markdown files define step-by-step instructions for core tasks including setup, scrape, rank, apply, upskill, and interview workflows. They specify the exact sequence of operations agents must execute.

• Skill definitions — Located in .claude/skills/, individual markdown files describe discrete capabilities. For example, .claude/skills/job-scraper/SKILL.md contains the complete specification for the job scraping capability, while .claude/skills/job-application-assistant/ contains segmented skill files.

• Command definitions — Found in .claude/commands/, these files map user-facing slash commands such as /setup, /reset, and /rank to their underlying workflow implementations.

• Global settings — The .claude/settings.json file provides repository-wide configuration parameters that agents read at startup to initialize runtime environments and framework versions.

• Candidate profile — Stored as CLAUDE.md in the repository root but referenced from within .claude configurations, this file contains the personal profile, contact details, education history, language table, and job search preferences that all agents consult.

Key Files Implementing the Thin-Pointer Design

The AGENTS.md file at the repository root explicitly documents the Thin-Pointer architecture and points to the .claude directory as the mandatory source of truth. This file instructs developers that any change to workflow logic should occur within the .claude tree, ensuring automatic propagation to all supported runtimes.

Individual skill implementations demonstrate this pattern in practice. The job-scraper skill at .claude/skills/job-scraper/SKILL.md defines scrape parameters, rate limiting, and data extraction rules in a single markdown file that both Claude Code and Python-based agents can parse. Similarly, command definitions like .claude/commands/setup.md standardize initialization procedures across platforms.

Loading Specifications at Runtime

Agents access these canonical specifications through standard file system operations. The following Python implementation demonstrates how a runtime can load both global settings and specific skill definitions:

import json
from pathlib import Path

# Load global settings from .claude/settings.json

SETTINGS_PATH = Path(__file__).parent.parent / ".claude" / "settings.json"
with SETTINGS_PATH.open() as f:
    settings = json.load(f)

# Load a specific skill definition (e.g., the job‑scraper)

SKILL_PATH = Path(__file__).parent.parent / ".claude" / "skills" / "job-scraper" / "SKILL.md"
with SKILL_PATH.open() as f:
    job_scraper_md = f.read()

print("Agent settings version:", settings.get("framework_version"))
print("Job‑scraper description:", job_scraper_md.splitlines()[1])

This approach allows agents to maintain zero local configuration while remaining synchronized with the latest workflow iterations. When the framework reads CLAUDE.md for candidate-specific data or .claude/settings.json for operational parameters, it ensures consistent behavior across disparate AI platforms.

Benefits of Centralized AI Agent Specifications

Implementing canonical specifications in the .claude directory provides three critical advantages for multi-runtime development:

• Configuration consistency — Modifications to .claude/skills/job-scraper/SKILL.md or command definitions immediately affect all runtimes without requiring individual redeployment or synchronization APIs.

• Cross-platform compatibility — Claude Code, Codex, Cursor, and Gemini CLI can execute identical workflow logic because they reference the same markdown and JSON source files.

• Version control integration — Git tracks changes to agent capabilities alongside application code, creating an auditable history of how AI behavior evolves with the framework.

Summary

• The .claude directory at the repository root stores all canonical specifications for AI agent runtimes in the MadsLorentzen/ai-job-search framework.
• The Thin-Pointer design documented in AGENTS.md mandates that agents import from this single source rather than duplicating configuration locally.
• Specifications include workflow instructions, skill definitions in .claude/skills/, command mappings in .claude/commands/, global settings in .claude/settings.json, and the candidate profile in CLAUDE.md.
• Agents load these files at runtime using standard file I/O operations, ensuring automatic propagation of updates across Claude Code, Codex, Cursor, and Gemini CLI implementations.

Frequently Asked Questions

What is the Thin-Pointer design in the AI Job Search Framework?

The Thin-Pointer design is an architectural pattern where all AI agent runtimes reference a single source of truth for their specifications rather than embedding configuration locally. According to AGENTS.md, this ensures that changes to workflows or skills in the .claude directory propagate automatically to every agent including Claude Code, Codex, and Gemini CLI without manual synchronization.

Can I modify the agent specifications without breaking existing runtimes?

Yes, because all runtimes load specifications at startup from the .claude directory. When you update files like .claude/skills/job-scraper/SKILL.md or .claude/settings.json, agents will ingest the new instructions the next time they initialize. The repository treats these markdown and JSON files as canonical configuration, version-controlled alongside the application code.

Where is the candidate profile stored relative to the agent specifications?

The candidate profile resides in CLAUDE.md at the repository root, but it is referenced from within the .claude configuration structure. Agents consult this file for personal details, education history, and preferences when executing personalized workflows like job applications or interview preparation.

Do all AI agent runtimes support loading these markdown specifications?

The framework is designed for compatibility with Claude Code, Google Antigravity, Codex, Cursor, and Gemini CLI. While the specifications are stored as markdown and JSON for human readability, any runtime capable of reading plaintext files can parse the instructions. The Python example in the source code demonstrates how standard file I/O operations can load these specifications into any agent implementation.

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