---

name: skill-optimizer
description: “Diagnose and optimize Agent Skills (SKILL.md) with real session data and research-backed static analysis. Works with Claude Code, Codex, and any Agent Skills-compatible agent.”
risk: safe
source: hqhq1025/skill-optimizer (MIT)
date_added: “2026-04-11”

何时使用此技能

• 当技能没有按预期触发或似乎损坏时使用
• 当您想要审计并改进技能库的质量时使用
• 当您想要了解哪些技能表现不佳或浪费上下文令牌时使用

规则

• 只读：绝不修改技能文件。只输出报告。
• 全部 8 个维度：不要跳过任何一个。如果数据不足，报告"N/A — 会话数据不足"而不是省略。
• 量化："上周您有 12 个研究任务，但该技能从未触发"比"您经常做研究"更好。
• 建议而非规定：对描述改进给出具体的措辞建议，但以建议的形式呈现。
• 展示证据：对于触发不足的主张，引用本应触发该技能的实际用户消息。
• 基于证据的建议：在建议重写描述时，引用支持该变更的具体研究发现（例如"前置触发关键词——MCP 研究表明选择率提升 3.6 倍"）。

概述

使用历史会话数据 + 静态质量检查分析技能，输出带有 P0/P1/P2 优先级修复的诊断报告。按 5 分制综合评分，跨 8 个维度为每个技能打分。

CSO（Claude/Agent 搜索优化）= 编写技能描述，使代理在正确的时间选择正确的技能。此技能检查 CSO 违规情况。

用法

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

数据来源

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

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

平台检测： 检查哪些目录存在。扫描所有可用来源——用户可能同时安装了 Claude Code 和 Codex。

工作流程

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 并提取：

• name、description（来自 YAML frontmatter）
• 触发关键词（来自 description 字段）
• 定义的工作流程步骤（步骤 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： 统计代理产生了遵循技能工作流程标记的输出（而不仅仅是在上下文中加载）的会话次数。

诊断：

• 从未触发 → 技能可能无用或触发词错误
• 关键词匹配数 >> 实际调用数 → 触发不足问题，描述需要改进
• 高频 → 核心技能，值得优化

4.2 调用后的用户反应

此维度至关重要且容易被跳过。不要跳过它。

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

• 负面：“no”、“wrong”、“never mind”、“not what I wanted”、用户打断
• 纠正：用户重新描述他们的意图、手动覆盖技能输出
• 正面：“good”、“ok”、“continue”、“nice”、用户遵循工作流程
• 静默切换：用户完全改变话题（很可能是误触发）

报告每个技能的满意度。

4.3 工作流程完成率

此维度至关重要且容易被跳过。不要跳过它。

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

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

报告：{skill-name}（N 个步骤）：平均完成 Step X/N（Y%）

如果某个特定步骤经常是执行停止的地方，标记它。

4.4 静态质量分析

对照这 14 条规则检查每个 SKILL.md：

检查项	通过标准
Frontmatter 格式	只有 name + description，总计 < 1024 字符
名称格式	仅限字母、数字、连字符
描述触发条件	以"Use when…"开头或有明确的触发条件
描述泄露工作流程	描述不总结技能的工作流程步骤（CSO 违规）
描述主动性	描述主动声明应使用它的场景，而非被动
概述部分	存在
规则部分	存在
MUST/NEVER 密度	统计全部大写的指令词；每 100 词 > 5 个则标记
字数	< 500 词（超出则标记）
叙事反模式	没有"在会话 X 中，我们发现…"式讲故事
YAML 引用安全性	包含 : 的 description 必须用双引号包裹
关键信息位置	核心触发条件和主要操作必须位于 SKILL.md 的前 20%
描述 250 字符检查	主要触发关键词必须出现在 description 的前 250 个字符内
触发条件数量	description 中 ≤ 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 令牌。检查：description 是否 ≤ 1024 字符？
• 第 2 层（SKILL.md 主体）：建议 < 500 行。检查：字数。
• 第 3 层（参考文件）：按需加载。检查：技能是否为详细内容使用参考文件，还是把一切都塞进 SKILL.md？

将那些在 SKILL.md 中放入 500+ 词而不使用参考文件的技能标记为"渐进式披露不佳"。

第 4 步：综合评分

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

分数	含义
5	健康：高触发率、积极反应、完整的工作流程、干净的静态质量
4	良好：1-2 个维度有轻微问题
3	需要注意：1 个维度有显著差距或 3+ 个维度有轻微差距
2	有问题：从未触发，或用户反应负面，或存在重大静态问题
1	损坏：不起作用、引用缺失或根本性错位

计分维度（加权平均）：

• 触发率：25%
• 用户反应：20%
• 工作流程完成：15%
• 静态质量：15%
• 触发不足：15%
• 令牌经济学：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)

研究背景

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

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

局限性

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