SkillTriage

[中文 · English]

SkillTriage

调用前选对，安装前查重，使用中留痕。

当你装了很多 Agent Skills，却不知道当前任务或开发决策该找谁辅助，SkillTriage 会扫描已有能力、阅读入围 Skill 的完整说明，并给出带证据的选择报告。它适用于架构权衡、接口设计、调试、代码审查、产品取舍、写作等场景；安装新 Skill 之前，还能识别同名、同内容、改名复制和能力重叠。

报告示例 · 快速开始 · 调用统计 · 核心能力 · 系统结构 · 三种模式 · 安装前查重 · 安全边界 · 常见问题

你会得到什么

1. Skill 选择报告

下面是基于测试夹具整理的精简示例。真实报告还会包含候选路径、环境检查和未验证项。

任务：写一篇微信公众号文章并完成排版

主推荐：wechat-writer
置信度：高
调用计划：wechat-writer

为什么选它：
- 同时覆盖公众号正文写作和排版交付物
- 当前环境可读取完整 SKILL.md

为什么不选 pdf-editor：
- 只处理 PDF 页面和表单，交付物不匹配

下一步：显式调用 $wechat-writer 并附上文章主题

正式的推荐报告还会把证据分层：召回线索、完整正文、环境硬门、使用历史和未验证项分别展示。排名第一不等于最终推荐；如果没有候选明显优于基础 Agent，报告会明确写“无需额外 Skill”。报告结束后会停在下一步授权之前，不自动调用、安装或修改候选。

如果本地有调用日志，报告还会给每个入围候选补充使用证据：推荐过几次、实际加载过几次和最近调用时间。成功、失败、被替换等结果只有在存在显式记录时才展示；自动加载记录不会被猜成成功或失败。没有日志或当前时间窗口没有事件时会明确写“暂无记录”，不会把未知历史伪装成 0 次。

它也可以得出“无需额外 Skill”。简单任务不应为了使用 Skill 而强行匹配。

2. 安装前检查报告

候选：writer
本地相似项：writer
重复类型：同名、正文不同

已有能力：根据 Git 提交生成发布说明
候选增量：撰写产品发布营销文章

裁决：REVIEW_COLLISION
原因：名称相同但任务与交付物不同，安装后可能发生路由冲突
动作：停在安装之前，由用户决定改名或限定安装作用域

SkillTriage 会把“文件完全重复”“能力高度重叠”和“只是触发词相似”分开处理，而不是用一个相似度分数代替判断。

3. 调用历史与使用统计

SkillTriage 会自动汇总“哪些 Skill 被加载过”，也可以记录“推荐过什么”和“显式结果”。这几个数字必须分开：推荐报告不代表用户真的执行了该 Skill，自动加载记录也不猜测成功或失败。

Skill 使用统计（显式结果示例）

yueshi-ai-wechat-article
- 推荐次数：18
- 实际调用：15
- 成功完成：13
- 被替换：2
- 最近调用：2026-08-06

常见组合：
- yueshi-ai-wechat-article + stick-figure-illustrations：6 次

安装 SkillTriage 后，用户正常调用其他 Skill 即可。运行 history、stats 或 rank 时，它会从本机 Codex 会话日志识别已经加载的 Skill，并自动追加到本地 JSONL 日志；用户不需要每次手动 record。这不是后台常驻监听，只在查询或推荐时同步，而且只提取 Skill 名称、路径、时间和调用组标识，不保存完整提示词或 Skill 正文。自动日志只有“已加载”证据；如果没有显式结果事件，HTML 报告会隐藏成功、失败、被替换和耗时列。

日志默认保存到 ~/.codex/skill-triage/calls.jsonl，也可以用 SKILL_TRIAGE_LOG 或 --log-file 指定位置。日志只保存 Skill 名称、时间、事件类型、任务类别、可选调用结果、可选耗时和组合关系，不保存完整提示词、Token、Cookie 或文件内容。

它解决什么问题

Skill 数量少时，凭记忆选择通常够用。数量变多后，问题会从“有没有这个能力”变成：

多个 Skill 都看起来能做，究竟哪个更适合当前交付物？
一个任务需要单个 Skill，还是需要有顺序的最小组合？
新 Skill 名字不同，但能力是不是已经装过？
同一个 Skill 出现在项目级、全局目录和插件缓存时，哪个副本值得关注？
搜索结果分数很高，是否只是关键词碰巧相同？

SkillTriage 位于“发现”和“执行”之间：先建立本机清单，再查找候选、阅读全文、检查环境，最后给出选择或安装裁决。

适合谁

