为首席幕僚 Agent 编写 talent-scan 斜杠命令：人才市场扫描与招聘建议的工程化落地

本指南围绕 claude-cookbooks 仓库 claude_agent_sdk/chief_of_staff_agent 项目中的 talent-scan.md 展开，讲解如何为基于 Claude Agent SDK 构建的「Chief of Staff（首席幕僚）」Agent 定义一个可复用的招聘型斜杠命令（Slash Command）。读者将掌握 .claude/commands 命令文件的目录结构、frontmatter 约定、$ARGUMENTS 参数传递机制，以及如何通过 recruiter 子代理与 talent_scorer.py 评分脚本，把一条自然语言指令落地成一次完整的「人才市场扫描 → 招聘建议」自动化流程。

talent-scan 在整个项目中的角色

talent-scan.md 位于 claude_agent_sdk/chief_of_staff_agent/.claude/commands/ 目录下，是该项目“命令即提示词模板”体系的一部分。与其并列的还有 strategic-brief.md（综合战略简报）、budget-impact.md（预算影响分析）与 slash-command-test.md（命令机制演示）。

该项目的业务场景是一个虚构公司 TechStart Inc（Series A 轮、50 人团队、月烧钱率约 50 万美元），公司上下文固化在 CLAUDE.md 中；talent-scan 解决的是其中的核心诉求——“Q2 招聘 10 名工程师以加速产品开发”（见 CLAUDE.md 的 Current Priorities）。当负责人输入 /talent-scan 相关问题时，主 Agent 会把任务委派给 recruiter 子代理，由其综合 Web 检索结果、公司薪酬基准与本地脚本输出，产出一份结构化的招聘决策报告。入口演示见 01_The_chief_of_staff_agent.ipynb。

命令文件解剖：frontmatter + 指令主体

一个斜杠命令的本质是“带 YAML frontmatter 的 Markdown 提示词文件”，talent-scan.md 正是最小而完整的示例，其结构如下。

YAML frontmatter：命令如何被识别

文件头部的三行 frontmatter 定义了命令的元信息：

---
name: talent-scan
description: Scan the talent market for specific roles and provide hiring recommendations
---

• name：命令名，即用户输入 /talent-scan 时匹配的标识符，全仓库唯一；
• description：命令用途的一句话描述，供 Agent 与上层调度理解该命令适合处理哪类请求，写法上应包含动作（Scan…）与产出（hiring recommendations）。

slash-command-test.md 中 description: example of how a slash-command works 的写法可作为对照，说明 description 还可充当 Agent 自省时理解命令机制的说明文本。

指令主体：一次人才市场扫描的完整任务清单

frontmatter 结束（---）之后的正文即注入给 Agent 的执行指令。talent-scan.md 的正文由三部分组成，是文章应完整继承的核心内容。

（1）执行入口：命令要求调用 recruiter 子代理，并把用户参数原样透传：

Use the recruiter subagent to perform a talent market scan for: $ARGUMENTS

$ARGUMENTS 是斜杠命令的占位符——用户输入 /talent-scan senior backend engineer in SF 时，$ARGUMENTS 会被替换为 senior backend engineer in SF。对比 budget-impact.md 中 analyze the budget impact of: $ARGUMENTS 与 strategic-brief.md 中 Create a strategic brief on: $ARGUMENTS，可见这是仓库内所有命令统一采用的参数注入约定。

（2）六维扫描分析项：命令要求 recruiter 对以下六个维度逐一分析并报告，它们是人才报告的骨架：

#	分析维度	含义
1	Talent availability in target markets	目标市场的人才供给充足度
2	Competitive salary ranges	有竞争力的薪资区间
3	Required skills and experience levels	岗位所需的技能与经验层级
4	Estimated time to hire	预估招聘周期
5	Recommended sourcing channels	建议的寻源渠道
6	Top candidate profiles (if using GitHub)	顶尖候选人画像（若借助 GitHub 分析）

（3）四项具体建议输出：报告末尾必须给出可执行建议，命令将其归纳为四类：

