Agent Skill 路由提示词工程实战解析 routing-prompt.md 与 Skill 路由基准测试设计【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本指南深入解析 Agent-Skills-for-Context-Engineering 仓库中researcher/benchmarks/router/routing-prompt.md这份模型即路由器LLM-as-router基准测试的核心模板。你将掌握如何设计一份让模型只输出严格 JSON 的 skill 路由提示词、模板中的三个占位符如何在 SDK 运行器中被真实填充、以及围绕该模板搭建的描述 → 路由 → 评估 → 改写描述闭环基准测试方法论。读完本文你可以直接复现仓库中的路由基准测试或借鉴这套模板为任意 skill 集合搭建自己的路由评估系统。一、模板定位路由基准测试的唯一试卷routing-prompt.md是仓库 researcher/benchmarks/router/README.md 所描述的Stage 2 Skill Router Benchmarkv2.3.0 已发布中直接喂给 LLM 的提示词模板。它位于 researcher/benchmarks/router/routing-prompt.md完整内容只有约 30 行但承担着核心职责Tests whether the activation-scenario descriptions in v2.2.0 skill frontmatter are good enough to route the right skill to a given prompt.换句话说这份模板检验的不是 skill 正文写得如何而是skill 的激活描述activation description是否足够精确能让一个前沿模型面对陌生任务时从 15 个 skill 中选出正确的那一个。正如 researcher/benchmarks/PLAN.md 所述Skill descriptions are the only signal a deployed agent uses to decide whether to load a skill. If they dont route correctly, the rest of the harness is academic.这就是设计这份模板的出发点描述是 Agent 决定是否加载某个 skill 的唯一信号。因此基准测试必须把描述隔离出来单独考察——这正是模板在运行器中被使用方式settingSources: []不加载任何真实 skill所保证的。模板在基准测试架构中的位置路由基准测试属于仓库 researcher/benchmarks/PLAN.md 四阶段方法论中的第二阶段阶段版本衡量内容成本状态0v2.2.0框架抗作弊能力、结构有效性$0已完成1v2.3.0每个 skill 的健康指标确定性$0已完成corpus 聚合 0.81415 个中 2 个被标记2v2.3.0Skill 路由准确率LLM-as-routerCursor credits每次全量扫描约 $7已完成基线 修复后 delta 已发布3v2.4.0Skill 在真实 Agent 任务上的有效性Cursor credits规模更大已搭建脚手架构建了第一个任务4v2.5.0跨 Skill 组合Cursor credits未来Stage 2 的方法论假设Hypothesis为The activation-scenario descriptions in v2.2.0 frontmatter (replacing v2.1.x keyword triggers) should let a frontier model route prompts to the correct skill at high top-1 accuracy and very high top-3 accuracy.Stage 2 之所以重要是因为它验证了 v2.2.0 用激活场景描述替代 v2.1.x 时代关键词触发器这一重构的有效性。二、模板逐段拆解四段式结构的设计意图routing-prompt.md全文可以分为四个功能段每段都在约束模型行为的一个维度。2.1 角色限定只做一件事You are routing an incoming task to the most relevant skill from a curated collection. Your only job is to pick the best skill.第一句话就把模型限定为路由器并用Your only job明确职责边界。这与 skills/context-fundamentals/SKILL.md 中每个 skill 只负责一个领域、不越界处理运营性工作的设计哲学一致——模板本身也是职责单一原则的实践。2.2 可用 skill 清单三个占位符之一{{SKILL_BLOCK}}# Available skills ({{SKILL_COUNT}}) Each item is name followed by the skills activation description. {{SKILL_BLOCK}}注意两个细节{{SKILL_COUNT}}告诉模型一共有多少个候选暗示每个候选都可能被选到降低模型因候选过多而忽略后半部分列表的倾向{{SKILL_BLOCK}}在运行时被渲染为带编号的namedescription列表。从 runRouter.ts 的renderPrompt实现可见其真实渲染格式function renderPrompt( template: string, shuffledSkills: Array{ name: string; description: string }, userPrompt: string, ): string { const skillBlock shuffledSkills .map((skill, index) ${index 1}. ${skill.name}\n ${skill.description}) .join(\n\n); return template .replace({{SKILL_BLOCK}}, skillBlock) .replace({{USER_PROMPT}}, userPrompt) .replace({{SKILL_COUNT}}, String(shuffledSkills.length)); }描述本身来自 researcher/corpus/index.json 索引的 15 个skills/name/SKILL.md的 frontmatter。运行器通过loadSkillDescriptions()读取 corpus 索引、解析每个 SKILL.md 的description:字段extractDescription会处理 YAML frontmatter 的description: ...单行与description: -折叠块两种形式。这解释了为什么Stage 1 的 skill 健康检查要求 description 必须存在、必须是第三人称、长度不超过 1024 字符——它们是 Stage 2 路由测试的直接输入。2.3 任务输入第二个占位符{{USER_PROMPT}}# Task The user has the following task. Read it carefully and identify which skill (if any) most directly applies.{{USER_PROMPT}}模板刻意与真实场景保持一致它让模型在只看描述、不加载任何 skill 正文的前提下做决策。运行器中Agent.prompt(filled, { ..., local: { cwd: REPO_ROOT, settingSources: [] } })的settingSources: []正是为了达成这个目的——Agent 没有任何已加载的 skill提示词中的描述是唯一信号。{{USER_PROMPT}}的取值来自 ground-truth 夹具 researcher/benchmarks/router/prompts.jsonl。每一行都是一个带标注的任务{prompt_id:p001,prompt:Explain why context windows degrade as they fill, and how attention mechanics make middle-of-context information less recoverable.,expected_primary_skill:context-fundamentals,acceptable_secondary_skills:[context-degradation],rejected_skills:[bdi-mental-states],reason:Foundational explanation of context behavior is core to context-fundamentals.}夹具字段与评估逻辑一一对应字段含义在评估中的用法prompt_id任务唯一 ID结果文件命名与断点续跑prompt喂给路由器的用户任务填充{{USER_PROMPT}}expected_primary_skill人类标注的正确 skill计算 top-1 / top-3 正确性acceptable_secondary_skills可接受的次优 skill分析混淆时参考rejected_skills明确不该选的 skill分析失败时参考reason标注理由人工审查与迭代改描述的输入初始夹具为 50 条覆盖五种类型来自 README.md单 skill 正控制每个 skill 一条共 15 条对抗性边界对来自 v2.2.0 边界混淆清单5 对 × 3 变体共 15 条如 evaluation vs advanced-evaluation组合任务多个 skill 都合理10 条负控制任何 skill 都不该强匹配5 条如 p045 三角形面积计算、p046 代码格式重排、p047 英译法微妙激活描述不够直白但应能解析的任务5 条。2.4 输出约束严格 JSON# Output Return ONLY a single JSON object. No prose, no markdown, no code fence. The JSON object must have exactly these keys: - ranking: an array of skill names, ordered most-to-least relevant. Include only skills you genuinely consider relevant. At least one skill must appear. - confidence: a number between 0.0 and 1.0 describing your confidence in the top choice. - rationale: a single sentence explaining why the top choice is the best match. Example:{ranking:[skill-a,skill-b],confidence:0.82,rationale:The task is about X, which is the core scope of skill-a.}输出段是整个模板中约束最密集的部分逐条分析Return ONLY a single JSON object直接要求纯 JSONNo prose, no markdown, no code fence显式禁止 围栏和解释性文字must have exactly these keys锁定 schema避免模型自由发挥字段名ranking至少一个 skill防止模型输出空数组逃避决策confidence限定 0.0–1.0为后续校准分析留出空间如 p042 涉及置信度阈值路由到人工的场景rationale要求单句压缩推理开销同时为失败分析提供线索。模板完整原文为了便于对照实现模板全文researcher/benchmarks/router/routing-prompt.md即上文拆解的四段拼接角色限定、# Available skills ({{SKILL_COUNT}}){{SKILL_BLOCK}}、# Task{{USER_PROMPT}}、# Output严格 JSON 约束。全文仅这三个占位符{{SKILL_COUNT}}、{{SKILL_BLOCK}}、{{USER_PROMPT}}。三、源码级执行链路模板如何被跑起来模板不是给人看的静态文档而是被 TypeScript 运行器逐条执行的。完整链路位于 researcher/benchmarks/sdk-runner/src/runRouter.ts。3.1 主流程加载夹具 prompts.jsonl → 加载 15 个 skill 描述 → buildRunPlan 生成计划 → 成本预估 预算断言 → dry-run 则退出 → 逐条 (prompt, model, rep)shuffle 描述顺序 → renderPrompt 填充模板 → Agent.prompt(filled, { settingSources: [] }) → 解析 JSON → 打分 → 落盘 → 汇总写入 summary.json 追加 router-history.jsonl关键点确定性洗牌shuffleSeeded用 mulberry32 PRNG SHA-256 派生的种子hash32(${promptId}|${modelId}|${rep}|${baseSeed})保证同一--seed下洗牌结果可复现。这实现了 PLAN.md 中的position bias 缓解策略shuffle skill order across replications, report consistency。严格 JSON 解析与重试parseRouterJson先正则提取\{[\s\S]*\}再JSON.parse成功则取出ranking数组。若解析失败则记为format_failure并重试最多MAX_FORMAT_ATTEMPTS 2次——这与已发布报告中的 The runner now retries transient format failures once 一致。错误分类捕获到CursorAgentError记为model_unavailable模型不可用继续跑其余模型其他错误记error并保留notes。断点续跑运行器按resultFileName(promptId, modelId, rep)即promptId-modelId-rep.json扫描已有结果跳过已完成项--no-resume可强制全量重跑。已发布报告显示v1 运行器在 566/600 处崩溃后正是靠 resume 路径补完了全部 600 条记录。预算强制assertBudget在调用任何模型前断言plan.length maxRuns且预估成本 maxBudgetUsd否则直接抛错拒绝执行。resolveConfig甚至规定不提供--max-runs/--max-budget-usd/--unsafe-no-cost-cap且非 dry-run 时运行器拒绝执行。并发与串行化输出runConcurrently实现有界并发默认 1报告中使用--concurrency 4把 60 分钟压到约 15 分钟并用printLock串行化控制台输出避免并发 worker 的日志互相穿插。3.2 计分逻辑每个 (prompt, model, rep) 的计分runRouter.tsrecord.predicted_primary parsed[0]; record.predicted_top3 parsed.slice(0, 3); record.top1_correct parsed[0] prompt.expected_primary_skill; record.top3_correct parsed.slice(0, 3).includes(prompt.expected_primary_skill);top-1ranking[0]是否等于expected_primary_skilltop-3expected_primary_skill是否出现在前三个。summarize按模型聚合出total、format_failure_rate、top1_accuracy、top3_accuracy写入summary.json并追加到 researcher/reports/router-history.jsonl该文件 gitignored历史追踪用。3.3 报告渲染从原始结果到发布报告researcher/scripts/render_router_report.py 将 gitignored 的原始 JSON 渲染为提交到仓库的 Markdown 报告。它实现按模型的 top-1/top-3 准确率与bootstrap 95% 置信区间2000 次重采样bootstrap_ci取 2.5%/97.5% 分位按 skill 的混淆矩阵expected × predicted逐 prompt 失败分析、逐 (prompt, model) 复现一致性检查格式失败率与各模型耗时统计。原始结果每个 (prompt, model, rep) 的 JSON含 raw model output 与解析后的 ranking保存在researcher/benchmarks/router/results/date-seed/被 gitignore仅摘要进入results-published/。四、如何运行与复现4.1 前置条件从 SDK 运行器目录执行researcher/benchmarks/sdk-runner/README.mdcd researcher/benchmarks/sdk-runner npm install npm run router:dry-run # 查看计划与成本预估不调用模型 npm run router:run -- --max-budget-usd 5 # 执行需先 export CURSOR_API_KEY4.2 完整可复现命令已发布报告如 researcher/benchmarks/router/results-published/2026-05-19.md给出的复现命令cd researcher/benchmarks/sdk-runner npm install export CURSOR_API_KEYyour-key node --experimental-strip-types src/runRouter.ts --models claude-opus-4-7,composer-2,gemini-3.1-pro,gpt-5.5 --reps 3 --seed 1 --max-budget-usd 15 python3 ../../scripts/render_router_report.py \ --results ../router/results/date-seed \ --fixture ../router/prompts.jsonl \ --output ../router/results-published/date.md4.3 CLI 参数一览所有参数在 common.ts 的parseCliFlags/resolveConfig中解析默认值明确参数含义默认值--dry-run打印计划与成本预估不调用 SDK关--models a,b,c参与评估的模型列表composer-2--reps N每个 (prompt, model) 的重复次数3--seed N洗牌与计划生成的随机种子1--fixture pathground-truth 夹具路径router/prompts.jsonl--max-runs NAgent 调用次数硬上限无整数最大值--max-budget-usd N预估成本上限超限快速失败无整数最大值--concurrency N并发数1--no-resume忽略已有结果强制全量重跑关默认续跑--unsafe-no-cost-cap显式放弃成本上限不推荐关4.4 成本估算依据运行器的成本预估常数runRouter.tsESTIMATED_TOKENS_INPUT 4000 ESTIMATED_TOKENS_OUTPUT 400 ESTIMATED_USD_PER_RUN 0.012 MAX_FORMAT_ATTEMPTS 2最坏情况调用次数 计划数 × 2重试一次。路由提示词规模小约 3–5k 输入 token、约 500 输出 token在 Cursor 积分模式下每次全量扫描100 prompts × 4 models × 3 reps 1200 次调用远低于 $5即使按不利的零售价估算也在 $5–15 区间PLAN.md 的成本分析。五、结果解读模板 描述质量的量化反馈模板输出的 JSON 最终汇入 已发布报告。每份报告包含运行元数据时间戳、repo commit、fixture SHA、seed、模型列表、复现次数、执行摘要、按模型排行榜bootstrap 95% CI、按 skill 混淆矩阵、最难 prompt 分解、复现命令。以 2026-05-19 的扫描600/600 条可用记录、0 格式失败为例ModelTop-195% CITop-3Format Failuresgemini-3.1-pro0.920[0.873, 0.960]0.9330composer-20.913[0.867, 0.953]0.9470gpt-5.50.913[0.867, 0.953]0.9730claude-opus-4-70.840[0.780, 0.893]0.9330报告还给出了关键方法论细节帮助读者判断结果可信度每次 (prompt, model, rep) 的 skill 描述顺序都做确定性洗牌降低位置偏差settingSources: []保证 Agent 未加载任何 skill描述是唯一路由信号置信区间为 2000 次重采样的 bootstrap 95% CI每 (prompt, model) 至少 3 次重复以估计方差。5.1 从混淆矩阵反推描述问题混淆矩阵是描述迭代的直接输入。例如 2026-05-19 报告中context-fundamentalsn42有 19 次正确、5 次被路由到context-degradation、6 次到context-optimization、12 次到project-development——这是该 skill 是最弱 catch-all 边界的证据。p046负控制Python 格式化、p048genuinely ambiguous 的 advanced-evaluation 任务在全模型下 top-1 均为 0说明这类 prompt 本身就该重新标注而不是继续改描述。5.2 描述迭代闭环当基准暴露路由失败时标准动作是results-published/README.mdfollow up by editing the activation description of the failing skill, rerunning the benchmark, and comparing the new report against the previous one to show the delta.2026-05-15 基线 vs 修复后2026-05-15-v2的 delta 报告展示了这一闭环的量化效果context-fundamentalstop-1 从 0.255 → 0.48923.4pp最大单项提升project-development从 0.750 → 1.00025pp路由达到完美此前最难的 p001Explain why context windows degrade从 0.00 → 0.83。同时报告也诚实标注了伪回归advanced-evaluation表面从 0.980 跌到 0.797实为基线只完成了 49/60 次运行v1 运行器中途崩溃绝对正确数 48 vs 47 基本持平。这种披露纪律正是 PLAN.md 中 Disclose methodology fully 的体现。六、把这份模板复用到你自己的 skill 集合从routing-prompt.md可以提炼出一套可移植的路由提示词设计清单角色单一化开头一句话限定你只做路由候选清单显式化{{SKILL_COUNT}}声明候选数列表带编号与描述缩进方便模型逐条比较任务与候选隔离Task 段落与 Available skills 段落分开防止任务文本污染候选理解输出 schema 硬约束字段名逐一列出、给出单行示例、禁止 prose/markdown/code fence、ranking至少一项评估可解析要求confidence数值化便于后续做置信度校准对应夹具中 p042 的场景与运行器配合用settingSources: []隔离描述信号、用确定性洗牌消除位置偏差、用parseRouterJson宽容解析 有限重试处理格式失败、用--dry-run先看成本再执行。把这三件事——模板routing-prompt.md、夹具prompts.jsonl、运行器runRouter.ts common.ts——配套使用你就拥有了一套可复现、可追踪、可迭代的 skill 路由质量评估系统。仓库中 已发布的对比报告 证明了这套方法的落地效果它不只是给出一个准确率数字更提供了哪个 skill 描述写得好、哪个边界容易混淆、下一步改哪句描述的可执行结论。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考