Dicklesworthstone/skillranker · 上手攻略

  • 仓库：Dicklesworthstone/skillranker
  • 链接：https://github.com/Dicklesworthstone/skillranker
  • 分类：AI 编码助手 / 技能路由
  • 作者：Jay
  • 更新：2026-09-21

这是什么

SkillRanker（命令 sr）是一个独立运行的 Rust CLI 工具，核心作用是在 AI 编码代理（Claude Code、Codex 等）的技能库中，根据当前会话的实时上下文，智能挑选最适合下一步的技能。它由 TypeSafe.ai 的 Jev 模型提供决策引擎，支持 Claude Code Hooks 集成、结构化 JSON 输出、主动弃权（abstention）机制和本地反馈闭环。⚠️ 使用需要自行申请 TypeSafe API Key（收费，按调用量计）。

解决什么问题

大技能库是双刃剑：技能多=覆盖广，但选错技能的代价也高——加载一个不适合当前步的技能会消耗上下文、浪费 token，甚至把任务方向带偏。SkillRanker 解决的是"在正确的时机选正确的技能"这个问题：

  • 会话感知：不只是匹配关键词，而是读取最近对话、最近失败、当前任务信号来评估候选技能是否真的适合当前这一步。
  • 双轨评估：Jev 先对全部候选做宽泛初筛，再对短列表做细粒度重排，两轮都包含"以上都不合适"的弃权选项。
  • 可审计：每次推荐附带推理路径、--why-not 可以追溯某个技能被排除的具体原因和阈值。
  • 本地优先：本地检索准备候选、离线 fixture 演示、离线回放评估，不开 --allow-network 就零网络请求。

快速安装

前置依赖

# Linux 或 macOS（macOS 状态需放在 APFS/HFS+ 本地文件系统，Unix 权限）
# Bash / Python 3 / curl / sha256sum 或 shasum
# 可选：Git + Rust（源码构建时）；RCH（远程编译 macOS source builds）

方式一：官方安装脚本（一键，推荐）

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/skillranker/main/install.sh?$(date +%s)" | bash -s -- --verify

安装脚本会自动选择对应平台的 Release 二进制文件、校验 SHA256 签名、写入 ~/.local/bin。若对应平台无预编译包，则从源码构建（需要 Rust 工具链）。--easy-mode 还会把安装目录加入当前 shell 的 PATH（自动备份）。

方式二：本地源码构建

git clone https://github.com/Dicklesworthstone/skillranker.git
cd skillranker
cargo install --locked --path . --bin sr

构建产物放在 ~/.cargo/bin/sr。

方式三：离线包安装

bash install.sh --offline skillranker.tar.gz --verify
# 需要同目录放置 .sha256 校验文件

Claude Code Hooks 集成

# 预览 Claude Code Hook 配置变更（不实际写入）
sr install-hook claude

# 确认无误后应用
sr install-hook claude --apply

⚠️ 安装脚本不配置凭证和网络授权，需要自行申请 TypeSafe API Key 并配置环境变量后方可进行真实排名。

核心配置

1. 申请 TypeSafe API Key

访问 TypeSafe Console 注册账号并创建 Key。Jev 是整个排名系统的大脑，每位用户自行提供凭证，SkillRanker 不分发共享 Key。

2. 设置环境变量

# 方式一：写入 .env 文件（推荐，checkout-local）
cp .env.example .env
chmod 600 .env
# 用文本编辑器填入 TYPESAFE_API_KEY=sk-xxxx

# 方式二：直接 export 到 shell
export TYPESAFE_API_KEY=sk-xxxx

⚠️ .env 已在 .gitignore 中，排除后记得将 Key 保管好，不要进入 shell 历史或日志文件。

3. 验证运行环境

sr capabilities --json   # 检查本构建实现的命令和集成
sr doctor --json          # 检查所有依赖项就绪状态（不发起网络请求）
sr doctor --config        # 展示所有配置项及其来源

核心用法

1. 离线演示（无需 Key / 网络）

# 三个预设 fixture：useful / none / explicit / unavailable
sr demo --case useful

演示运行完整的本地管道，使用绑定的合成上下文和标注响应，不访问私人会话、不调 Jev API。

2. 技能排名（核心命令）

# 预览（不发送网络请求）
sr rank --context scratch/context.json --dry-run

# 真实排名（需要 --allow-network）
sr rank --context scratch/context.json --allow-network

# 结构化 JSON 输出
sr rank --context scratch/context.json --allow-network --json

# 指定 transcript 格式 + harness 类型
sr rank --transcript scratch/session.jsonl --harness claude_code --allow-network

# 指定 cass 导出的会话目录
sr rank --session scratch/session.jsonl --allow-network

3. 诊断某个技能为何落选

