Understanding Career-Ops modes/*.md Files: How Skill Modes Are Defined and Triggered

The modes/*.md files in Career-Ops are declarative Markdown documents that serve as executable specifications for LLM-driven behaviors, triggered by CLI commands that map verbs to these files via a lookup table in AGENTS.md.

Career-Ops employs a unique architecture where skill modes are defined as self-contained Markdown documents rather than traditional code modules. These modes/*.md files reside in the modes/ directory and encode exactly what the system should do when processing specific user intents, from evaluating job descriptions to generating PDFs.

What Are the modes/*.md Files?

Each file in the modes/ directory represents a self-contained skill specification written in plain Markdown. Unlike conventional configuration files, these documents contain natural language instructions, prompting recipes, and structured logic that the LLM interprets at runtime.

The repository includes several core mode files:

• modes/_shared.md — Holds system-wide rules, scoring logic, archetype definitions, and tool configuration applicable to every mode. This file is auto-updatable and should never be edited manually.
• modes/oferta.md — Implements the job-evaluation workflow (blocks A-G) when candidates paste job descriptions or URLs.
• modes/scan.md — Defines the portal-scanning behavior that queries configured job sites and collects fresh URLs.
• modes/pdf.md — Controls PDF generation mode that converts HTML CV templates into PDFs via Playwright.
• modes/apply.md — Guides cover-letter generation and form completion.
• modes/contacto.md, modes/followup.md, modes/patterns.md — Handle LinkedIn outreach, follow-up cadences, and interview pattern analysis respectively.

Language-specific variants are organized in subfolders such as modes/de/, modes/fr/, modes/ja/, modes/tr/, and modes/ua/, enabling localized versions like modes/de/angebot.md for German job evaluations.

How Skill Modes Are Defined

A skill mode is identified strictly by its filename minus the .md extension. The system maintains a static lookup table in AGENTS.md that maps user intents and CLI verbs to specific mode files.

The mapping follows this pattern:

User Intent	Mode File
Evaluate a job posting	oferta.md
Scan job portals	scan.md
Generate CV PDF	pdf.md
LinkedIn outreach	contacto.md
Analyze interview patterns	patterns.md

When the repository operates in a non-English locale, the lookup mechanism automatically searches the appropriate language subfolder (e.g., modes/de/ instead of modes/) for the corresponding filename.

How Skill Modes Are Triggered

Skill mode activation follows a four-step execution pipeline implemented in the CLI entry point:

1. CLI Invocation — The user executes a command such as /career-ops scan or /career-ops evaluate.
2. Mode Lookup — The command parser extracts the verb and consults the Skill Modes table in AGENTS.md to resolve the verb to a specific Markdown file.
3. Prompt Assembly — The system reads the target mode file (using the Read tool) and concatenates its contents with dynamic context including the user's CV (cv.md), profile data, and web search results.
4. Execution & Output — The assembled prompt is sent to the LLM, which follows the instructions in the mode file to generate output written to reports/, output/, or batch/tracker-additions/.

# Example: Triggering the scan mode

/career-ops scan

This command loads modes/scan.md, combines it with current profile data, and executes the portal query logic defined within that file.

Key Mode Files and Their Architecture

modes/_shared.md

This file functions as the system kernel. It contains universal scoring matrices, archetype definitions, and shared tool configurations that every skill mode imports implicitly. Because it is auto-updatable, it ensures all modes adhere to the latest evaluation criteria without individual file modifications.

modes/oferta.md

When a candidate pastes a job description or URL, this file instructs the LLM to produce a structured seven-block evaluation report (blocks A through G). It specifies how to read the candidate's CV, calculate alignment scores, and format the final assessment according to the rules defined in _shared.md.

Localization Structure

The multilingual support relies on a folder hierarchy where language codes prefix the mode filename:

modes/
├── oferta.md          # Default/English version

├── scan.md
└── de/
    ├── angebot.md     # German equivalent of oferta.md

    └── scan.md        # German scan instructions

The CLI resolver checks the configured locale first, falling back to the root modes/ directory if a localized version is absent.

Customization and Version Control

The repository enforces a strict separation between system logic and user customization. Only modes/_profile.md is intended for manual edits—this file contains personal archetypes, tone preferences, and workflow customizations.

All other mode files, including _shared.md, remain under version control and receive automatic updates from the upstream repository. Modifying these directly will result in merge conflicts when the system auto-updates.

Summary

• modes/*.md files are declarative Markdown specifications that define LLM behaviors for specific Career-Ops skills.
• Skill modes are identified by filename and mapped to user intents via the lookup table in AGENTS.md.
• Triggering occurs through a four-step pipeline: CLI invocation → mode lookup → prompt assembly → LLM execution.
• modes/_shared.md provides system-wide rules and scoring logic applicable to all modes.
• Language-specific subfolders enable multilingual support without code changes.
• Customization is limited to _profile.md; other files are auto-updated by the system.

Frequently Asked Questions

Can I edit the modes/*.md files directly?

You should only edit modes/_profile.md for personal customizations. Files like _shared.md, oferta.md, and scan.md are auto-updated by the Career-Ops system and will be overwritten during updates. Modify these only if you intend to fork the repository and maintain your own version.

How does Career-Ops handle multiple languages?

The system supports localization through subfolders named after language codes (e.g., modes/de/, modes/fr/). When configured for a specific locale, the CLI resolver looks for mode files in the appropriate subfolder first, falling back to the root modes/ directory if no localized version exists.

What happens when I run /career-ops evaluate?

The CLI extracts the verb "evaluate" and maps it to modes/oferta.md (or its localized equivalent). It then assembles a prompt containing the mode instructions, your CV from cv.md, and the job description you provided. The LLM processes this to generate the seven-block evaluation report in your reports/ directory.

Where is the skill mode mapping defined?

The authoritative mapping between CLI verbs and mode files is documented in the Skill Modes table within AGENTS.md at the repository root. This table serves as the contract between the command-line interface and the declarative mode specifications.

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