Skill写了到底有没有用？CANNBot-Sentry Skill覆盖率与使用事件分析手把手教程
【免费下载链接】cannbot-sentryCANN 生态中面向 Agent 工作流的“哨兵”：观测 · 审计 · 评测三位一体的质量基础设施项目地址: https://gitcode.com/cann/cannbot-sentry
你是不是也写过不少 Agent Skill，却拿不准它们到底有没有被真正用上？CANNBot-Sentry 是 CANN 生态里面向 Agent 工作流的“哨兵”，通过 Skill 覆盖率面板和 Skill 使用事件追踪，帮你一眼看清：哪些 Skill 被调用了、哪些只是加载了、哪些从头到尾没被碰过。这篇手把手教程将带你从安装到看图，10 分钟搞定。
一、为什么 Skill “写了等于没用”？
Agent 会话开始时，框架会把所有可用 Skill 的清单注入上下文（比如The following skills are available这样的列表）。问题在于：
- 注入 ≠ 使用：Skill 出现在清单里，不代表 Agent 真的调用了它；
- 调用不可见：Skill 的加载、调用、子代理派发散落在漫长的对话流里，人工翻日志几乎不可能；
- Token 白烧：没被使用的 Skill 清单照样占用上下文，白白消耗 Token。
CANNBot-Sentry 的 Skill 覆盖率分析正是为了解决这三个问题：从捕获的会话数据中，自动区分「可用 Skill 全集」和「实际使用记录」，逐个对账。核心逻辑在 skill-coverage.ts 中实现，它能同时解析 Claude 风格的列表和 opencode 的<available_skills>XML 两种注入格式。
二、三步快速上手：安装、捕获、打开面板
1. 获取并启动平台
git clone https://gitcode.com/cann/cannbot-sentry cd cannbot-sentry/packages/insight ./start.sh # 首次自动装依赖并启动浏览器打开http://localhost:21025即可。也支持免克隆安装：npm install -g cannbot-insight。更多细节见 安装使用手册。
2. 用 cpx 代理捕获一次真实会话
在原命令前加cpx即可，例如：
cpx claude # 交互式会话 cpx claude -p "用一句话介绍自己" # 最快冒烟验证cpx 会捕获 agent 与模型之间的明文流量，agent 退出后自动压缩归档；若 insight 正在运行还会自动导入。
3. 进入会话详情，找到 Skill 相关面板
导入后在会话详情页可以看到 Skills 明细（SkillDetail.tsx），顶部就是 Skill 覆盖度卡片；展开某个对话轮次还能看到该轮的 Skill 使用事件。整体界面长这样：
三、看懂 Skill 覆盖率环图：五种状态一眼定位问题
覆盖度卡片（SkillCoverageCard.tsx）左侧是一个环状图，中心数字就是未使用数量，配合右侧彩色标签逐个点名：
| 状态 | 含义 | 该关注什么 |
|---|---|---|
| 🟢 已调用 | Skill 真正被 invoke/use 过 | 检查成功率与耗时 |
| 🔵 仅加载 | 只加载了没调用 | 可能是描述写得不够“诱人” |
| 🟣 子代理 | 以 Task/Agent 派发形式被使用 | 属正常路径，不算浪费 |
| ⚪ 未使用 | 注入了但整场会话没碰过 | 优先删减或合并的对象 |
| 🟠 全集外 | 清单外动态出现的 Skill/子代理 | 检查是否有未声明的 Skill 在跑 |
排序上，“未使用”永远置顶（见 buildCoverage），因为覆盖度看板的核心问题就是“哪些没用上”。鼠标悬停任意标签，还能看到调用/加载/派发次数与 Skill 描述。
四、追踪 Skill 使用事件：从加载到调用的完整生命周期
对某个具体 Skill 想深入时，展开对应轮次的 Skill 事件列表（SkillEventList.tsx），每个 Skill 会显示：
- 生命周期徽章：如
load → invoke，缺失任一阶段会单独标出，方便发现“加载了却没调用”的情况； - 成功/失败状态：
fail时会展开显示错误信息，快速定位 Skill 执行失败原因； - Token 开销：事件携带的参数与结果体积折算成 Token 数直接标在行尾，量化每个 Skill 的上下文成本。
事件分组逻辑在 skill-event-grouping.ts：它把 load、invoke/use、dispatch 三类事件与对应的工具调用记录对齐，拼成完整生命周期。
五、不止“有没有用”，还能审计“用得好不好”
覆盖率回答“用了没有”，而 Skill 审计子 tab（SkillAuditTab.tsx）回答“用得对不对”：它把本会话中可审计的 Skill 与子代理列为对账目标，跑一次审计即可生成发现项（findings），并支持从发现项直接跳转回对应的对话轮次，把问题定位到具体哪一步。审计报告的呈现组件在 skill-audit/ 目录下。
六、常见问题速答
Q1：没有看到覆盖度卡片？说明该会话没能解析出“可用 Skill 清单”（比如框架未注入清单）。此时面板会自动隐藏；若只有使用记录，会退化为按实际使用列出。
Q2：子代理派发算“使用”吗？算。纯 dispatch 型子代理（来自 agents/ 目录或动态生成）本就不在 Skill 清单里，会被正确归类为「子代理」而非「全集外」，避免误报。
Q3：数据会泄露吗？cpx 捕获前统一脱敏，API key 永不落盘，本地数据集中在~/.cannbot-insight/，可自主管理。
七、总结
- 用cpx 前缀捕获会话，是拿到 Skill 分析数据的最短路径；
- 覆盖度环图回答“哪些 Skill 没被用上”，「未使用」置顶直接给出删减清单；
- 使用事件列表回答“用的过程是否健康”：生命周期、成败、Token 开销一目了然；
- Skill 审计回答“用得对不对”，发现项可跳转到具体轮次。
从“写了个 Skill 石沉大海”到“每个 Skill 的去向都有据可查”，CANNBot-Sentry 让你对 Agent 工作流的质量真正有了哨兵。
【免费下载链接】cannbot-sentryCANN 生态中面向 Agent 工作流的“哨兵”：观测 · 审计 · 评测三位一体的质量基础设施项目地址: https://gitcode.com/cann/cannbot-sentry
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
