career-ops 的 SKILL.md 路由解析：多 CLI 求职命令行中枢如何把一句 JD 变成完整流水线

本文深入剖析 career-ops 的技能路由文件 SKILL.md——整个"AI 求职指挥中心"的入口层。你将理解它如何解析项目根目录、把用户输入（子命令、JD 文本或 URL）路由到 30+ 种模式文件、注入统一的语言指令，以及它如何按需加载上下文并委托子代理执行重活。读完后你可以完整复现 career-ops 在 Claude Code、Cursor、Codex、OpenCode 等多种 AI 编码 CLI 中的调用链路与分层加载机制。

career-ops 的定位是"多 CLI 求职指挥中心"（job-search command center）：评估职位、生成 CV、扫描招聘门户、跟踪申请状态。而 SKILL.md 正是这个中心的总路由器（Router）。文档开篇就点明设计原则：

career-ops is a multi-CLI job-search command center. The routing below is shared across supported agent CLIs even when the invocation surface differs.

即：路由语义与调用界面解耦——无论入口是斜杠命令、自然语言还是无头执行，同一套路由表负责把请求分发到正确的模式文件。

一、技能文件的位置与声明式元数据

career-ops 遵循开放代理技能标准（open agent skill standard），Claude Code 入口是 .claude/skills/career-ops/SKILL.md，Cursor 则有对应的 .cursor/skills/career-ops/SKILL.md（SKILL.md 中明确 Cursor 侧"会被自动发现"）。仓库根目录还通过 AGENTS.md、CLAUDE.md、CODEX.md、OPENCODE.md 等入口包装文件覆盖其余 CLI——从 docs/SUPPORTED_CLIS.md 的清单可见，核心逻辑统一收敛在 AGENTS.md，各 CLI 只是薄封装。

SKILL.md 的 YAML frontmatter 是它被技能机制识别的关键：

name: career-ops
description: >-
  AI job search command center -- evaluate offers, generate CVs, scan portals,
  track applications. Use when the user pastes a job URL or JD, asks to scan
  portals, generate a CV/PDF, track applications, prepare for interviews, draft
  outreach/emails, or run any career-ops mode.
arguments: mode
user_invocable: true
user-invocable: true
argument-hint: "[scan | discover | deep | pdf | text | latex | latex-tex | cover | email | add | expand | ...]"
license: MIT

几个值得注意的设计点：

• arguments: mode：整个路由器只接收一个参数 $mode，所有分支逻辑都围绕它展开。
• user_invocable: true：允许用户直接以 /career-ops 形式调用，而非只能由代理内部触发。
• argument-hint：列出全部可用子命令（scan | discover | deep | pdf | text | latex | latex-tex | cover | email | add | expand | … | update），在支持参数补全的 CLI 中提供输入提示。
• description 用"Use when …"句式：这是在告诉代理什么时候该加载本技能（粘贴 JD/URL、要求扫描门户、生成 CV/PDF、跟踪申请、准备面试等），是技能发现的触发语义。

二、项目根目录解析（Project Root Resolution）

SKILL.md 的第一条实质规则是路径解析，这在嵌套检出或子目录启动时至关重要：

Before reading any repo-relative path, derive PROJECT_ROOT from this loaded SKILL.md: start at the skill file's directory and walk upward until the nearest directory containing both AGENTS.md and modes/.

规则要点：

1. 以 SKILL.md 所在目录为起点向上逐级查找，直到找到同时包含 AGENTS.md 和 modes/ 两个哨兵（sentinel）的目录；
2. 路由中涉及的一切路径（modes/、config/、data/、脚本、模板、输出路径）都必须相对 PROJECT_ROOT 解析，绝不相对进程当前工作目录；
3. 若两个哨兵都找不到，停止一切读写，先定位 career-ops 检出位置。

这套哨兵机制保证即使仓库被检出到 Development/career-ops 这类嵌套路径、或命令从子目录发起，路由仍能稳定命中。它与 modes/_shared.md 中"Data Root 解析顺序"（CAREER_OPS_ROOT/CAREER_OPS_DATA_DIR 环境变量 → .career-ops-data 标记文件 → 仓库根默认值）共同构成了 career-ops 的完整路径解析体系：SKILL.md 管系统层文件（技能、模式、脚本），Data Root 规则管用户层文件（cv.md、config/profile.yml、data/）。

三、调用方式：斜杠命令与自然语言的等价映射

SKILL.md 的 Invocation Notes 明确了不同 CLI 的入口差异：

场景	调用方式
支持斜杠命令注册的 CLI	直接 /career-ops
Cursor	技能位于 .cursor/skills/career-ops/ 自动发现；按名称请求模式，或粘贴 JD/URL 触发 auto-pipeline
Codex 交互会话	在仓库根运行 codex；斜杠命令在 Codex 中不保证可用，改为按名称让 Codex 运行同一模式
Codex 无头 worker	codex exec "prompt"

