skill-optimizer

何时使用此技能

• 技能未按预期触发或似乎出现故障时
• 想要审查并提升技能库的质量时
• 想要了解哪些技能表现不佳或浪费上下文令牌时

规则

• 只读：绝不修改技能文件。仅输出报告。
• 全部 8 个维度：不得跳过任何维度。如果数据不足，请报告“ N/A — 会话数据不足”，而不是省略。
• 量化：“你上周有 12 个研究任务，但该技能从未触发”比“你经常做研究”更有说服力。
• 提出建议，不要强行规定：提供具体的描述改进措辞建议，但要以建议的方式表达。
• 展示证据：对于未触发的说法，请引用本应触发该技能的实际用户消息。
• 基于证据提出建议：建议重写描述时，引用促使该建议的具体研究发现（例如：“将触发关键词前置——MCP 研究显示，选择率提升了 3.6 倍”）。

概述

结合历史会话数据 + 静态质量检查分析技能，并输出包含 P0/P1/P2 优先级修复项的诊断报告。按照 8 个维度对每项技能进行综合评分，满分为 5 分。

CSO（Claude/Agent 搜索优化）= 编写技能描述，让 Agent 在合适的时机选择正确的技能。此技能用于检查 CSO 违规情况。

用法

• /optimize-skill → 扫描所有技能
• /optimize-skill my-skill → 扫描单项技能
• /optimize-skill skill-a skill-b → 扫描多个指定技能

数据来源

自动检测当前 Agent 平台并扫描相应路径：

来源	Claude Code	Codex	共享
会话记录	~/.claude/projects/**/*.jsonl	~/.codex/sessions/**/*.jsonl	—
技能文件	~/.claude/skills/*/SKILL.md	~/.codex/skills/*/SKILL.md	~/.agents/skills/*/SKILL.md

**平台检测：**检查哪些目录存在。仅使用用户授权的平台、日期范围和记录。目录存在并不代表已获准读取无关的聊天记录。报告中应隐去私人消息和机密信息；优先使用最少量的摘录并在本地分析。

工作流

Identify target skills
        ↓
Collect session data (python3 scripts scan JSONL transcripts)
        ↓
Run 8 analysis dimensions
        ↓
Compute composite scores
        ↓
Output report with P0/P1/P2

第 1 步：确定目标技能

按顺序扫描技能目录：~/.claude/skills/、~/.codex/skills/、~/.agents/skills/。通过解析后的路径和内容哈希识别副本；多个位置中名称相同的技能可能包含不同版本，不得在不说明的情况下合并。对于每项技能，读取 SKILL.md 并提取：

• 名称、描述（来自 YAML frontmatter）
• 触发关键词（来自 description 字段）
• 定义的工作流步骤（Step 1/2/3... 或 Workflow 下的 ### 章节）
• 字数

如果用户指定了技能名称，则仅筛选这些技能。

步骤 2：收集会话数据

使用 Python3 脚本，通过 Bash 扫描会话 JSONL 文件。提取：

Claude Code 会话（~/.claude/projects/**/*.jsonl）：

• Skill tool_use 调用（调用了哪些技能）
• 用户消息（完整文本）
• 技能调用后的助手消息（用于工作流跟踪）
• 技能调用后的用户消息（用于反应分析）

Codex 会话（~/.codex/sessions/**/*.jsonl）：

• session_meta 事件 → 提取 base_instructions，作为技能加载证据
• response_item 事件 → 助手输出（工作流跟踪）
• event_msg 事件 → 工具执行和技能相关事件
• turn_context 事件中的用户消息（用于反应分析）

注意： Codex 通过上下文注入技能，而不是显式的 Skill 工具调用。加载技能（存在于 base_instructions 中）不等于主动调用。要检测实际使用情况，请在该会话的 response_item 内容中查找特定于技能的工作流标记（步骤标题、输出格式）。工作流标记是可能使用技能的间接证据，并非调用的确凿证明；请将已确认的调用与推断出的匹配分别报告，并记录不确定性。不同客户端版本的转录记录架构可能不同；提取消息前，请先检查实际事件结构。

