# Skill Optimizer

> 使用真实会话数据和研究支持的静态分析来诊断和优化智能体技能（SKILL.md）。适用于 Claude Code、Codex 及任何兼容 Agent Skills 的智能体。触发词：优化技能、技能诊断、技能审计、技能质量分析、optimize skill、skill audit、skill diagnostics

- Skill: `kscz0000/skill-optimizer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/skill-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/skill-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/skill-optimizer

---


## 使用场景

- 技能未按预期触发或似乎损坏时
- 想要审计和提升技能库质量时
- 想要了解哪些技能表现不佳或浪费上下文 token 时

## 规则

- **只读**：绝不修改技能文件，仅输出报告。
- **全部 8 个维度**：不得跳过任何维度。数据不足时报告"N/A — 会话数据不足"而非省略。
- **量化**："你上周有 12 个研究任务但该技能从未触发"优于"你经常做研究"。
- **建议而非指令**：为描述改进提供具体措辞建议，但以建议形式呈现。
- **展示证据**：对于触发不足的声明，引用实际应该触发该技能的用户消息。
- **基于证据的建议**：建议描述重写时，引用驱动该变更的具体研究发现（例如"前置触发关键词 — MCP 研究显示选择率提升 3.6 倍"）。

## 概述

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

CSO（Claude/智能体搜索优化）= 编写技能描述，使智能体在正确的时间选择正确的技能。此技能检查 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。

## 工作流

```
识别目标技能
        ↓
收集会话数据（python3 脚本扫描 JSONL 记录）
        ↓
运行 8 个分析维度
        ↓
计算综合评分
        ↓
输出包含 P0/P1/P2 的报告
```

### 步骤 1：识别目标技能

按顺序扫描技能目录：`~/.claude/skills/`、`~/.codex/skills/`、`~/.agents/skills/`。按技能名称去重（多个位置的同名技能 = 同一技能）。对每个技能读取 `SKILL.md` 并提取：
- name、description（来自 YAML frontmatter）
- 触发关键词（来自 description 字段）
- 定义的工作流步骤（Workflow 下的 Step 1/2/3... 或 ### 章节）
- 字数

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

### 步骤 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 条消息。分类：
- **否定**："不对"、"错了"、"算了"、"不是我想要的"、用户打断
- **修正**：用户重新描述意图，手动覆盖技能输出
- **肯定**："好"、"行"、"继续"、"不错"、用户遵循工作流
- **沉默切换**：用户完全换话题（可能是误触发）

报告每个技能的满意度。

#### 4.3 工作流完成率

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

对会话数据中发现的每次技能调用：
1. 从 SKILL.md 提取技能定义的步骤
2. 在该会话的助手消息中搜索步骤标记（Step N、技能中定义的特定输出格式）
3. 计算：执行到了哪一步？

报告：`{技能名称}（N 步）：平均完成到第 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 Token 经济性

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

对每个技能：
- 字数（来自步骤 1）
- 触发频率（来自 4.1）
- 成本效益 = 触发次数 / 字数
- 标记：大型且从未触发的技能作为移除或压缩候选

**渐进式披露层级检查：**
按 3 层加载模型评估每个技能：
- 第 1 层（frontmatter）：约 100 token。检查：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%
- Token 经济性：10%

**定性维度**（报告但不评分）：
- 4.5a 误触发：按计数 + 示例报告
- 4.6 跨技能冲突：按冲突对报告
- 4.7 环境一致性：按每个引用的通过/失败报告

## 报告格式

```markdown
# 技能优化报告
**日期**：{日期}
**范围**：{全部 / 指定技能}
**会话数据**：{N} 个会话，{日期范围}

## 概览
| 技能 | 触发 | 反应 | 完成率 | 静态 | 触发不足 | Token | 评分 |
|------|------|------|--------|------|----------|-------|------|
| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |

## P0 修复（阻塞使用）
1. ...

## P1 改进（更好的体验）
1. ...

## P2 可选优化
1. ...

## 逐技能诊断
### {技能名称}
#### 4.1 触发率
...
#### 4.2 用户反应
...
（全部 8 个维度）
```

## 研究背景

本报告中的分析维度基于以下研究：
- **触发不足检测**：Memento-Skills（arXiv:2603.18743）— 技能作为结构化文件需要准确的路由；未路由的技能无法通过读写学习循环自我改进
- **描述质量**：MCP Description Quality（arXiv:2602.18914）— 精心编写的描述实现 72% 的工具选择率，而随机基线为 20%（提升 3.6 倍）
- **信息位置**：Lost in the Middle（Liu et al., TACL 2024）— LLM 的 U 形注意力曲线
- **格式影响**：He et al.（arXiv:2411.10541）— 仅格式变化就能导致 9-40% 的性能差异
- **指令遵从**：IFEval（arXiv:2311.07911）— LLM 在多约束提示词下表现挣扎

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