已经安装很多 Skills，无法稳定记住每项能力的人；
在同一个项目里同时使用 Codex、Claude Code、Cursor 等工具的人；
准备安装新 Skill，希望先确认本机是否已经有相同能力的人；
维护团队 Skill 库，需要定期发现同名冲突、重复副本和损坏引用的人；
希望 Agent 说明“为什么选它、为什么不选另一个”，而不只是返回名称的人。

它不是 Skill 市场，也不是安装器。它解决的是安装前、决策时和调用前的判断问题；你还可以要求它只解释候选 Skill 的思考框架和判断依据，把一次调用变成一次学习。

快速开始

从 GitHub 仓库直接安装到用户级 Skill 目录：

npx skills add ZekerTop/skill-triage --skill skill-triage -g

安装后直接调用 $skill-triage，不需要先记住 Skill 名；准备安装其他仓库时，再先让它检查重复和能力覆盖。

第一条指令

安装后，对 Agent 说：

$skill-triage 我要写一篇微信公众号文章并生成正文配图，当前应该调用哪个 Skill？只给我选择报告，先不要执行。

开发决策也可以直接问：

$skill-triage 我正在开发一个功能，需要在两个技术方案之间做选择。请找出适合辅助架构权衡和代码审查的 Skill，先解释调用顺序和判断依据，不要直接改代码。

合格的表现是：先扫描已有 Skills，阅读全文后给出主 Skill、必要的配合 Skill、调用顺序、未选原因和环境检查，而不是只返回一个名字或直接开始执行任务。

核心能力

你的问题	SkillTriage 会检查什么	你会得到什么
“这个任务用哪个 Skill？”	任务目标、交付物、候选完整说明、当前环境	一个主推荐、未选原因和显式调用方式
“开发中不知道该如何决策？”	决策目标、候选方案、约束、风险和候选 Skill 的思考框架	决策辅助 Skill、比较维度、学习建议和需要自己拍板的事项
“是不是需要多个 Skill？”	每个必要阶段是否已被主 Skill 覆盖	最小组合及 `A → B` 或 `A + B` 的调用顺序
“这个新 Skill 已经装过了吗？”	路径、名称、正文、文件树和完整能力说明	重复类型、已有覆盖、候选新增能力和安装建议
“本机 Skills 有什么问题？”	同名冲突、正文重复、相似能力、metadata 和本地引用	按优先级排列的体检报告
“现在能直接用吗？”	输入、文件、工具、系统、权限和作用域要求	可用、不可用或尚未验证的环境结论
“一定要调用 Skill 吗？”	基础 Agent 是否已经足够完成任务	必要时明确回答“无需额外 Skill”
“这个 Skill 调用了多少次？”	本地调用日志中的推荐、实际调用和结果事件	按 Skill、时间范围和组合查看使用统计

系统结构

SkillTriage 把“收集事实”和“理解能力”分开。Python 扫描器负责可重复检查；Agent 负责阅读完整说明并作出最终判断。

flowchart TB
    subgraph INPUTS["用户输入"]
        TASK["当前任务：该用哪个 Skill？"]
        CANDIDATE["待安装候选：是否重复？"]
        AUDIT["本机清单：是否有冲突？"]
    end

    COORDINATOR["SkillTriage 协调层<br/>选择一个模式 · 保持只读 · 组织报告"]

    subgraph SCANNER["证据收集：Python 标准库扫描器"]
        DISCOVER["查找项目级和全局 Skill 目录"]
        PARSE["读取名称、说明、路径和文件"]
        CHECK["计算哈希 · 检查引用 · 查找候选"]
    end

    subgraph REVIEW["完整说明复核：Agent"]
        READ["阅读入围候选的完整 SKILL.md"]
        GATES["检查交付物、环境、依赖和权限"]
        RULES["应用选择、查重、报告和安全规则"]
    end

    REFERENCES["references/<br/>选择规则 · 查重规则 · 报告模板 · 安全边界"]

    subgraph OUTPUTS["输出"]
        SELECTION["Skill 选择报告"]
        PREFLIGHT["安装前检查报告"]
        HEALTH["本地 Skill 体检报告"]
        HISTORY["HTML 调用历史 / 统计"]
    end

    SESSION_LOG["Codex 本地会话日志<br/>Skill 已加载消息"]
    SYNC["自动同步：只提取名称、路径、时间和调用组"]

    STOP["停在未获授权的安装、替换或删除动作之前"]

    TASK --> COORDINATOR
    CANDIDATE --> COORDINATOR
    AUDIT --> COORDINATOR
    COORDINATOR --> DISCOVER
    DISCOVER --> PARSE --> CHECK --> READ --> GATES --> RULES
    REFERENCES --> RULES
    RULES --> SELECTION
    RULES --> PREFLIGHT
    RULES --> HEALTH
    SESSION_LOG --> SYNC --> HISTORY
    COORDINATOR -. history / stats / rank .-> SYNC
    SELECTION --> STOP
    PREFLIGHT --> STOP
    HEALTH --> STOP