汇总：

• 按技能统计：调用次数、触发关键词匹配次数
• 按技能统计：调用后的用户反应情绪
• 按技能统计：工作流步骤完成标记

步骤 3：运行 8 个分析维度

必须运行全部 8 个维度。 不使用此技能时的基准行为是跳过 4.2、4.3、4.5b 和 4.8 维度。这些维度最有价值——请勿跳过。

4.1 触发率

统计每个技能实际被调用的次数，以及其触发关键词在用户消息中出现的次数。

Claude Code： 统计转录记录中的 Skill tool_use 调用。 Codex： 统计 Agent 产生了遵循该技能工作流标记的输出的会话（而非仅仅在上下文中加载技能的会话）。

诊断：

• 从未触发 → 技能可能无用，或触发词不正确
• 关键词匹配次数远高于实际调用次数 → 触发不足，需要改进描述
• 频率较高 → 核心技能，值得优化

4.2 调用后的用户反应

此维度至关重要，也很容易被跳过。请勿跳过。

技能在某个会话中被调用后，阅读用户接下来的 3 条消息。分类如下：

• 负面：“不”“错了”“算了”“不是我想要的”，或用户打断
• 纠正：用户重新描述意图，手动覆盖技能输出
• 正面：“好”“可以”“继续”“不错”，或用户遵循工作流
• 无提示切换：用户完全转移话题（可能是误触发）

报告观察到的反应类别及样本数；保持沉默、打断和话题切换都不能证明用户不满意或发生了误触发。

4.3 工作流完成率

此维度至关重要，也很容易被跳过。请勿跳过。

对于会话数据中找到的每次技能调用：

1. 从 SKILL.md 中提取该技能定义的步骤
2. 在该会话的助手消息中查找步骤标记（Step N、技能中定义的特定输出格式）
3. 计算执行进度

报告：{skill-name} (N steps): avg completed Step X/N (Y%)

如果执行经常在某个特定步骤停止，请标记出来。

4.4 静态质量分析

根据以下 14 条规则检查每个 SKILL.md：

检查项	通过标准
Frontmatter 格式	根据目标宿主／仓库架构进行验证；允许使用其他受支持的元数据
名称格式	仅包含字母、数字和连字符
描述中的触发条件	以 "Use when..." 开头，或包含明确的触发条件
描述泄露工作流	描述不得概述技能的工作流步骤（违反 CSO）
描述的主动性	描述主动说明应在哪些场景中使用，而非仅被动陈述
概述部分	存在
规则部分	存在
MUST/NEVER 密度	统计所有全大写的指令词；每 100 个词超过 5 个则标记
字数	少于 500 词（超出则标记）
叙事反模式	不包含“In session X, we found...”这类讲述经历的内容
YAML 引号安全性	description 中包含 : 时，必须用双引号括起来
关键信息位置	核心触发条件和主要操作必须位于 SKILL.md 的前 20%
描述的 250 字符检查	主要触发关键词必须出现在描述的前 250 个字符内
触发条件数量	描述中理想情况下不超过 2 个触发条件

4.5a 误触发率（过度触发）

技能被调用，但用户立即拒绝或忽略了它。

4.5b 触发不足检测

这是价值最高的维度。 对每项技能，提取其能力关键词（不只是触发关键词——即该技能能做什么）。然后扫描用户消息，查找与这些能力匹配、但未调用该技能的任务。

报告：哪些用户消息本应触发该技能却没有，并提出描述改进建议。

累积风险评估： 对于长期触发不足的技能（在 5 个或更多存在相关任务的会话中触发次数为 0），标记为“累积风险”——触发不足的技能无法通过使用反馈自我改进，导致差距随时间扩大。建议立即将描述重写为 P0 优先级。

