How the Job-Application-Assistant Skill File Works in ai-job-search

The job-application-assistant skill is a declarative Claude Code skill defined in .claude/skills/job-application-assistant/SKILL.md that orchestrates a four-step pipeline (research, evaluation, CV tailoring, cover-letter drafting, and interview prep) entirely through markdown configuration files and allowed tool calls.

The job-application-assistant skill file drives the end-to-end job application workflow in the MadsLorentzen/ai-job-search repository. Unlike traditional scripts, this skill contains no executable code; instead, it uses a YAML-fronted markdown manifest that instructs the Claude Code runtime how to fetch postings, evaluate fit against a candidate profile, and generate tailored LaTeX documents. Understanding this architecture is essential for customizing the workflow or adding new evaluation dimensions.

Skill Manifest Structure (SKILL.md)

The entire behavior of the assistant is declared in .claude/skills/job-application-assistant/SKILL.md. This manifest specifies the framework version, allowed tools, and the ordered workflow steps that execute when a user provides a job posting URL or raw text.

Header Declaration

The skill begins with standard metadata declaring its identity and capabilities. According to lines 2, 7, and 8 of SKILL.md, the header defines:

• name: job-application-assistant
• allowed-tools: Read, Write, WebFetch, AskUserQuestion (and others as required)
• framework_version: 1.3.4

This explicit tool gating ensures the skill operates within a sandboxed environment, only performing file I/O and web fetching operations explicitly permitted by the manifest.

Four-Step Workflow Pipeline

Starting at line 17, the Workflow section outlines a declarative pipeline the runtime follows sequentially. Each step references external markdown files containing the actual logic, keeping the manifest clean and the rules auditable.

Step 1 – Research & Evaluate Fit

The first phase (lines 19-27) performs due diligence before any writing begins. The runtime:

1. Fetches the posting using WebFetch and caches the raw text.
2. Conducts company research via the guidelines in 09-web-research.md.
3. Scores the opportunity against the candidate profile using the Job Evaluation Framework defined in 04-job-evaluation.md, rating technical skills, experience, cultural fit, logistics, and career alignment.
4. Presents an evaluation table and uses AskUserQuestion to confirm whether to proceed.

If the user rejects the fit assessment, the pipeline terminates immediately, saving time on poor matches.

Step 2 – Tailor CV

Upon approval, the skill derives a unique <company>_<role> sub-folder identifier (per documents/README.md conventions) and executes the CV tailoring logic (lines 29-35). It loads the most relevant base CV from the cv/ directory, applies LaTeX-based tailoring rules from 05-cv-templates.md (handling section ordering and skill emphasis), and writes the resulting file to cv/main_<company>_<role>.tex.

Step 3 – Write Cover Letter

Next (lines 36-40), the skill generates matching application materials. It follows the tone guidelines in 03-writing-style.md to ensure consistent voice, injects content into the LaTeX cover-letter template from 06-cover-letter-templates.md, and outputs cover_letters/cover_<company>_<role>.tex.

Step 3b – Record the Application

To maintain synchronization with the broader application tracking system, lines 42-46 implement bookkeeping that mirrors the standalone /apply command (see /.claude/commands/apply.md). The skill writes a metadata record containing cv_file, cover_letter_file, source, deadline, and archived text, ensuring that downstream commands like /rank and /scrape can reference the new application entry.

Step 4 – Interview Preparation

The final phase (lines 47-52) invokes the interview-prep framework from 07-interview-prep.md. This generates STAR-format answer bullets, key talking points derived from the company research, and culturally relevant questions to ask the interviewer.

Quick Commands

Lines 71-78 expose shortcuts for power users who want to run individual steps without triggering the full pipeline. These declarations allow users to invoke Step 1 (evaluation only) or Step 4 (interview prep only) via natural language triggers recognized by the Claude Code runtime.

Supporting Configuration Files

The skill relies on a suite of auxiliary markdown files located in .claude/skills/job-application-assistant/ to encode business logic:

• 01-candidate-profile.md – Structured representation of education, experience, and publications used during evaluation and tailoring.
• 02-behavioral-profile.md – Assessment of strengths and ideal work environments for cultural fit scoring.
• 03-writing-style.md – Prescriptive rules for tone, structure, and prohibited constructs (e.g., clichés) enforced during text generation.
• 04-job-evaluation.md – The scoring rubric used in Step 1, defining weights for each dimension.
• 05-cv-templates.md – LaTeX skeleton and section-ordering logic for Curriculum Vitae generation.
• 06-cover-letter-templates.md – LaTeX structure with mandatory placeholders for company-specific customization.
• 07-interview-prep.md – Star-story generation logic and question selection criteria.
• 08-application-forms.md – Guidelines for portal-specific free-text fields when automated forms are required.
• 09-web-research.md – Escalation strategies for HTTP errors (403/404) and verified sources for company intelligence.