调用统计走一条自动同步旁路：history、stats 和 rank 先从 Codex 本地会话日志识别 Skill 激活，再读取 JSONL 事件并按 Skill、来源、结果和组合聚合。自动事件证明 Skill 已被加载，但结果为“未标记”；只有显式 record 才会补充成功、失败、被替换或推荐事件。调用次数只代表当前本地会话日志能观察到的事件，不是所有 Agent runtime 的全局审计总数。

组件职责

组件	负责什么	不负责什么
`SKILL.md`	识别用户意图、选择模式、要求阅读全文、组织最终结论	不用关键词分数直接宣布最终答案
`scripts/skill-triage.py`	扫描目录、读取 metadata、计算哈希、检查引用、生成候选清单、同步 Codex Skill 激活记录	不判断两个不同写法的 Skill 是否真的能力相同，也不猜测自动事件是否成功
`references/selection-rubric.md`	规定选择顺序、必要条件、最小组合和置信度	不收集本机文件证据
`references/duplicate-rules.md`	区分同路径、同正文、同名冲突、能力重叠和部分增量	不因“看起来相似”自动删除文件
`references/report-templates.md`	固定三类报告必须回答的问题	不替代候选全文阅读
`references/runtime-paths.md`	记录常见扫描目录和保守的作用域顺序	不保证某个 runtime 一定采用这个生效顺序
`references/failure-modes.md`	固定扫描失败、候选不完整、日志缺失和无候选时的状态与降级动作	不把失败检查转换成“可以安装”
`references/safety-boundaries.md`	规定只读范围、候选隔离和再次确认条件	不把检查通过描述成安全认证

三种模式

模式	什么时候使用	主要交付物
`recommend`	当前任务不知道该调用哪个 Skill	主推荐、备选排除理由、最小调用计划、显式调用方式
`preflight`	安装新 Skill 之前检查重复或冲突	重复类型、能力覆盖与增量、作用域影响、安装裁决
`doctor`	体检本机已经安装的 Skills	同名冲突、正文重复、能力重叠线索、损坏引用和 metadata 问题

SkillTriage 会先选择一个主模式。如果用户意图会改变模式，它只问一个关键问题。

决策流程图

flowchart LR
    INTENT["用户请求"] --> MODE{"这次要解决什么问题？"}

    MODE -->|"当前任务用哪个"| REC["recommend"]
    REC --> REC_SCAN["扫描并查找候选"]
    REC_SCAN --> REC_READ["阅读 3–5 个候选的完整说明"]
    REC_READ --> REC_GATE{"输入、交付物、环境和权限明确吗？"}
    REC_GATE -->|"不明确且会改变选择"| QUESTION["只问一个关键问题"]
    REC_GATE -->|"明确"| REC_OUT["一个主 Skill / 最小组合 / 无需额外 Skill"]

    MODE -->|"安装前查重"| PRE["preflight"]
    PRE --> STAGE["隔离候选并记录来源"]
    STAGE --> EXACT["检查同路径、同正文、同文件树和同名冲突"]
    EXACT --> CAPABILITY["比较任务、输入、输出、流程和边界"]
    CAPABILITY --> VERDICT["给出允许的安装裁决"]
    VERDICT --> INSTALL_STOP["停在安装之前"]

    MODE -->|"体检本机库存"| DOC["doctor"]
    DOC --> INVENTORY["建立本机清单"]
    INVENTORY --> ISSUES["发现冲突、重复、相似项和损坏引用"]
    ISSUES --> DOC_OUT["给出复核优先级，不自动清理"]

    INSTALL_STOP --> CONFIRM["全局安装、替换或删除需要再次确认"]
    DOC_OUT --> CONFIRM

三种模式的完整过程

`recommend`：为当前任务选 Skill

输入

用户的实际目标和最终交付物；
已知文件、运行环境、工具和权限限制；
用户明确点名、要求比较或禁止使用的 Skill。

处理步骤

