
关于
使用真实会话数据和基于研究的静态分析诊断并优化 Agent Skill(SKILL.md)。兼容 Claude Code 和其他 Agent 框架。
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):
Skilltool_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: 统计代理按照技能工作流标记产出输出的会话数(非仅加载到上下文中)。
诊断:
- 从未触发 → 技能可能无用或触发词错误
- 触发率低 → 描述可能需要优化