关键是文档强调：路由语义不随入口变化。SKILL.md 给出了两组等价的 Codex 提示词示例：

Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123
Run the career-ops scan mode and summarize new matches.
Run the career-ops pipeline mode for data/pipeline.md.
Run the career-ops pdf mode for the latest evaluated role.
Run the career-ops tracker mode and summarize the current statuses.

以及斜杠命令到自然语言的逐条映射：

/career-ops {JD}      ↔ "Evaluate this JD with career-ops auto-pipeline: {JD or URL}"
/career-ops scan      ↔ "Run the career-ops scan mode and summarize new matches."
/career-ops pipeline  ↔ "Run the career-ops pipeline mode for data/pipeline.md."
/career-ops pdf       ↔ "Run the career-ops pdf mode for the latest evaluated role."
/career-ops email     ↔ "Run the career-ops email mode for the latest evaluated role."
/career-ops tracker   ↔ "Run the career-ops tracker mode and summarize the current statuses."

这个"双入口等价"设计使同一套模式文件可以被交互式会话、无头批处理（codex exec、claude -p）和子代理复用，这也是 modes/_shared.md 中 Spend Tier 模型路由表能按 CLI 维度横向扩展的前提。

四、模式路由表：从 $mode 到模式文件

路由的核心是一张输入→模式映射表。SKILL.md 的完整规则：

输入	模式
（空 / 无参数）	discovery — 显示命令菜单
JD 文本或 URL（无子命令）	auto-pipeline
oferta / ofertas / contacto / deep	同名模式
interview-prep / interview	同名模式
eu-swe / eu-fintech	regional/eu-swe / regional/eu-fintech
interview/plan / interview/practice / interview/debrief	同名子模式
pdf / text / latex / latex-tex	同名输出模式
email / add / expand / training / project	同名模式
tracker / agent-inbox（inbox 别名）/ pipeline / apply	同名模式
scan / discover / batch / patterns / offer-prep	同名模式
titles / upskill / followup / reply-watch / outcome	同名模式
interview-redflag / update / cover	同名模式

路由判定有两条兜底规则：

1. Auto-pipeline 检测：若 $mode 不是已知子命令，但包含 JD 特征关键词（"responsibilities"、"requirements"、"qualifications"、"about the role"、"we're looking for"、公司名+职位名）或一个 JD URL，则执行 auto-pipeline；
2. 非 JD 输入：既非子命令、又不像 JD 时，回落到 discovery 菜单。