去掉“帮我选 Skill”“只给报告”等选择指令，保留真正的任务内容。
扫描现有 Skill 目录，找出可能相关的候选。
阅读排名靠前的 3–5 个候选的完整 SKILL.md。
排除缺少必要输入、环境不兼容、交付物不符或需要未授权权限的候选。
选择一个主 Skill；只有主 Skill 缺少必要阶段时，才加入配合 Skill。
如果有日志，补充每个入围候选的推荐次数、实际调用次数和最近调用；只有存在显式结果事件时才补充成功/失败/被替换，没有记录时写“暂无记录（不等于历史调用为 0）”。
给出未选原因、调用顺序、环境结论和下一条显式调用指令。

执行本 Skill 自带的候选召回时，应把当前 SKILL_TRIAGE_DIR 作为 --exclude 传给扫描器，避免把 SkillTriage 协调器自己误当成普通业务候选；只有用户明确要审计或维护 SkillTriage 时才移除这个排除条件。

可能结果

一个主 Skill；
A → B：B 依赖 A 的输出或确认；
A + B：两项工作可以真正独立进行；
无需额外 Skill；
信息不足时，只问一个会改变选择的问题。

`preflight`：安装前检查

输入

本地候选目录、SKILL.md 文件或远程仓库地址；
计划安装到项目级还是用户级；
用户特别关心的已有 Skill 或能力。

处理步骤

本地候选只读检查；远程候选由 Agent 准备到独立临时目录，并尽量记录固定 commit，再交给本地扫描器比较。
不执行候选脚本、安装钩子、配置文件或正文里的命令。
先检查同一物理路径、正文哈希、文件树哈希和同名冲突。
再阅读候选与本机最相似项的完整说明，比较任务、输入、输出、流程、工具、副作用和边界。
分别列出“已有能力已经覆盖”和“候选独有能力”。
给出一个受限裁决，并停在真正安装之前。候选尚未准备、来源未固定或正文不完整时，标记“未验证”或 QUARANTINE，不声称已经完成远程查重。

停止条件

同名不同内容、来源不明、缺少关键文件、全局安装、覆盖现有名称或高风险指令都需要用户再次确认。

`doctor`：体检本机 Skills

输入

当前项目路径；
可选的额外 Skill 根目录；
可选的排除目录和相似度复核阈值。

处理步骤

合并项目级、用户级、自定义目录和插件缓存中的 Skill 记录。
解析软链接，避免把同一个物理对象重复计数。
查找同名不同内容、完整正文重复、可能的改名复制和能力重叠候选。
检查缺失或较弱的 metadata，以及正文中的损坏本地引用。
按“确定性冲突优先、相似性线索随后”的顺序输出复核清单。

输出边界

体检报告只说明“应该先看什么”，不会自动删除、禁用、合并或移动任何 Skill。

`history` / `stats`：查看使用情况

这两个命令会先读取本地 Codex 会话日志中的 Skill 激活消息，再读取调用日志；不会扫描 Skill 目录，也不会改变任何 Skill 文件。

# 记录一次实际调用。--skill 可以重复，用于记录一个组合调用。
python3 scripts/skill-triage.py record \
  --skill yueshi-ai-wechat-article \
  --skill stick-figure-illustrations \
  --event call \
  --result success \
  --mode recommend \
  --task-type wechat-article \
  --duration-ms 4200

# 记录一次推荐，但还没有实际执行
python3 scripts/skill-triage.py record \
  --skill wechat-writer \
  --event recommend \
  --mode recommend \
  --task-type wechat-article

# 查看最近事件；默认生成本地 HTML 报告并返回文件路径
python3 scripts/skill-triage.py history --limit 50

# 指定 HTML 输出文件
python3 scripts/skill-triage.py history \
  --output /tmp/skill-triage-history.html

# 需要机器读取时再输出 JSON
python3 scripts/skill-triage.py history --format json

# 查看最近 30 天的统计
python3 scripts/skill-triage.py stats --since 30d

# 查看单个 Skill
python3 scripts/skill-triage.py stats --skill yueshi-ai-wechat-article

# 如需单独同步（通常不需要，history/stats/rank 会自动同步）
python3 scripts/skill-triage.py sync

# 本次查询不读取 Codex 会话日志
python3 scripts/skill-triage.py history --no-auto-sync

stats 会输出推荐次数、实际调用次数、自动激活次数、最近调用时间和常见组合；如果日志中有显式结果事件，还会补充成功、失败和被替换次数。组合调用会为每个 Skill 计算一次单项调用，同时用共享的 call_id 计算组合调用次数，避免把一次组合误报成多次组合。

在当前任务的 recommend 流程里，rank 会把同一份历史证据附在每个候选的 usage 字段中。默认读取 ~/.codex/skill-triage/calls.jsonl；可以用 --log-file 指定日志，或用 --since 30d 只看最近 30 天：

