| name | skill-optimizer |
| description | 优化、审查或诊断 Agent Skills（SKILL.md）。用于 skill 质量分析、重构技能、skills 不触发、skill 没生效、optimize skills、analyze skills、check my skills。 |
| disable-model-invocation | false |
Skill Optimizer
路径选择
| 路径 | 行为 | 典型触发 |
|---|
| A — 结构化改写 | 读目标 skill → 诊断与计划 → 用户确认后才改 SKILL.md / references / scripts | 用户附着或指定路径、说「改 description」「拆 references」「加确认步骤」 |
| B — 会话审计 | 扫描本机 skill 目录与历史会话 jsonl，只输出报告，绝不写 skill 文件 | /optimize-skill、/skill-audit、「分析我所有 skills」「skill 从不触发」「只审计不要改」 |
判定： 用户明确「只分析 / 只出报告 / 不要改」→ B。用户点名要改某 skill 且未禁止写文件 → A（无确认仍不得改）。「先看全局再改」→ 先做 B，再在用户要求下对单项切 A。
共用规则
- 官方规范优先（双轨）：每次启动先执行下方 Step 0 — Fetch Spec（三级降级：代理 → 直连 → 本地缓存），未完成前禁止进入诊断、计划或改写阶段。
- 路径 B：只读。 不得修改任何 skill 文件，只交付报告（Step 0 对缓存文件的覆盖是允许的例外，因为它属于 skill 自身的资产更新而非被审计 skill 的修改）。
- 路径 A：确认门槛。 不得把「审查结论」与「直接改文件」混为一步；未确认不得改目标 skill。
- 路径 B：八维齐全。 不得跳过 references/session-audit-dimensions.md 中的 4.2、4.3、4.5b、4.8；缺数据写
N/A — insufficient session data。
- 量化与证据： 报告用次数、比例、日期范围；欠触发须引用真实用户原句；description 改写用建议语气并点明依据（静态表条目、官方规范条款或研究结论）。
- 范围克制： 用户只要某一方向（如只改 description）时，围绕该方向计划，不擅自整 skill 重写；不要为了「全面」把无关 reference 全读进上下文。
- 路径统一用
${CLAUDE_SKILL_DIR}： 任何「读 / 写 / 引用本 skill 资源」的动作（含脚本、Bash、Read、Write、WebFetch 后落盘）都使用 ${CLAUDE_SKILL_DIR}/... 形式，不写死绝对路径，不写仓库相对路径。
Pipeline 类 skill 的特别处理
当目标 skill 在 Step 2 Review 中被判定为 Pipeline（主模式或次模式），或满足 ≥3 个 workflow-skill-creator 适用信号（≥3 顺序步骤 / 跨步骤状态传递 / 需脚本辅助 / 需进度文件 / 强制顺序、跳步导致失败），按以下规则叠加评审基准：
- 必读资产：
${CLAUDE_SKILL_DIR}/../workflow-skill-creator/references/architecture_patterns.md（六大架构模式）与 quality_checklist.md（七维自检）
- 基准合并：Step 5 Verify 须在
review-checklist.md 之上叠加 workflow-skill-creator 的 quality_checklist；针对编排专门规范遇冲突时以 workflow-skill-creator 为准
- Plan 输出义务：Step 3 Plan 必须在末段写明「目标 skill 已识别为 Pipeline，对照 workflow-skill-creator 六大模式逐项核对」并列出未达标项
- 跨 skill 路径：两 skill 同属
agents-dev plugin，故用 ${CLAUDE_SKILL_DIR}/../workflow-skill-creator/... 引用；若日后被拆到不同 plugin，需改为目标 plugin 的解析路径
路径 B 工作流（概要）
- Step 0 — Fetch Spec：执行下方「Step 0 详细流程」；本轮基准来自最新抓取或
${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md 缓存。
- 锁定范围：
/optimize-skill 全量，或 /optimize-skill a b 指定多个 name。
- 发现 skill：按 session-audit-dimensions.md 中的目录顺序扫描并去重，读 frontmatter 与步骤结构。
- 采集会话：Claude Code / Codex jsonl 字段差异见该文档；Codex 注意「加载 ≠ 已按 skill 执行」。
- 跑满八维 + 综合分：表格、权重、报告骨架均见该文档；遇到与官方规范不一致处，须在报告中以「依据：官方规范 §X」标注。
- 输出：使用该文档中的 Report Format；P0 / P1 / P2 分级；报告首段写明「本轮使用的官方规范来源（live / cache）+ fetched_at」。
路径 A 工作流
复制并跟踪进度：
优化进度：
- [ ] 步骤 0：Fetch Spec（拉取并阅读最新官方规范，必要时落盘缓存）
- [ ] 步骤 1：Scope（确定范围）
- [ ] 步骤 2：Review（审查目标 skill）
- [ ] 步骤 3：Plan（输出优化计划并等待确认）
- [ ] 步骤 4：Implement（确认后实施）
- [ ] 步骤 5：Verify（校验结果）
Step 0: Fetch Spec（共用，路径 A / B 都执行）
按以下顺序执行，并在最终报告/汇报里写明走到了哪一支：
- 尝试在线抓取（代理优先）：调用
WebFetch，URL = https://proxy.sumsec.me/https://code.claude.com/docs/en/skills.md；若代理失败，再尝试直连 WebFetch https://code.claude.com/docs/en/skills.md。prompt 要求按官方原文返回完整 markdown（重点保留 frontmatter 字段表、调用控制、动态上下文、subagent、可见性、分发、字符串替换 ${CLAUDE_SKILL_DIR} 等条款）。
- 成功 → 覆盖缓存：把抓取到的官方文档整文件覆盖到
${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md，并保留头部注释块（来源、fetched_at、method 字段）。本轮以「live」为基准。
- 失败 / 离线 / 用户要求离线 → 读缓存：
Read ${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md，本轮以「cache」为基准；在最终汇报第一行用一句话标注：⚠️ 使用本地缓存基准（fetched_at: <时间>）。
- 基准摘要：从 live 或 cache 中摘录本轮要用到的条款（frontmatter 字段、调用控制、动态上下文、subagent、分发、新增/废弃项），作为 Step 2 / Step 3 / Step 5 的判定基准；保留官方原句中的关键术语，禁止改写。
- 禁止事项：禁止跳过 Step 0；禁止仅凭"SKILL.md 里曾经引用过官方文档链接"就视作完成；禁止把缓存文件改成与官方原文严重偏离的精简版（精简放到摘要里，不要污染缓存）。
Step 1: Scope
确认目标 skill 与优化范围；目标不明时只问一个最短问题。
Step 2: Review
先读目标 SKILL.md，再按需读其直接链接的 references/、scripts/、assets/。本 skill 自身的 references 一律通过 ${CLAUDE_SKILL_DIR}/references/<file> 定位（下面的 markdown 链接是相对路径展示，实际工具调用请用 ${CLAUDE_SKILL_DIR} 形式）：
Review 关注点保持与原 skill 一致：name、description、模式匹配、确认门槛、渐进披露、输出可执行性等。额外固定关注：被审查 skill 是否正确使用 ${CLAUDE_SKILL_DIR} 引用自身资源——动态上下文、Bash 命令、脚本路径、Read/Write 目标、缓存落盘位置都必须用该变量；写死 ~/.claude/skills/...、绝对路径、仓库相对路径属于反模式（详见 ${CLAUDE_SKILL_DIR}/references/claude-code-skills-checklist.md §7）。
Step 3: Plan
先诊断再计划，不改文件。输出须包含「审查结论」（模式判断 + 高/中/低优先级问题）与「优化计划」（文件级变更、原因、是否用户指定方向），末句：请确认是否按以上计划执行。
Step 4: Implement
用户确认后再改；小步、新增 reference 须在 SKILL.md 中直接链接。
Step 5: Verify
- 已对照 Step 0 抓取或缓存的官方规范条款逐条核对：
description / 调用控制 / 动态上下文 / subagent / 分发等改动有据可循
- frontmatter 字段符合目标平台规范；
name 与目录一致；description 可独立表达触发条件；额外字段均有明确意图
- 已按
${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md（或 Step 0 live 抓取摘要）校验技能位置、命令兼容、扩展 frontmatter、调用控制、动态上下文、subagent、可见性覆盖、分发要求与简洁性 / 渐进披露 / 命名 / description 等基础项
review-checklist.md 已覆盖 Claude Code 新特性；必要时按 ${CLAUDE_SKILL_DIR}/references/claude-code-skills-checklist.md 细查- 若目标为 Pipeline 类：已对照
${CLAUDE_SKILL_DIR}/../workflow-skill-creator/references/quality_checklist.md 七维（结构 / 进度文件 / 执行规范 / 前置门槛 / 依赖 / 触发 / 输出）自检；六大架构模式（进度文件驱动、步骤框架分离、三阶段执行、脚本自动化、资源分层、路径一致性）改造结果可追溯到 architecture_patterns.md
- 正文更短更清晰；路径 A 的确认门槛仍在说明中写清
- 若借鉴了 4.4：description 含
: 时 YAML 用双引号包裹等
- 任何脚本 / Bash 引用本 skill 内文件，路径都形如
${CLAUDE_SKILL_DIR}/...，不写死本机绝对路径
汇报：已改文件、已落实方向、本轮基准来源（live fetched_at 或 cache fetched_at）、残留风险。
审查优先级（路径 A 快速裁定）
- 触发失败、确认缺失、流程不可执行
- 结构臃肿、重复、资源组织混乱
- 措辞与示例润色
与上游的关系
会话八维、评分与报告模板与 xget 镜像的 SKILL.md 对齐，并压缩进 references/session-audit-dimensions.md 以降低 Tier2 体积。
