# How to Contribute to the AI Job Search Project: A Developer's Guide

> Developers can contribute to the ai-job-search project by submitting workflow improvements, bug fixes, or documentation updates. Learn how to get involved in this open-source AI project.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Developers can contribute to the ai-job-search project by submitting universal workflow improvements, robustness fixes, documentation updates, or CI enhancements that benefit all users of the template, while keeping market-specific features and personal data in private forks.**

The **MadsLorentzen/ai-job-search** repository provides a universal template for an AI-driven job-application workflow designed to work across markets, languages, and personal profiles. Before you contribute to the ai-job-search project, you must understand that all submissions are evaluated against the "universal template" rule defined in [`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md)—changes must improve the core, market-agnostic machinery rather than adding ad-hoc, locale-specific content.

## Understanding the Contribution Philosophy

The project maintains strict scope boundaries to ensure the template remains portable. According to the source code in [`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md) (lines 5-8), contributions are assessed first against the universal template rule, then against execution quality.

### What Gets Merged

Contributions that improve the core framework for every fork include:

- **Universal customization features** — Enhancements to the `/add-template` or `/add-portal` scaffolding that benefit all users, such as the command that registers LaTeX CV/cover-letter templates (referenced in [`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/README.md), lines 48-50).
- **Robustness and correctness fixes** — Patches that make the core workflow more reliable, including fixes to flag validation or HTML entity decoding (see [`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md), lines 11-13).
- **Documentation that closes real gaps** — Expanded setup instructions in [`SETUP.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md) or new "how-to" pages that help newcomers configure the framework.
- **Infrastructure that reduces review burden** — Improvements to [`.github/workflows/ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.github/workflows/ci.yml), [`tools/lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/lint_skills.py), or type-checking configurations that make future contributions easier to verify.

### What Gets Declined

The maintainers will reject contributions that violate the universal template principle:

- Market-specific portal skills (e.g., a French job board) — these belong in personal forks.
- Personal profile data — the template ships with placeholders; users maintain private data in their own forks.
- Duplicate orchestration layers — the markdown specs are the single source of truth; additional wrappers create drift.
- Speculative infrastructure without a proven problem.

## Contribution Workflow

Follow these seven steps when preparing your contribution:

1. **Read the contribution guide** — Study [`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md) to understand the universal template rule and the quality bar for new commands.

2. **Fork the repository** — Create your fork at `https://github.com/yourname/ai-job-search` for development. Your fork is where you can add market-specific portal skills or private profile data.

3. **Identify a suitable improvement** — Look for robustness bugs, missing documentation, or generic features that benefit all users.

4. **Create a focused PR** — Submit one concern per pull request; avoid "kitchen-sink" changes that mix multiple features.

5. **Provide a failing test on master** — Reproduce the bug or missing case by adding a test in `tests/` (Python) or `.agents/.../cli/tests/` (TypeScript).

6. **Run the full CI locally** — Execute `python3 tools/lint_skills.py`, `python3 tools/check_framework_version.py`, and `bun run typecheck` for any touched CLIs, followed by `pytest`.

7. **Submit the PR** — Include a `Co-authored-by` line if you incorporated someone else's code; otherwise credit reviewers in the commit message.

The repository's CI pipeline enforces LaTeX smoke tests, skill linting, and type-checking before any merge can occur (see [`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/README.md), lines 13-15).

## Practical Contribution Examples

### Adding a New Universal Command

To extend the workflow with a new `/upskill` command that performs skill-gap analysis for all users:

```bash

# Clone your fork

git clone https://github.com/yourname/ai-job-search.git
cd ai-job-search

# Scaffold a new command file from an existing template

cp .claude/commands/expand.md .claude/commands/upskill.md

# Edit the command to add a new skill-gap analysis step

# (Modify .claude/commands/upskill.md following the existing markdown format)

# Add a Python test exercising the new step

cat > tests/test_upskill_new_feature.py <<'EOF'
def test_upskill_gap_detection():
    # Set up a minimal profile and dummy posting

    # Run the upskill command and assert expected recommendations

    assert True  # placeholder - replace with real assertions

EOF

# Run CI locally before submitting

python3 tools/lint_skills.py
python3 -m pytest tests/test_upskill_new_feature.py

```

### Improving CI Infrastructure

To enhance the linting rules that validate skill definitions:

```bash

# Modify the lint script to add new validation rules

sed -i 's/old_rule/new_rule/g' tools/lint_skills.py

# Verify that all SKILL.md files still pass validation

python3 tools/lint_skills.py

```

### Updating Documentation

To add clarifications about rate-limiting policies:

```bash

# Edit the README section on job search tools

sed -i '/Job search tools/ a\
- Added note about the new linkedin-search rate-limit policy' README.md

# Build the markdown locally to check rendering

markdown-preview README.md

```

## Key Files and Architecture

Understanding the repository structure helps you target the right location for your changes:

- **[`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md)** — Contribution policy and acceptance criteria (lines 5-8 define the universal template rule).
- **[`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/README.md)** — High-level overview, quick-start guide, and command list.
- **`.claude/commands/`** — Markdown definitions of each slash-command (`/setup`, `/apply`, etc.).
- **`.claude/skills/job-application-assistant/`** — Core skill specification that drives the AI workflow.
- **`.agents/skills/`** — Portable CLI skills for individual job portals (e.g., `linkedin-search`).
- **`tools/`** — CI helpers including [`lint_skills.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/lint_skills.py) and [`check_framework_version.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/check_framework_version.py).
- **`tests/`** — Python test suite covering core utilities and workflows.
- **[`.github/workflows/ci.yml`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.github/workflows/ci.yml)** — GitHub Actions pipeline enforcing LaTeX compiles, linting, and type-checks.

## Summary

- The **MadsLorentzen/ai-job-search** project accepts only universal improvements, not market-specific features.
- Valid contributions include robustness fixes, documentation updates, universal scaffolding features, and CI infrastructure enhancements.
- Always place personal data and locale-specific portal skills in your private fork, not in upstream PRs.
- Run `python3 tools/lint_skills.py`, `bun run typecheck`, and `pytest` locally before submitting to ensure CI compliance.
- Reference specific files like [`CONTRIBUTING.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CONTRIBUTING.md) and follow the one-concern-per-PR rule for faster review cycles.

## Frequently Asked Questions

### Can I add support for a specific job board in my country?

No. Market-specific portal skills—such as integrations for a French or German job board—belong in your personal fork, not the upstream repository. The ai-job-search template is designed as universal infrastructure; localization happens in forks to keep the core maintainable.

### Where should I store my personal CV and profile data?

Never commit personal profile data to the repository. The template ships with placeholder files only. You should maintain your private CV content, contact details, and target job preferences in your own fork, keeping them separate from contributions intended for the main project.

### How do I test my changes before submitting a PR?

Run the full local CI suite: execute `python3 tools/lint_skills.py` to validate skill definitions, `python3 tools/check_framework_version.py` for version compliance, `bun run typecheck` for any TypeScript CLIs you modified, and `pytest` to run the Python test suite. Additionally, ensure LaTeX templates compile correctly if you modified CV generation logic.

### What makes a contribution likely to be merged quickly?

Focus on **universal customization features** that improve the `/add-template` or `/add-portal` scaffolding for everyone, or **robustness fixes** that correct validation bugs. Provide a failing test case that reproduces the issue on master, keep your PR focused on a single concern, and ensure all CI checks pass including linting and type-checking.