python3 scripts/skill-triage.py rank \
  --task "选择适合当前架构决策的 Skill" \
  --project "$PWD" \
  --log-file ~/.codex/skill-triage/calls.jsonl \
  --since 30d \
  --format json

调用次数只是“这个 Skill 过去是否被使用、结果是否稳定”的背景信息。它不能替代完整 SKILL.md 阅读，也不能因为某个 Skill 调用最多就直接推荐它。

不带 --format 的 history 会生成一个离线 HTML 报告：表格按调用次数显示颜色深浅，支持按 Skill、任务和事件筛选，并可按调用次数、推荐次数或 Skill 名称从高到低、从低到高排序。只有存在显式结果或耗时事件时，报告才显示结果筛选器、成功/失败/被替换列和对应排序项。默认文件为日志目录下的 history.html，也可以用 --output 指定路径。

下面是一个包含显式结果记录的历史报告示例；只有自动激活记录时，结果列会被隐藏：

报告会把推荐次数、实际调用和自动激活分开统计，并用颜色帮助快速找到使用频率高的 Skill；如果有显式结果记录，再显示成功、失败、被替换和耗时。

如果本地日志不存在，命令会先尝试从 Codex 会话日志导入已加载的 Skill；仍没有可观察事件时才返回“暂无记录”。自动导入的结果显示为“未标记”，不会伪造成功或失败。

它如何做决定

一次可靠选择分为两层：

先找到值得阅读的候选：扫描器根据名称、description 和正文词语建立候选清单，并记录路径、作用域和匹配线索。这一步只是缩小阅读范围。
再判断哪个真正适合：Agent 阅读完整说明，核对任务、交付物、输入、环境、依赖、权限和能力边界，最后决定选择、组合或弃权。

关键原则：

本地优先：先检查已经安装的能力，不默认去市场找新的。
正文定案：名称和 description 只负责召回，最终结论必须依据完整 SKILL.md。
交付物优先：关键词相同但输出不匹配的候选会被排除。
最小组合：一个 Skill 能完成，就不堆叠多个 Skill。
允许弃权：基础 Agent 已经足够时，明确回答“无需额外 Skill”。
分数不冒充结论：脚本分数只是召回线索，不是最终适配度或安全证明。

安装前如何查重

SkillTriage 不把所有相似项都叫作“重复”。它会区分：

类型	典型证据	默认处理
同一物理路径	路径解析结果一致	清单去重
完整正文重复	标准化正文哈希一致	`SKIP_DUPLICATE`
同名、内容不同	名称一致但正文哈希不同	`REVIEW_COLLISION`
改名复制	名称不同但正文高度一致	阅读全文后优先复用已有 Skill
能力重复	任务、输入、输出和流程相同	无有效增量时 `USE_EXISTING`
触发冲突	触发条件相近，交付物或方法不同	明确边界或限定作用域
部分重叠	有公共能力，也有明确独有能力	`INSTALL_SCOPED` 或 `COMPOSE`

脚本负责路径、名称、哈希、文件树和引用检查；Agent 负责理解完整能力说明、工作流程和使用边界。

安装裁决

安装前报告只使用下列裁决，避免用模糊的“应该没问题”代替行动建议：

裁决	含义	用户下一步
`INSTALL`	没有确认重复，且候选提供有用能力	确认安装作用域后再安装
`SKIP_DUPLICATE`	已确认同路径、同正文、同文件树或无增量的完整复制	不安装，继续使用已有 Skill
`UPDATE`	已验证为同一来源的更新版本	查看版本变化，确认后更新
`REVIEW_COLLISION`	同名不同内容，或关键冲突尚未解决	先比较、改名或明确哪个副本应生效
`USE_EXISTING`	已有 Skill 已经覆盖当前需要	直接使用报告中指出的现有 Skill
`INSTALL_SCOPED`	候选有价值，但全局安装可能干扰其他任务	只安装到需要它的项目
`COMPOSE`	候选与已有 Skill 各自负责不同阶段	按报告给出的顺序组合使用
`QUARANTINE`	来源、完整性或风险无法确认	保持隔离，补齐证据后再判断
`REJECT`	已确认恶意、严重损坏或与明确要求不兼容	不安装

INSTALL 是报告结论，不是安装动作。SkillTriage 仍会停下来等待用户授权。

证据与报告怎么读

证据强度