Because these are plain markdown files under version control, extending the skill requires only editing text rather than debugging code.

Runtime Execution Flow

When a user executes /apply <URL>, the Claude Code runtime resolves the intent to the job-application-assistant skill based on the tool requirements matching the manifest's allowed-tools list. The execution proceeds as follows:

1. Manifest Loading – The runtime parses SKILL.md and validates the framework version.
2. Step 1 Execution – WebFetch retrieves the posting, and the runtime evaluates it using the logic in 04-job-evaluation.md.
3. User Gate – AskUserQuestion presents the evaluation table; the user must approve continuation.
4. Steps 2-4 Execution – If approved, the runtime performs sequential file reads from the auxiliary markdown files and writes the generated LaTeX outputs to cv/ and cover_letters/.
5. Metadata Commit – A JSON record is written to archive the application state.

No arbitrary code execution occurs; every action is a declarative tool call (Read, Write, WebFetch) orchestrated by the markdown manifest.

Practical Usage Examples

The skill supports both full-pipeline and single-step invocation patterns.

Run the Complete Application Workflow

/apply https://jobindex.dk/job/1234567

This triggers Steps 1-4 sequentially, prompting for confirmation after the fit evaluation.

Evaluate Fit Without Writing Documents

evaluate this job posting https://jobindex.dk/job/9876543

This invokes the Quick Command shortcut defined at line 73 of SKILL.md, executing only Step 1 and returning the evaluation table.

Generate a Tailored CV Manually

write a CV for AcmeCorp_SoftwareEngineer

This triggers Step 2 directly, reading cv/main.tex, applying rules from 05-cv-templates.md, and outputting cv/main_acmecorp_softwareengineer.tex.

Interview Preparation Shortcut

help me prepare for an interview at AcmeCorp

Executes Step 4 only, consuming 07-interview-prep.md to generate STAR bullets and suggested questions.

Summary

• The job-application-assistant skill file (SKILL.md) is a declarative manifest that defines a four-step workflow (research, document generation, bookkeeping, and interview prep) without containing executable code.
• Configuration logic resides in numbered auxiliary markdown files (e.g., 04-job-evaluation.md, 05-cv-templates.md) that control scoring rubrics, LaTeX templates, and writing style.
• The skill uses an explicit allowed-tools list (Read, Write, WebFetch, AskUserQuestion) ensuring sandboxed, auditable execution.
• Step 3b mirrors the standalone /apply command to maintain compatibility with the repository's tracking commands (/rank, /scrape).
• Users can invoke the full pipeline or individual steps via natural language quick commands defined in the manifest.

Frequently Asked Questions

What makes the job-application-assistant skill file different from a traditional Python script?

Unlike imperative scripts, the SKILL.md manifest is purely declarative. It describes what actions to take (fetch URL, evaluate against profile, write LaTeX file) and which files contain the rules, but contains no loops, conditionals, or execution logic. The Claude Code runtime interprets this manifest and performs the tool calls, making the skill inherently sandboxed and version-controllable as markdown text.

How does the skill decide whether to proceed with writing a CV and cover letter?

During Step 1, the skill invokes the Job Evaluation Framework defined in 04-job-evaluation.md to score the posting against the candidate profile across multiple dimensions (technical fit, logistics, culture). It displays this evaluation table via AskUserQuestion and requires explicit user confirmation before proceeding to Step 2. If the user declines, the pipeline terminates.

Can I customize the CV template or evaluation criteria without modifying code?

Yes. Because the skill references external markdown files, you can edit 05-cv-templates.md to change LaTeX section ordering or modify 04-job-evaluation.md to adjust scoring weights. Changes take effect immediately on the next skill invocation because the runtime reloads these files dynamically. No compilation or deployment step is required.

Where does the skill store generated application materials?

The skill derives a folder naming convention <company>_<role> from documents/README.md and writes LaTeX source files to cv/main_<company>_<role>.tex and cover_letters/cover_<company>_<role>.tex. Additionally, Step 3b writes a metadata record (mirroring /.claude/commands/apply.md) to ensure the application is tracked in the repository's central application database.

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