# How to Configure Custom Archetypes in modes/_profile.md for Career-Ops

> Learn to configure custom archetypes in modes/_profile.md for Career Ops. Define job relevance and frame your resume using markdown tables for scoring and PDF generation.

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

---

**Career-Ops uses the archetype table in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) to determine job relevance and frame your résumé, requiring you to define target roles, thematic axes, and value propositions in markdown tables that the scoring engine consumes during evaluation and PDF generation.**

Configuring custom archetypes in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) for Career-Ops allows you to define exactly which roles the system should target and how it presents your experience. The repository `santifer/career-ops` creates this file from [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) during the first run, storing your personal target roles and adaptive framing data in the `modes/` directory rather than `config/` to separate user-layer overrides from system defaults.

## Understanding the Archetype Table Structure

The archetype definition lives at the top of [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) in a markdown table with three columns that drive the system's decision-making:

- **Archetype** – The target role name (e.g., **Senior Backend Engineer**), formatted in bold so the parser recognizes it as a primary key.
- **Thematic axes** – Core competencies or focus areas you want highlighted (e.g., *scalability, micro-services, observability*).
- **What they buy** – The value proposition you bring to employers (e.g., *delivers high-throughput APIs with zero-downtime releases*).

According to the source code in [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md), this table structure is mandatory because [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) and [`modes/pdf.md`](https://github.com/santifer/career-ops/blob/main/modes/pdf.md) read these rows when scoring job offers and generating CVs.

## Setting Up Your Profile File

If [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) does not exist, copy the template manually or let the system create it automatically on first launch:

```bash
cp modes/_profile.template.md modes/_profile.md

```

The template contains placeholder archetypes around lines 5-10 and the "Adaptive Framing" table around lines 37-44. Keep the markdown pipe syntax intact (`|`) and maintain the bold formatting (`**...**`) for archetype names, as the rendering logic specifically searches for that pattern.

## Adding and Modifying Custom Archetypes

To add a new target role, append a row to the archetype table following the exact column order. For example, to target Machine-Learning Engineer positions:

```markdown
| Archetype | Thematic axes | What they buy |
|-----------|---------------|---------------|
| **Machine-Learning Engineer** | model training, MLOps, data pipelines | Builds production-grade ML systems that scale |

```

Place this row immediately below the header separator line. The system parses this table during runtime to weight job relevance, so ensure the **Archetype** column remains in bold to signal the parser that this is a primary role definition.

## Mapping Projects with Adaptive Framing

The "Adaptive Framing" table (located around lines 37-44 in the template) links your concrete projects to each archetype. This ensures the scoring engine pulls the correct proof points when generating documents.

Add rows that map your experience to the new archetype:

```markdown
| If the role is... | Emphasize about you... | Proof point sources |
|-------------------|------------------------|---------------------|
| Machine-Learning Engineer | End-to-end model deployment, CI/CD for ML | article-digest.md + cv.md (section 4) |

```

Each row tells [`modes/pdf.md`](https://github.com/santifer/career-ops/blob/main/modes/pdf.md) which sections of your source files to inject into the final CV based on the archetype match detected by [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md).

## Complete Configuration Example

Here is a minimal, working [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) that demonstrates both tables:

```markdown

# User Profile Context -- career-ops

## Your Target Roles

| Archetype | Thematic axes | What they buy |
|-----------|---------------|---------------|
| **Machine-Learning Engineer** | model training, MLOps, data pipelines | Builds production-grade ML systems that scale |
| **Senior Backend Engineer** | scalability, micro-services, observability | Delivers high-throughput APIs with zero-downtime releases |

## Your Adaptive Framing

| If the role is... | Emphasize about you... | Proof point sources |
|-------------------|------------------------|---------------------|
| Machine-Learning Engineer | End-to-end model deployment, CI/CD for ML | article-digest.md + cv.md (section 4) |
| Senior Backend Engineer | Scalable services, observability tooling | cv.md (section 2) + article-digest.md |

```

Save the file to the `modes/` directory. The next evaluation run—such as `node evaluate.mjs <job-url>`—will automatically incorporate these archetypes without requiring additional configuration steps.

## How Career-Ops Consumes Your Archetypes

The system reads [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) at runtime in two critical contexts:

1. **Job Scoring** – [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) evaluates job descriptions against your archetype definitions to calculate relevance scores based on the thematic axes you specified.
2. **Document Generation** – [`modes/pdf.md`](https://github.com/santifer/career-ops/blob/main/modes/pdf.md) injects archetype-specific language into your CV and cover letter, using the "Adaptive Framing" table to select which proof points to emphasize.

As documented in [`docs/CUSTOMIZATION.md`](https://github.com/santifer/career-ops/blob/main/docs/CUSTOMIZATION.md), storing these definitions in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) rather than `config/` ensures that updates to the core repository never overwrite your personal settings, maintaining a clear separation between system defaults and user-layer overrides.

## Summary

- **Archetypes** are defined in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) using a three-column markdown table with bold role names.
- **Create** the file by copying [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) if it does not exist.
- **Edit** the "Your Target Roles" table to define which positions Career-Ops should target and what value you offer.
- **Map** projects to archetypes in the "Adaptive Framing" table so the system knows which experience to highlight.
- **Consume** these configurations automatically in [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) for scoring and [`modes/pdf.md`](https://github.com/santifer/career-ops/blob/main/modes/pdf.md) for CV generation.

## Frequently Asked Questions

### Where should I place my custom archetype definitions?

Place them in [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), not in the `config/` directory. According to [`docs/CUSTOMIZATION.md`](https://github.com/santifer/career-ops/blob/main/docs/CUSTOMIZATION.md), this location ensures your personal settings persist across updates to the core repository, as [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) is user-layer overrides while [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) contains system defaults.

### What happens if I don't use bold formatting for the archetype name?

The parsing logic in Career-Ops looks for bold text (`**Role Name**`) in the Archetype column to identify primary keys. If you omit the asterisks, the system may fail to recognize the entry as a valid archetype, causing scoring and PDF generation to skip that role.

### How do I link specific projects to a new archetype?

Add a row to the "Adaptive Framing" table (around lines 37-44 in the template) specifying the archetype name in the first column, the emphasis angle in the second, and the source files or sections in the third. This tells [`modes/pdf.md`](https://github.com/santifer/career-ops/blob/main/modes/pdf.md) exactly which proof points to extract when generating documents for that specific role.

### Do I need to restart the application after editing [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md)?

No. Career-Ops reads [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) at runtime during each evaluation. Simply save your changes and run your desired mode (e.g., `node evaluate.mjs <job-url>`) to see the new archetypes applied immediately.