证据	能说明什么	不能说明什么
真实路径和作用域	Skill 位于哪里，是否是同一物理对象	哪个 runtime 一定会优先启用它
正文哈希	标准化后的指令正文是否完全相同	内容是否安全、质量是否更高
文件树哈希	整个 Skill 目录是否逐文件相同	两个不同实现是否拥有相同能力
名称和 description	哪些候选值得优先阅读全文	最终任务是否匹配
完整 `SKILL.md` 比较	任务、输入、输出、流程、依赖和边界是否重叠	无法读取的外部系统当前一定可用
环境检查	所需文件、工具或权限当前是否可确认	没检查到的条件是否安全

一份完整报告应该回答什么

任务理解：这次真正要完成什么，最终交付物是什么；
推荐或裁决：选择谁、是否组合、是否需要安装；
证据：读取了哪些候选、哪些路径和说明支持结论；
未选原因：最相似的其他候选为什么落选；
能力边界：推荐项不负责什么，哪些阶段仍需别的能力；
环境状态：可用、不可用，还是尚未验证；
风险：同名覆盖、权限、外部依赖和无法确认的部分；
下一步：准确的调用方式，或等待用户确认的动作。

置信度“高 / 中 / 低”表示当前证据是否足够，不代表一个虚构的精确成功率。

扫描范围与作用域

默认只扫描实际存在的目录。目录不存在是正常情况，不会被当作错误。

Runtime	项目级目录	用户级目录
Codex	`<project>/.codex/skills`	`$CODEX_HOME/skills`，未设置时使用 `~/.codex/skills`
Shared Agent Skills	`<project>/.agents/skills`	`~/.agents/skills`
Claude Code	`<project>/.claude/skills`	`~/.claude/skills`
Cursor	`<project>/.cursor/skills`	`~/.cursor/skills`
Gemini CLI	`<project>/.gemini/skills`	`~/.gemini/skills`
OpenCode	`<project>/.opencode/skills`	`~/.opencode/skills`
GitHub Copilot	`<project>/.github/skills`	`~/.github/skills`
通用目录	`<project>/skills`	通过 `--root` 显式增加
Codex 插件缓存	不适用	`$CODEX_HOME/plugins/cache`

扫描器使用“项目级 → 自定义目录 → 用户级 → 插件缓存”的保守顺序帮助比较。这个顺序只是复核提示；在声称哪个副本真正生效前，仍需检查当前 runtime 的实际清单或文档。

它和相邻工具有什么不同

工具类型	主要回答	SkillTriage 的关系
Skill 目录或搜索器	“外面有哪些 Skill？”	在需要新增能力时提供候选来源
Skill 安装器	“怎样把它装进指定 Agent？”	接收安装裁决；SkillTriage 自己默认不安装
Skill 清单工具	“本机有哪些 Skill？”	清单是输入，SkillTriage 继续判断任务适配和重复关系
手动选择	“这个名字看起来像不像？”	用完整正文、环境硬门和排除理由降低误选
SkillTriage	“这次该用哪个？这个还需要装吗？”	连接发现、安装和实际调用的只读决策层

安全边界

默认只读，不自动安装、升级、卸载、删除、移动、覆盖或合并 Skill。
只运行当前已激活 SkillTriage 自带的只读扫描器。
远程候选先进入独立临时目录；不执行候选脚本、安装钩子或正文中的命令。
相似度只是复核线索，不能作为删除依据，也不能证明候选安全。
不输出 Token、Cookie、API Key、凭据值或无关用户文件。
全局安装、替换现有名称和任何破坏性清理都需要新的明确确认。

完整规则见 references/safety-boundaries.md。

失败、降级和“未验证”

SkillTriage 不会把缺少证据自动解释成“没有问题”。

情况	处理方式
某个扫描目录无法读取	报告具体目录和错误，继续处理其他可读目录，并标注清单不完整
无法确认当前激活的 SkillTriage 路径	不执行任何同名扫描器，只使用当前会话提供的 Skill 清单做降级分析
候选缺少 `SKILL.md` 或 frontmatter	标为不完整；不默认给出 `INSTALL`
远程候选无法固定到明确 commit	标记来源版本未验证，必要时使用 `QUARANTINE`
候选引用的脚本、文件或工具不存在	记录缺失项，并在环境检查中判定不可用或未验证
用户任务过于模糊	只问一个会改变推荐结果的问题
没有候选明显优于基础 Agent	回答“无需额外 Skill”，而不是推荐最接近的弱匹配
脚本扫描失败	说明失败范围；不把失败转换成“没有重复”或“可以安装”

“未验证”表示当前证据不足。它既不等于安全，也不等于危险。

内置扫描器

扫描器只依赖 Python 3 标准库：

