# Where to Put Personal Customizations in Career-Ops Configuration: The Complete Guide

> Learn where to put personal customizations in career-ops configuration. Keep your settings safe from updates by using profile.yml, modes/_profile.md, and portals.yml.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Place all personal customizations in [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml), and specific template files while leaving system defaults untouched to ensure updates never overwrite your settings.**

The `santifer/career-ops` repository separates user-specific data from system-wide defaults through a strict file hierarchy. By confining your edits to designated personal customization files, you protect your bespoke settings from being overwritten when pulling upstream updates.

## Core Identity and Targeting Configuration

Your professional identity, compensation expectations, and job targeting logic live in centralized YAML files that drive the entire system's scoring and generation pipeline.

### Profile Details in [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml)

The [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) file serves as the single source of truth for your identity and job-targeting logic. All modes read this file to drive candidate scoring, work-authorization signals, and CV generation.

Store your name, contact information, target roles, professional narrative, compensation requirements, and location filters here:

```yaml
candidate:
  name: Jane Doe
  email: jane@example.com
  location: Berlin, DE
target_roles:
  - Senior Backend Engineer
  - AI Product Manager
narrative:
  headline: "Building AI‑first products that scale"
  superpowers: "Distributed systems, LLM integration"
compensation:
  target_range: "120k-150k EUR"
  currency: EUR

```

### Archetype Definitions in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md)

The [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) file contains the **Target Roles** definition table that shapes offer scores and CV language. Edit the Markdown table under the **Target Roles** heading to determine how opportunities are evaluated and how your resume is framed for each archetype.

```markdown
| Archetype               | Thematic axes            | What they buy |
|------------------------|--------------------------|---------------|
| Senior Backend Engineer | Go, microservices, CI/CD | Scalable systems |
| AI Product Manager      | Product vision, LLMs, data pipelines | AI‑driven products |

```

## Job Portal and Search Configuration

Control which jobs are scraped and how titles are filtered through dedicated portal configuration files.

### Search Queries in [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml)

Copy [`templates/portals.example.yml`](https://github.com/santifer/career-ops/blob/main/templates/portals.example.yml) to [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml) in your project root to configure keywords, search queries, and tracked companies. This file determines which postings are scraped and how titles are filtered:

```yaml
title_filter:
  positive:
    - "backend engineer"
    - "machine learning"
  negative:
    - "intern"
    - "senior java"
search_queries:
  - "backend engineer site:linkedin.com/jobs"
tracked_companies:
  - "Google"
  - "Microsoft"

```

## Visual and Content Customization

Modify the output appearance and supporting documents without altering the core logic.

### CV Template Styling in [`templates/cv-template.html`](https://github.com/santifer/career-ops/blob/main/templates/cv-template.html)

Adjust design tokens, colors, fonts, and layout in [`templates/cv-template.html`](https://github.com/santifer/career-ops/blob/main/templates/cv-template.html). The accompanying CSS and `fonts/` folder control HTML/LaTeX rendering. Keep modifications ATS-friendly while personalizing the visual presentation:

```html
<style>
  :root {
    --primary-color: hsl(187,74%,32%);
    --accent-color: hsl(270,70%,45%);
    --font-heading: "Space Grotesk", sans-serif;
    --font-body: "DM Sans", sans-serif;
  }
</style>

```

### Negotiation Scripts in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md)

Replace the example scripts in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) with your own wording for salary discussions. These provide ready-to-use text for negotiations but do not affect scoring algorithms:

```markdown

### Salary Negotiation

- **Target range:** 130k–150k EUR
- **Geographic arbitrage:** Emphasize cost‑of‑living differences
- **Pushback response:** "Based on market data and my impact, I’m confident this range reflects my value."

```

## Advanced and Optional Customization

Extend functionality through IDE-specific hooks and workflow modifications.

### IDE Hooks in [`.claude/settings.json`](https://github.com/santifer/career-ops/blob/main/.claude/settings.json)

Add session-start commands and integrations in [`.claude/settings.json`](https://github.com/santifer/career-ops/blob/main/.claude/settings.json) for Claude Code. OpenCode users should use `.opencode/commands/` or `.opencode/agents/` instead:

```json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "echo 'Career‑ops session started'"
      }]
]
  }
}

```

### Workflow State Extensions in [`templates/states.yml`](https://github.com/santifer/career-ops/blob/main/templates/states.yml)

Only modify [`templates/states.yml`](https://github.com/santifer/career-ops/blob/main/templates/states.yml) when extending the tracker's state machine. This file defines canonical workflow states, with related logic in `normalize-statuses.mjs` and references in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md). Most users should never edit this file unless adding entirely new tracker states.

## Summary

- **Edit only** [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml), [`templates/cv-template.html`](https://github.com/santifer/career-ops/blob/main/templates/cv-template.html), and [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) for standard personal customizations.
- **Never modify** system defaults in untouched template files unless you intend to change shared behavior for every user.
- **Copy example files** (such as [`templates/portals.example.yml`](https://github.com/santifer/career-ops/blob/main/templates/portals.example.yml) to [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml)) before editing to establish your personal layer.
- **Preserve update safety** by keeping custom hooks in [`.claude/settings.json`](https://github.com/santifer/career-ops/blob/main/.claude/settings.json) and rare state modifications in [`templates/states.yml`](https://github.com/santifer/career-ops/blob/main/templates/states.yml).

## Frequently Asked Questions

### Will updating the career-ops repository overwrite my personal settings?

No, provided you edit only the designated personal customization files. The repository architecture intentionally separates user-specific data in [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml), and user-copied templates from system-wide defaults. Files you create or modify in these specific paths persist safely through git pulls and updates.

### How do I configure job search keywords for specific portals?

Create a [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml) file in your project root by copying [`templates/portals.example.yml`](https://github.com/santifer/career-ops/blob/main/templates/portals.example.yml). Edit the `title_filter` sections for positive and negative keyword matching, and modify `search_queries` to control which jobs are scraped from each portal.

### Can I customize the visual appearance of generated CVs?

Yes, modify [`templates/cv-template.html`](https://github.com/santifer/career-ops/blob/main/templates/cv-template.html) to adjust CSS design tokens such as `--primary-color`, `--accent-color`, and font families. You can also replace fonts in the `fonts/` folder. Maintain ATS-friendly standards while customizing the visual output for PDF generation.

### Where should I add custom automation hooks for Claude Code?

Define custom hooks in [`.claude/settings.json`](https://github.com/santifer/career-ops/blob/main/.claude/settings.json) using the `SessionStart` event type to run commands when your IDE session begins. These optional extensions allow integrations without affecting the core career-ops logic or other users' environments.