Victory Skill 是一个实验性的 Skill 路由器：在第一次聊天模型请求之前，以确定性方式选出相关 Skill，并直接注入完整 SKILL.md 正文。
它替代了原生路径：聊天模型先阅读 Skill catalogue、判断需要哪个 Skill，再额外调用工具读取文件。
用户 query
-> 嵌入 query 和每个可见 Skill 的一条紧凑路由文本
-> 保留达到 embedding 阈值的候选
-> 可选的本地 cross-encoder rerank
-> 注入每个保留候选的完整 SKILL.md
-> 第一次聊天模型请求
每个 Skill 只有一条简短、由作者维护的路由文本。它包含名称、必填 description 和可选路由元数据。完整 Markdown 正文只在命中后使用：指令、代码块、示例和流程分支不是可靠的检索文本。
---
name: figma-implement-design
description: Translate supplied Figma designs into production-ready application code.
metadata:
routing:
use_cases:
- 把提供的 Figma 设计稿实现为现有项目中的响应式页面。
- 读取 Figma 变量和组件状态，完成像素级 UI 还原。
tags:
- Figma
- design file
- React
- responsive UI
---use_cases 是简短的用户任务陈述；tags 标识具体平台、工件、实体或输出类型。没有这些元数据的 Skill 仍会仅依赖 description 路由。
- 不生成 routing card：路由文本对作者可见、可版本管理。
- 不使用正文分段 max pooling：通用流程性文本会产生假阳性。
- 不设置自动 Top-K：复合请求可能确实需要多个 Skill。
- 只在匹配后注入完整
SKILL.md，不需要聊天模型发起 Skill-read 工具调用。 - rerank 接收紧凑路由文本，绝不接收完整 Skill 正文。
所有数据都是检索标签指标，不是端到端任务成功率的声明。精度等于预期标签占注入标签的比例；召回等于被路由保留的预期标签比例。使用的 embedding 模型为 text-embedding-v4。
80 个公开 Skill description 加 8 条复合 prompt 的语料，在 embedding 阈值 0.5 下得到初始 baseline：
| 召回率 | 精度 | 平均候选数 | 最大候选数 | 零命中 case 数 |
|---|---|---|---|---|
| 61.46% | 18.15% | 3.69 | 42 | 27 |
这表明通用 description 加较低全局阈值会导致 Skill 过度注入。
一组探索性语料使用 12 个已安装 Skill 和 6 条中文 prompt，在 0.5 下对比 description-only 与 Markdown 正文分段最高分：
| 路由输入 | 召回率 | 精度 |
|---|---|---|
| 仅 description | 83.33% | 55.56% |
| Markdown 正文分段 | 83.33% | 50.00% |
正文分段没有找回更多预期 Skill，反而增加了假阳性，因此不进入路由文本。
自有中文 fixture 包含 12 个 Skill 和 14 条单/复合 prompt。description 忽略路由元数据，metadata 则包含 use_cases 和 tags。
| Embedding 阈值 | 输入 | 召回率 | 精度 | 平均候选数 | 零命中 case 数 |
|---|---|---|---|---|---|
| 0.50 | description | 68.75% | 47.83% | 1.64 | 4 |
| 0.50 | metadata | 93.75% | 46.88% | 2.29 | 1 |
| 0.55 | description | 62.50% | 52.63% | 1.36 | 5 |
| 0.55 | metadata | 81.25% | 56.52% | 1.64 | 3 |
| 0.60 | description | 25.00% | 57.14% | 0.50 | 10 |
| 0.60 | metadata | 62.50% | 62.50% | 1.14 | 5 |
本地 BAAI/bge-reranker-v2-m3 端点将 query 与路由文本成对评分，对 embedding 候选进行 rerank。embedding 阈值为 0.45 时，它在当前 fixture 中保留了所有预期标签，同时令第一阶段候选池适合本地推理。
| Embedding 阈值 | Rerank cutoff | 召回率 | 精度 | 最终平均候选数 |
|---|---|---|---|---|
| 0.45 | 无 | 100.00% | 27.12% | 4.21 |
| 0.45 | 0.01 | 100.00% | 80.00% | 1.43 |
| 0.45 | 0.05 | 93.75% | 83.33% | 1.29 |
| 0.45 | 0.10 | 87.50% | 93.33% | 1.07 |
当前实验性起始配置是 embedding 0.45 -> rerank 0.01。它不是通用默认值，仍需在更大的真实 query 语料上验证。reranker 首次请求耗时 1.19s，在 Apple MPS 上热态处理 5 个候选约为 101ms。
新的 mainstream-200.json 将公开 catalogue 扩充到 200 个 Skill，并以固定上游 commit 记录来源。除了 description-close smoke case，它还包含 50 条人工标注 case：语义改写、近邻消歧、跨语言、格式扰动、组合请求和应拒识请求。
在 text-embedding-v4 的 description-only 扫描中，单阈值没有可接受的折中：0.45 得到 91.32% 召回但平均注入 29.89 个 Skill、精度 3.14%；0.60 将平均候选降至 5.02，却使组合 case 召回降为 18.75%。完整口径、数据源和阈值结果见 benchmarks/skill-routing。这证明 rerank 或作者维护 metadata 是扩大 catalogue 后的必要后续工作，而不是可选优化。
本地 BAAI/bge-reranker-v2-m3 已在其中 58 条鲁棒/复合 case 上复测：0.45 -> rerank 0.01 将精度从 6.39% 提升至 23.94%，平均候选从 15.10 降至 3.24，并达到 100% 拒识；代价是召回降为 69.23%、单实例 MPS rerank 耗时 170.20 秒。它证明二阶段筛选有效，但旧 12-Skill fixture 的 cutoff 不能直接作为生产配置，仍需按候选池预算重新校准。
mainstream-100.json 是 200-Skill catalogue 的固定分层子集。它保留全部 47 个复合/鲁棒 case 预期标签，再按来源补齐至 100 条，因此能在相同 58 条 case 上隔离 catalogue 规模影响，但不能视为新的独立泛化集。
同一模型、同一 0.45 -> rerank 0.01 配置下：
| Catalogue | 阶段 | 召回率 | 精度 | 平均候选数 | 拒识准确率 | 耗时 |
|---|---|---|---|---|---|---|
| 100 | embedding | 86.15% | 12.84% | 7.52 | 75.00% | 8.67s |
| 100 | rerank | 69.23% | 38.79% | 2.00 | 100.00% | 39.29s |
| 200 | embedding | 86.15% | 6.39% | 15.10 | 75.00% | 12.84s |
| 200 | rerank | 69.23% | 23.94% | 3.24 | 100.00% | 170.20s |
100 与 200 的 rerank 总召回和近邻召回（均为 58.33%）相同，说明 0.01 的主要问题不是 catalogue 规模，而是它对近邻与组合相关标签过度过滤。100 条只降低了候选池和本地 MPS 耗时，不能使该 cutoff 成为生产默认值。
同一 12-Skill fixture 上，聊天模型选择 baseline 得到 100% 精度和召回率，耗时 6.35s。这只衡量从明确 catalogue 中的显式选择，不是端到端对比，也没有消除原生路径后续的 Skill-read 调用。
数据集、runner、命令、输入模式和结果 schema 均位于 benchmarks/skill-routing。
仅通过环境变量提供 endpoint 和凭据，不要将凭据加入仓库文件或 fixture。
当前工作树的模式扫描只在 API key 解析测试 fixture 中发现了 Google Vertex 风格字符串；未在已跟踪文件中发现常见 OpenAI、GitHub、AWS、Slack 或 Hugging Face key 格式。GitHub Secret Scanning 当前未为该仓库启用，因此在依赖平台侧告警前应先启用它。
metadata 路由路径及其 benchmark suite 已实现。本地 reranker 已完成 benchmark，但尚未接入运行时路径。
MIT