4.6 跨技能冲突

比较所有技能对：

• 触发关键词重叠（两个描述中包含相同关键词）
• 工作流重叠（两个技能教授相似流程）
• 指导意见相互矛盾

4.7 环境一致性

对每项技能，提取其中引用的：

• 文件路径 → 检查是否存在（test -e）
• CLI 工具 → 检查是否已安装（which）
• 目录 → 检查是否存在

标记所有失效引用。

4.8 令牌经济性

此维度至关重要，也很容易被忽略。请勿跳过。

对每项技能：

• 字数（来自步骤 1）
• 触发频率（来自 4.1）
• 成本效益 = 触发次数 / 字数
• 标记：较长且从未触发的技能，考虑删除或压缩

渐进式披露层级检查： 根据 3 层加载模型评估每项技能：

• 第 1 层（frontmatter）：约 100 个令牌。检查：描述是否不超过 1024 个字符？
• 第 2 层（SKILL.md 正文）：建议少于 500 行。检查：字数。
• 第 3 层（参考文件）：按需加载。检查：技能是否使用参考文件存放详细内容，还是将所有内容都塞进 SKILL.md？

如果技能在未使用参考文件的情况下，将 500 个或更多词写入 SKILL.md，则标记为“渐进式披露欠佳”。

步骤 4：综合评分

按 5 分制为每项技能评分：

分数	含义
5	健康：触发率高、用户反应积极、工作流完整、静态质量良好
4	良好：有 1-2 个维度存在小问题
3	需要关注：有 1 个维度存在明显差距，或有 3 个及以上维度存在小差距
2	有问题：从未触发，或用户反应消极，或存在重大静态问题
1	不可用：无法工作、引用缺失，或根本不匹配

评分维度（加权平均）：

• 触发率：25%
• 用户反应：20%
• 工作流完成度：15%
• 静态质量：15%
• 触发不足：15%
• Token 经济性：10%

定性维度（仅报告，不计分）：

• 4.5a 过度触发：报告数量和示例
• 4.6 技能间冲突：报告冲突对
• 4.7 环境一致性：针对每项引用报告通过/失败

报告格式

# Skill Optimization Report
**Date**: {date}
**Scope**: {all / specified skills}
**Session data**: {N} sessions, {date range}

## Overview
| Skill | Triggers | Reaction | Completion | Static | Undertrigger | Token | Score |
|-------|----------|----------|------------|--------|--------------|-------|-------|
| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |

## P0 Fixes (blocking usage)
1. ...

## P1 Improvements (better experience)
1. ...

## P2 Optional Optimizations
1. ...

## Per-Skill Diagnostics
### {skill-name}
#### 4.1 Trigger Rate
...
#### 4.2 User Reaction
...
(all 8 dimensions)

研究背景

所引用的研究针对特定模型和任务，不能证明技能路由普遍改善、字数限制或因果效应。引用数值效果前，请核实每篇论文及其实验设置。静态评分、触发不足匹配和 Token 比率应视为参考性启发指标，而非功能、安全或合并认证。如果某个维度缺乏可靠证据，请报告 N/A，而不要将其估算后计入综合评分。

本报告中的分析维度基于以下研究：

• 触发不足检测：Memento-Skills（arXiv:2603.18743）——技能以结构化文件形式存在，需要准确路由；未路由的技能无法通过读写学习循环自我改进
• 描述质量：MCP Description Quality（arXiv:2602.18914）——撰写良好的描述达到 72% 的工具选择率，而随机基线为 20%（提升 3.6 倍）
• 信息位置：Lost in the Middle（Liu 等，TACL 2024）——LLM 注意力曲线呈 U 形
• 格式影响：He 等（arXiv:2411.10541）——仅格式变化就可能导致 9-40% 的性能差异
• 指令遵循：IFEval（arXiv:2311.07911）——LLM 难以遵循包含多项约束的提示词

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请暂停并请求澄清。