• Senior vs. junior hiring mix：高/初级招聘配比（直接影响薪资结构与团队成长性）；
• Remote vs. in-office strategy：远程还是办公室办公策略；
• Compensation packages：整体薪酬包设计（薪资 + 股权）；
• Interview process optimizations：面试流程的优化点。

落地依赖一：recruiter 子代理定义

命令中“Use the recruiter subagent”并非空话，其能力边界由同目录 .claude/agents/recruiter.md 定义。该子代理文件同样采用 frontmatter 结构，关键字段包括：

• name: recruiter 与 description（注明“用于招聘决策、团队构成分析与人才市场洞察”，并声明应被主动使用）；
• tools: Read, WebSearch, Bash：限定子代理可用工具——WebSearch 用于调研市场行情，Read/Bash 用于读取公司数据与运行本地脚本。

子代理的系统提示词把职责划分为四块：Talent Pipeline Management（候选人寻源与管道指标）、Hiring Strategy（团队构成与薪酬分析）、Candidate Evaluation（GitHub 履历评估与推荐）、Market Intelligence（人才供给、竞对招聘与远程策略）。其中对本文主题最相关的是 Market Intelligence 与 Hiring Strategy——talent-scan 命令要求输出的“目标市场人才可得性”“竞对薪资”与“远程 vs 办公室策略”正是这些职责的指令级触发。

子代理文档还预置了它与本地资源的绑定关系，可供写作参考：

• WebSearch：调研候选人背景与市场薪资；
• scripts/talent_scorer.py：通过 Bash 调用的人才评分脚本；
• financial_data/hiring_costs.csv：公司各岗位招聘成本数据；
• CLAUDE.md：团队结构与薪酬基准。

落地依赖二：人才评分的本地脚本支撑

talent-scan 命令产生的建议若要落到“具体岗位给多少钱、该不该发 offer”，需要 scripts/talent_scorer.py 提供量化依据。该脚本实现了加权打分模型，权重定义如下（见 talent_scorer.py 的 weights 定义）：

维度	权重	打分逻辑要点
technical_skills	0.30	技术栈匹配度（0-100，取 tech_skills_match，封顶 100）
experience_years	0.20	经验年限阶梯：≤2 年 40 分、≤5 年 70 分、≤8 年 90 分、>8 年回落 85 分（过度资历轻微扣分）
startup_experience	0.15	有创业公司经历 100 分，否则 50 分
education	0.10	high_school 40 / bachelors 70 / masters 85 / phd 90
culture_fit	0.15	默认 75 分，可外部传入 culture_score
salary_fit	0.10	以 salary_expectation 与目标薪资 target_salary 的相对偏差扣分：max(0, 100 - diff_pct*200)

总分落在不同区间会映射为招聘建议（见 get_recommendation）：≥85 → STRONG HIRE（立即发 offer）；75-84 → HIRE；65-74 → MAYBE；50-64 → WEAK；<50 → NO HIRE。脚本同时会输出风险因素，例如技术分低于 60、无创业经历、薪资期望偏差过大或 notice period 超过 30 天。

talent-scan 建议中的“Compensation packages”与“sourcing channels”还能与招聘成本表交叉验证。financial_data/hiring_costs.csv 给出了各角色的基准：Senior Backend Engineer 基础年薪 20 万美元 + 0.2% 股权、总包 22 万；Junior Backend Engineer 11.5 万 + 0.08% 股权；Engineering Manager 22.5 万 + 0.4% 股权等，并包含 Recruiting Fee、Onboarding Cost 与 Monthly Loaded Cost。这些数据是 recruiter 计算“senior/junior 配比成本”与“每月烧钱影响”的直接证据来源。

CLI 用法示例（单候选人 / 批量文件两种模式，见 main 函数）：

# 单候选人打分（8 年经验、技术匹配 90、期望薪资 200K、有创业经历）
python scripts/talent_scorer.py --name "Alice" --years 8 --tech-match 90 --salary 200000 --startup

