技能优化器

---

name: skill-optimizer description: "通过真实会话数据和基于研究的静态分析来诊断和优化 Agent Skills (SKILL.md)。支持 Claude Code、Codex 及所有兼容 Agent Skills 的代理。" risk: safe source: hqhq1025/skill-optimizer (MIT) date_added: "2026-04-11"

何时使用此技能

• 当技能未按预期触发或似乎失效时
• 当你想审计和提升技能库质量时
• 当你想了解哪些技能表现不佳或浪费上下文 token 时

规则

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

概述

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

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。

工作流程

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

步骤 1：识别目标技能

按顺序扫描技能目录：~/.claude/skills/、~/.codex/skills/、~/.agents/skills/。按技能名去重（多个位置同名 = 同一技能）。对每个技能读取 SKILL.md 并提取：

• name、description（来自 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 触发率

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

Claude Code： 统计记录中的 Skill tool_use 调用。 Codex： 统计代理按照技能工作流标记产出输出的会话数（非仅加载到上下文中）。

诊断：

• 从未触发 → 技能可能无用或触发词错误
• 触发率低 → 描述可能需要优化