路由到模式文件后，modes/{mode}.md 就是该模式的完整执行手册。以 auto-pipeline 为例，modes/auto-pipeline.md 定义了四步流水线：Step 0 用 Playwright/WebFetch 提取 JD（URL 输入优先 browser_navigate + browser_snapshot 渲染 SPA，或选 scan.extractor: cli 时走 browser-extract.mjs 输出紧凑 JSON 省 token）→ Step 0.5 liveness 门禁（死链直接终止，不浪费评估 token）→ Step 0.6 黑名单门禁（比对 data/blacklist.md）→ Step 1 A-G 评估 → Step 2 报告落盘 reports/{###}-{company-slug}-{YYYY-MM-DD}.md → Step 3 按 cv.output_format 分支生成 PDF/LaTeX/文本 CV → Step 4 分数 ≥ 4.5 时草拟申请表答案。路由表本身不关心这些细节，它只保证"正确的输入到达正确的模式文件"。

五、输出语言指令：prose 语言与 market 语境解耦

执行任何模式前，SKILL.md 要求读取 config/profile.yml（用户层文件，运行时从 config/profile.example.yml 复制而来）并解析两个键：

• language.output：面向人类输出的 ISO 语言码，默认 en；
• language.modes_dir：可选的市场模式目录（如 modes/de 对应 DACH 市场），只控制市场词汇与本地评估规则。

随后注入一条强制指令：

Write all human-facing output in {language.output} regardless of the language of these instructions or of the job description. This includes reports, tracker notes, PDFs, cover letters, outreach, interview prep, form answers, and summaries.

解耦原则写得很明确：language.output 对 prose 有最终决定权；modes_dir 只是市场上下文，不得强制 prose 语言。config/profile.example.yml 中的注释印证了这一点——modes_dir 允许"使用 DACH 市场词汇但依然用英文写作"（# modes_dir: modes/de # optional: use DACH market vocabulary while still writing in English）。这种"市场逻辑归市场目录、输出语言归 profile"的分离，使 modes/da、modes/de、modes/zh 等本地化模式目录可以只贡献词汇表而不动全局语言策略。

六、Discovery 菜单：无参数时的完整命令面

无参数调用时，CLI 展示命令菜单。这份菜单本身就是 career-ops 全部能力的索引（节选自 SKILL.md 原文）：

career-ops -- Command Center

Available commands:
  /career-ops {JD}      → AUTO-PIPELINE: evaluate + report + PDF + tracker (paste text or URL)
  /career-ops pipeline  → Process pending URLs from inbox (data/pipeline.md)
  /career-ops oferta    → Evaluation only A-F (no auto PDF)
  /career-ops ofertas   → Compare and rank multiple offers
  /career-ops contacto  → LinkedIn power move: find contacts + draft message
  /career-ops deep      → Deep research prompt about company
  /career-ops interview-prep → Generate company-specific interview prep doc
  /career-ops interview    → Interactive profile/CV onboarding interview
  /career-ops eu-swe    → Calibrate a European SWE application before CV/apply/interview
  /career-ops eu-fintech → Scan 21 EU fintech portals for Product Manager roles (zero-token)
  /career-ops interview/plan → Time-blocked prep plan for an upcoming interview
  /career-ops interview/practice → Practice interview, one question at a time with feedback
  /career-ops interview/debrief → Post-interview debrief: close gaps, predict next round
  /career-ops pdf       → PDF only, ATS-optimized CV
  /career-ops text      → Tailored markdown CV (mirrors cv.md, no PDF)
  /career-ops latex     → Export CV as LaTeX/Overleaf .tex
  /career-ops latex-tex → Tailor your own resume.tex in place (opt-in; cv.md stays default)
  /career-ops cover     → Cover letter: standalone JD paste or /career-ops cover {slug}
  /career-ops email     → Formal application email draft (draft-only; never sends, submits, or clicks)
  /career-ops add       → Add a project/paper/role to your CV (fetch + preview + confirm)
  /career-ops expand    → Auto-discover and add missing competencies from profile links
  /career-ops training  → Evaluate course/cert against North Star
  /career-ops project   → Evaluate portfolio project idea
  /career-ops tracker   → Application status overview
  /career-ops agent-inbox → Queue/drain requests for the next session (data/agent-inbox.md)
  /career-ops apply     → Live application assistant (reads form + generates answers)
  /career-ops scan      → Scan portals and discover new offers
  /career-ops discover  → Resolve a company list to scannable ATS boards + append to portals.yml (zero-token)
  /career-ops batch     → Batch processing with parallel workers
  /career-ops patterns  → Analyze rejection patterns and improve targeting
  /career-ops offer-prep → Read a received offer/contract with the candidate: clause walk + lawyer questions (not legal advice)
  /career-ops titles    → Suggest adjacent job titles from your CV to broaden the search
  /career-ops upskill   → Aggregate skill-gap analysis from your evaluated reports
  /career-ops followup  → Follow-up cadence tracker: flag overdue, generate drafts
  /career-ops outcome   → Record application outcome & archive artifacts
  /career-ops update    → Update career-ops system files with diff preview + compat check

Inbox: add URLs to data/pipeline.md → /career-ops pipeline
Or paste a JD directly to run the full pipeline.

菜单尾部还给出两条工作流提示：向 data/pipeline.md 投递 URL 后用 pipeline 批量处理，或直接粘贴 JD 跑完整流水线。值得注意的是各条目的自我约束措辞——email 强调"draft-only; never sends, submits, or clicks"，offer-prep 标注"not legal advice"——路由层就内置了行为边界声明。

七、上下文分层加载：三种模式的读取集合

路由确定模式后，SKILL.md 规定了执行前必须加载哪些文件，这是控制 token 消耗与防止上下文污染的关键机制。

公共前置：若 modes/_custom.md 存在，读取顺序固定为 modes/_profile.md 之后、选定模式文件之前。该文件存放用户"house rules"（流程偏好），可以覆盖工作流/风格默认值，但永不引入关于候选人的事实声明。

第一类：需要 _shared.md + 模式文件。读取 modes/_shared.md + modes/_profile.md（若存在）+ modes/_custom.md（若存在）+ modes/{mode}.md，适用于：

auto-pipeline、oferta、ofertas、pdf、text、contacto、apply、pipeline、scan、batch

这一类全是"内容生成型"模式，因此必须携带 modes/_shared.md 中的系统规则——包括可信源边界（cv.md、article-digest.md、config/profile.yml、modes/_profile.md 是唯一的内容事实源，"Keywords get reformulated, never fabricated"）、五维评分体系（Match con CV / North Star / Comp / Cultural signals / Red flags，综合为 1–5 全局分）、Spend Tier 模型路由表（spend_tier 的 economy/standard/premium 三档映射到各 CLI 的廉价/均衡/最强模型）以及 Block G 职位真实性三档（High Confidence / Proceed with Caution / Suspicious）。

第二类：独立模式（带 profile 与 custom 上下文）。读取 modes/_profile.md + modes/_custom.md（若存在）+ modes/{mode}.md（不含 _shared.md），适用于：

tracker、agent-inbox、deep、interview-prep、interview、regional/eu-swe、
interview/plan、interview/practice、interview/debrief、latex、latex-tex、
training、project、patterns、titles、upskill、followup、reply-watch、
outcome、cover、email、add、offer-prep、discover

从源码结构看，这个划分对应 modes/ 目录的实际组织：modes/ 下除约 30 个模式文件外，还有 interview/ 子目录（plan/practice/debrief）与 regional/、各语言目录（da/、de/、es/、fr/、hi/、id/、it/、ja/、ko/、nl/、pl/、pt/、ru/、tr/、ua/、zh/、zh-TW/）。独立模式多为"读数据 + 生成单一产物"（跟踪表概览、LaTeX 导出、联系人名录），不需要加载完整的评分规则。

第三类：委托子代理（subagent）的模式。对 scan、apply（使用 Playwright 时）、pipeline（3 个及以上 URL）三种重活模式，SKILL.md 要求把 _shared.md + _profile.md + _custom.md + modes/{mode}.md 的内容注入 worker 提示词，以 worker/subagent 形式启动：

Agent(
  subagent_type="general-purpose",
  prompt="[output language directive]\n\n[content of modes/_shared.md]\n\n[content of modes/_profile.md if exists]\n\n[content of modes/_custom.md if exists]\n\n[content of modes/{mode}.md]\n\n[invocation-specific data]",
  description="career-ops {mode}"
)

注意提示词的拼装顺序是有讲究的：输出语言指令放在最前，然后是共享系统规则、用户档案、house rules、模式文件，最后是本次调用的具体数据。这样即使长上下文中途被截断，最关键的约束（语言、事实源边界）也最不容易丢失。

八、路由层与下层脚本的协作关系

SKILL.md 本身不含业务逻辑，它把每个模式委托给 modes/*.md 手册，而手册又编排仓库根目录下的 .mjs 脚本完成确定性工作——这正是"AI 负责判断、脚本负责执行"的分层。几个典型对应关系（路由模式 → 底层脚本）：

• scan → scan.mjs（Greenhouse/Ashby/Lever API 的零 token 扫描器）、scan-ats-full.mjs（对全量公开 ATS 数据集的关键词扫描，每 500 家公司做 checkpoint，--resume 续扫）；
• tracker → tracker.mjs / set-status.mjs（严格的 states.yml 校验 + 共享锁 + 原子写）；
• pdf → generate-pdf.mjs（Playwright 渲染 HTML 到 PDF）；
• upskill / patterns / followup → upskill.mjs / analyze-patterns.mjs / followup-cadence.mjs；
• update → update-system.mjs（check / apply --confirm / dismiss / rollback 四态更新协议，系统层可自动更新、用户层永不触碰）；
• intake 前置 → doctor.mjs（node doctor.mjs --json 输出 onboardingNeeded/missing/unpersonalized，冷启动门禁）。

更新检查本身也是路由语义的一部分：AGENTS.md 规定每个会话首条消息静默运行 node update-system.mjs check，仅在返回 update-available 时才打扰用户，且明确承诺"Your data (CV, profile, tracker, reports) will NOT be touched"——这与 AGENTS.md 的 Data Contract（用户层 vs 系统层文件二分）严格对应。当前仓库版本见 VERSION（1.31.0）。

九、设计要点小结

回顾 SKILL.md 全文，这个路由文件体现了四条可复用的 Agent 技能设计原则：

1. 单一参数、确定性路由：只暴露 $mode 一个参数，路由表 + 两条兜底规则（JD 关键词检测、discovery 回落）覆盖了全部输入形态，不留模糊分支；
2. 哨兵式根目录解析：以"目录中同时存在 AGENTS.md 与 modes/"为锚点向上回溯，把路径正确性与启动位置、检出位置彻底解耦；
3. 分层上下文加载：三类模式分别绑定不同的文件读取集合，把"内容生成型"模式与"工具型"模式区分开，重活委托子代理并规定提示词拼装顺序，避免主会话上下文膨胀；
4. 语言与市场双轴解耦：language.output 管 prose 语言，modes_dir 管市场词汇，二者互不越权——这是 modes/ 下 17 个本地化目录能够独立演进而不互相干扰的原因。

对希望构建自己"多模式 Agent 技能"的读者，SKILL.md 给出的模板价值很大：frontmatter 声明触发语义与参数、正文先定路径解析、再定路由表、再定上下文加载协议，最后才列发现菜单。career-ops 的全部求职自动化能力，都是从这一份不到 250 行的路由文件开始分发的。