# 批量排序（从 JSON 文件读取候选人列表，输出 Top 3 排名）
python scripts/talent_scorer.py --input candidates.json --format json

输出字段包括 total_score、各维度 scores、recommendation 与 risk_factors，格式可选 json 或 text——这与 agent.py 中主 Agent 通过 Bash 运行本地 Python 脚本的能力（见下文）无缝衔接。

端到端运行：命令如何被加载与触发

talent-scan 这类命令之所以能被 Agent 识别，关键在于 agent.py 的配置。核心要点在 ClaudeAgentOptions 的构造：

options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    allowed_tools=["Task", "Read", "Write", "Edit", "Bash", "WebSearch"],
    system_prompt=system_prompt,
    cwd=os.path.dirname(os.path.abspath(__file__)),
    # 关键：加载文件系统级设置
    setting_sources=["project", "local"],
)

代码注释明确说明：setting_sources 必须包含 "project" 才能加载文件系统设置，否则 SDK 会以隔离模式运行、不读取任何本地设置。一旦开启，SDK 会从项目目录自动载入四类资源（见 agent.py 顶部 docstring）：

1. Slash commands：来自 .claude/commands/（talent-scan.md 在此被读取）；
2. CLAUDE.md：项目指令上下文；
3. Subagent definitions：来自 .claude/agents/；
4. Hooks：由 .claude/settings.local.json 触发的生命周期钩子。

也就是说，用户只需把 talent-scan.md 放入 .claude/commands/ 目录，并在 agent.py 中保持 setting_sources=["project", "local"]，主 Agent 就能在对话中以 /talent-scan <岗位描述> 的形式触发命令。agent.py 还支持通过 permission_mode 控制执行策略（default 直接执行、plan 仅规划、acceptEdits 允许文件修改），以及通过 output_style 覆盖输出风格（如 executive、technical），后者对应 .claude/output-styles/ 目录下定义的风格模板。

触发后，完整链路可以概括为：

用户输入 /talent-scan <目标岗位>
        │  $ARGUMENTS 替换为具体岗位
        ▼
主 Agent（agent.py，system_prompt 来自 CLAUDE.md + scripts/ 说明）
        │  Task 工具委派
        ▼
recruiter 子代理（.claude/agents/recruiter.md）
        │  WebSearch 调研市场 · Bash 运行 talent_scorer.py · Read 读取 hiring_costs.csv
        ▼
六维人才市场报告 + 四条招聘建议（配比/远程/薪酬包/面试流程）

这条链路同时解释了仓库中 audit/ 目录的成因：.claude/settings.local.json 注册了两个 PostToolUse 钩子——Bash 命中后执行 script-usage-logger.py，Write/Edit 命中后执行 report-tracker.py——从而把脚本调用与报告产出记录到审计日志，实现可追溯的 Agent 决策留痕。

自定义同类命令的工程建议

结合 talent-scan.md 与仓库内其他命令，可总结出在 claude-cookbooks 项目中新增一个“招聘/分析类斜杠命令”的四条经验：

1. frontmatter 三要素必填：name（命令唯一标识）、description（告诉 Agent 何时该用）缺一不可，参考 budget-impact.md 与 strategic-brief.md；
2. 明确委派对象与产出格式：正文第一句即声明“Use the XXX subagent…”，随后用编号列表或表格固定输出结构，保证不同次执行的结构一致性（如 talent-scan 固定六维分析 + 四项建议）；
3. 让 $ARGUMENTS 承载用户变量：把具体岗位、地域等输入留给调用者，命令文件本身保持泛化、可复用；
4. 为子代理配备可执行工具：只有命令文本而没有能力支撑（如 recruiter 的 WebSearch/Bash 与 talent_scorer.py）的报告是空泛的；命令、子代理定义与本地脚本三者需配套演进，并通过 setting_sources=["project", "local"] 统一装载。

整体项目架构与数据流向可进一步参考 flow_diagram.md，运行期行为可在 01_The_chief_of_staff_agent.ipynb 中查看端到端演示。