python3 scripts/skill-triage.py --help
python3 scripts/skill-triage.py scan --project "$PWD" --format json
python3 scripts/skill-triage.py rank --task "编辑 PDF 表单" --project "$PWD" --top-k 8 --format json
python3 scripts/skill-triage.py compare --candidate ./candidate-skill --project "$PWD" --format json
python3 scripts/skill-triage.py doctor --project "$PWD" --format json
python3 scripts/skill-triage.py history --limit 50 --format markdown
python3 scripts/skill-triage.py stats --since 30d --format markdown

它默认识别 Codex、Shared Agent Skills、Claude Code、Cursor、Gemini CLI、OpenCode、GitHub Copilot 和通用项目 Skill 目录。路径优先级只是检查提示；实际由哪个副本生效，需要结合当前 runtime 验证。

项目结构

skill-triage/
├── SKILL.md                         # Agent 工作流和决策规则
├── agents/openai.yaml               # Codex 展示信息与默认提示
├── scripts/skill-triage.py          # 清单、召回、比较、体检和调用统计工具
├── references/
│   ├── duplicate-rules.md           # 重复与能力重叠裁决
│   ├── report-templates.md          # 三类报告模板
│   ├── runtime-paths.md             # 扫描路径和保守优先级
│   ├── safety-boundaries.md         # 权限与确认边界
│   ├── failure-modes.md              # 失败状态与安全降级动作
│   └── selection-rubric.md          # 最终选型与组合准则
├── tests/
│   ├── test_skill_triage.py         # 确定性单元测试
│   └── test-prompts.json            # 前向测试提示集
├── README.md
└── README.en.md

调用日志不放进仓库。默认位置是用户目录下的 ~/.codex/skill-triage/calls.jsonl，适合按机器单独保存；如果团队需要共享统计，应先脱敏，再通过 --log-file 指向经过审查的文件。

验证与测试

python3 -m unittest discover -s tests -v
python3 scripts/skill-triage.py --help
npx skills add . --list

结构校验：

python3 /path/to/skill-creator/scripts/quick_validate.py .

验收提示：

$skill-triage 帮我解释 2+2，看看该调用哪个 Skill。

合格结果应允许回答“无需额外 Skill”，而不是为了匹配库存强行推荐。

常见问题

为什么它会回答“无需额外 Skill”？

因为 Skill 的作用是补充专门流程，不是每个任务都需要一个。基础 Agent 已经能可靠完成的简单问题，强行加入 Skill 只会增加上下文和冲突。

为什么候选分数最高，却没有被推荐？

分数只用于查找值得阅读的候选。最终选择还要检查交付物、完整工作流、环境、依赖、权限和边界。关键词相同但输出错误的 Skill 会被排除。

推荐报告里的调用次数会影响排序吗？

不会。调用次数只作为历史使用证据展示，帮助你判断团队是否熟悉它、过去是否经常失败或被替换；当前任务是否适合，仍由目标、交付物、环境和完整说明决定。这样可以避免“用得多”被误读成“最适合”。

为什么安装前报告停住了，没有替我安装？

因为选择和安装是两个不同动作。报告可以建议安装，但全局安装、替换同名 Skill 或执行候选代码会改变环境，需要用户明确授权。

为什么清单里会出现多个同名 Skill？

同一 Skill 可能同时存在于项目级、用户级、共享目录或插件缓存。它们可能是同一路径的别名、完全复制，也可能是同名不同内容。SkillTriage 会先分类，再提示需要检查哪个副本。

能看到某个 Skill 调用了多少次吗？

可以。安装后正常调用 Skill，之后执行 $skill-triage history 即会自动从 Codex 会话日志导入“已加载”次数；record --event recommend 仍用于记录推荐，record --event call --result success/failure/replaced 只用于补充显式结果。没有可读取的会话日志时，报告会明确写“暂无记录”，不会把未知历史写成 0。

当你用 $skill-triage 查询“当前场景该调用哪个 Skill”时，推荐报告也会读取同一份日志并显示这些数字；如果使用 --since，报告会标明统计时间窗口。

它会自动监听所有 Agent 的调用吗？

它不会后台常驻监听所有 runtime。对于 Codex，history、stats 和 rank 会在运行时读取本地会话日志中的 Skill 激活消息，所以不需要每次手动 record。其他 runtime 没有相同日志结构时，只能使用显式 record 或对应的适配器；自动发现的 Codex 事件只代表已加载，成功/失败需要单独记录。

组合调用会不会被重复计算？

每个 Skill 都会有一条自己的调用记录，便于统计单项使用次数；同一次组合共享一个 call_id，所以 stats 还能单独给出组合调用次数，不会把一个组合误报成多个组合。

调用日志会不会保存敏感内容？