sr rank --context scratch/context.json --allow-network \
  --why-not SKILL_ID --explain

追踪指定技能被排除的阈值和具体原因，不消耗额外 Jev 调用。

4. Claude Code Hook 集成

Claude Code Hook 允许在每次提示前自动触发排名推荐，无需手动喂 context：

# 安装 hooks（预览）
sr install-hook claude

# 应用（写入 Claude Code 配置）
sr install-hook claude --apply

# 影子模式（评估但不注入建议）
sr hook claude --shadow

# 卸载
sr uninstall-hook claude --apply

⚠️ 安装 hooks 后，Claude Code 每次发送提示前会触发 sr hook claude，SkillRanker 返回 JSON 格式的推荐，但不自动加载——最终决定权在用户/agent 自己。

5. 观察与校准

# 统计过去 7 天的技能使用情况
sr stats --since 7d --by-skill

# 查看技能描述质量与覆盖缺口（本地）
sr doctor --descriptions
sr gaps

# 查看可见/屏蔽/排除的技能记录
sr roster --json

# 对比当前 roster 与历史快照
sr roster --diff scratch/roster-snapshot.json

6. 离线回放与策略对比

# 捕获带标签的 bounded 重放 case
sr rank --context scratch/context.json --allow-network \
  --save-case scratch/case.json

# 离线回放（不发起网络请求）
sr replay scratch/case.json --explain

# 用本地策略对比历史 case
sr replay scratch/case.json --compare-policy scratch/candidate.toml

典型适用场景

  • Claude Code 大技能库治理：当你的 .claude/skills/ 目录有数十个技能时，sr rank 可以帮助决定当前步应该加载哪个，而不是全塞进上下文。
  • Coding Agent 技能路由自动化：集成进 Agent 启动脚本，每次用户消息进来前自动做一次技能预选，减少无效技能消耗的 context。
  • 技能描述质量审计：用 sr gaps 和 sr doctor --descriptions 发现哪些技能描述模糊、覆盖重叠、或完全没被命中过。
  • Skill 开发迭代：用 sr demo + sr eval 验证新技能是否真的比现有技能更匹配特定场景，不需要开真实会话。
  • 多 Harness 对比：同一技能列表在 Claude Code / Codex / omp/pi 等不同 harness 下的可见性不同，用 --roster --diff 可以直观看到差异。

坑与注意

⚠️ 需要 TypeSafe API Key：Jev 是收费模型（具体定价见 TypeSafe 官网），没有免费额度。本地调用 sr demo 不消耗 Jev 配额，但任何 --allow-network 调用都会计费。

⚠️ SkillRanker 不执行技能：它只推荐，不加载、不执行、不Override Agent 的主控指令。最终是否采纳建议由 Agent 或用户自行决定。

⚠️ macOS 文件系统要求：macOS 上状态文件需放在 APFS 或 HFS+ 本地文件系统（不受 NFS/网络文件系统支持）。

⚠️ 网络授权是显式 Flag：--allow-network 单独控制每次 CLI 运行的联网权限，环境中设置了 Key 不等于授权了网络请求，需要每次明确指定或改配置。

⚠️ Linux 支持较好：官方文档称"supported local platform is Linux"，macOS 部分功能可能受限，建议先跑 sr capabilities --json 确认。

⚠️ Cass 集成需要额外工具：会话存档依赖 coding_agent_session_search（cass）工具，需单独安装并理解其导出格式。

与同类对比

特性 SkillRanker Keyword Search 全量加载 OpenHands Skill Selector
决策依据 实时会话上下文 + Jev LLM 判断 名称/描述关键词 无（全部加载） 任务描述 embedding
可弃权 ✅（none 选项） ❌ ❌ 部分
可解释性 ✅（--why-not 追踪） ❌ ❌ 部分
离线演示 ✅ ✅ ✅ ✅
Claude Code Hook ✅ ❌ ❌ ❌
技能库上限 254 个（含 none 选项） 无 无 未标注
外部依赖 TypeSafe Jev（收费） 无 无 本地模型
审计日志 ✅（ledger + stats） ❌ ❌ 部分

一句话总结：SkillRanker 是目前专门为 Claude Code 生态设计的技能路由工具中最成熟的一个，Jev 引擎提供的语义判断远超关键词匹配，但需要承担 TypeSafe API 调用成本——适合技能库规模大、对上下文效率敏感的进阶用户。

Sources：GitHub README（https://github.com/Dicklesworthstone/skillranker）· web_search 补充 TypeSafe Jev 定价信息（2026-09 暂无公开定价页面，需注册后查看）；Jev 模型版本号 / 确切训练数据截止日期 / SkillRanker 自身版本号未在 README 标注，以「⚠️」标注；Rust toolchain 版本未找到，以「⚠️ 未标注」标注。