默认不会。日志只保存 Skill 名称、路径、时间、事件类型、任务类别、来源、可选结果、可选耗时和组合关系，不保存完整提示词、Token、Cookie、环境变量或文件正文。日志仍然属于本地数据，建议把它加入个人数据管理和清理计划。

能不能自动删除重复项？

不能。完全相同的正文也不代表两个目录都可以安全删除；其中一个可能被某个 runtime、项目或软链接使用。SkillTriage 只提供证据和清理建议，删除必须另行确认。

任务太模糊时应该提供什么？

至少说明目标、最终交付物和输入。例如不要只说“做个报告”，可以说“把这份 CSV 分析成带图表的中文汇报 PPT”。这些信息会直接改变 Skill 选择。

它能检查 GitHub 上还没安装的 Skill 吗？

可以。提供仓库或 Skill 目录链接，并明确说“先不要安装”。SkillTriage 会隔离候选、记录可确认的版本、阅读说明并与本机库存比较，不执行候选代码。

它能代替安全审计吗？

不能。它可以发现高风险指令、未知依赖和不完整来源，但这不是完整的代码安全审计，也不是安全认证。

已知限制

当前扫描器通过哈希确认完全相同的内容，并根据文字匹配查找候选；不内置向量模型或外部 API。
能力重复和最终任务适配仍需要 Agent 阅读完整正文后判断。
扫描器能发现常见目录，但不能仅凭目录位置证明 runtime 的真实激活优先级。
无法读取的目录或候选只能标记为“未验证”，不能推断为不存在或安全。
SkillTriage 生成安装建议，但默认不会替用户执行安装或清理。
Codex 调用统计依赖本地会话日志仍然可读；会话日志被清理、压缩或其他 runtime 没有对应结构时，历史调用无法准确补回。
自动导入只证明 Skill 已加载，不包含任务完成结果；成功、失败和被替换需要显式补充。
如果某个 runtime 只在内部进行隐式 Skill 判断、却没有写出 <skill> 激活消息，当前兼容层无法凭空补回这类调用。
Codex 目前仍在讨论标准化的 Skill 生命周期 Hook；在稳定 Hook 可用前，本项目使用本地会话日志作为兼容层（见 Codex #17132）。

可扩展方向

以下是可以继续探索的方向，不代表当前已经支持：

为超大 Skill 库增加可更新的本地索引，减少重复扫描；
与安装器建立可选的“先检查、再确认、后安装”流程；
更清楚地识别同一 Skill 的来源、版本和更新关系；
根据用户对推荐结果的接受或拒绝，改进后续候选排序；
为团队提供可共享的查重基线和变更报告。
为 Claude Code、Cursor 等 runtime 提供可选的调用记录适配器；
在不上传原始提示词的前提下，生成个人 Skill 使用趋势和闲置能力提醒。

选对再调用，查重再安装。

Name		Name	Last commit message	Last commit date
agents		agents
assets		assets
docs/superpowers/specs		docs/superpowers/specs
references		references
scripts		scripts
tests		tests
.gitignore		.gitignore
README.en.md		README.en.md
README.md		README.md
SKILL.md		SKILL.md

Latest commit

History

Folders and files

Repository files navigation

SkillTriage

你会得到什么

1. Skill 选择报告

2. 安装前检查报告

3. 调用历史与使用统计

它解决什么问题

适合谁

快速开始

第一条指令

核心能力

系统结构

组件职责

三种模式

决策流程图

三种模式的完整过程

recommend：为当前任务选 Skill

preflight：安装前检查

doctor：体检本机 Skills

history / stats：查看使用情况

它如何做决定

安装前如何查重

安装裁决

证据与报告怎么读

证据强度

一份完整报告应该回答什么

扫描范围与作用域

更多调用示例

它和相邻工具有什么不同

安全边界

失败、降级和“未验证”

内置扫描器

项目结构

验证与测试

常见问题

为什么它会回答“无需额外 Skill”？

为什么候选分数最高，却没有被推荐？

推荐报告里的调用次数会影响排序吗？

为什么安装前报告停住了，没有替我安装？

为什么清单里会出现多个同名 Skill？

能看到某个 Skill 调用了多少次吗？

它会自动监听所有 Agent 的调用吗？

组合调用会不会被重复计算？

调用日志会不会保存敏感内容？

能不能自动删除重复项？

任务太模糊时应该提供什么？

它能检查 GitHub 上还没安装的 Skill 吗？

它能代替安全审计吗？

已知限制

可扩展方向

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`recommend`：为当前任务选 Skill

`preflight`：安装前检查

`doctor`：体检本机 Skills

`history` / `stats`：查看使用情况