skill-optimizer

star 3

用于优化、审查或诊断 Agent Skills（SKILL.md）：优化 skill、skill 质量、重构技能、/optimize-skill、/skill-audit、optimize skills、analyze skills、check my skills、skills 不触发、skill 没生效。

SummerSec By SummerSec schedule Updated 6/3/2026
play_arrow Run Skill in Manus View GitHub

name: skill-optimizer description: "用于优化、审查或诊断 Agent Skills（SKILL.md）：优化 skill、skill 质量、重构技能、/optimize-skill、/skill-audit、optimize skills、analyze skills、check my skills、skills 不触发、skill 没生效。" disable-model-invocation: true

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。

共用规则

  • 官方规范优先（双轨）：每次启动本 skill，先执行 Step 0 — Fetch Spec：
    1. 先 WebFetch https://code.claude.com/docs/en/skills.md；
    2. 成功：把抓取结果写入（覆盖）${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md，并以此为本轮判定基准；
    3. 失败 / 无网络 / 用户要求离线：直接 Read ${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md 作为降级基准，并在报告醒目处标注「⚠️ 使用本地缓存基准（fetched_at: …）」。 无论路径 A / B，未完成 Step 0 之前禁止进入诊断、计划或改写阶段。
  • 路径 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 工作流（概要）

  1. Step 0 — Fetch Spec：执行下方「Step 0 详细流程」；本轮基准来自最新抓取或 ${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md 缓存。
  2. 锁定范围：/optimize-skill 全量，或 /optimize-skill a b 指定多个 name。
  3. 发现 skill：按 session-audit-dimensions.md 中的目录顺序扫描并去重，读 frontmatter 与步骤结构。
  4. 采集会话：Claude Code / Codex jsonl 字段差异见该文档；Codex 注意「加载 ≠ 已按 skill 执行」。
  5. 跑满八维 + 综合分：表格、权重、报告骨架均见该文档；遇到与官方规范不一致处，须在报告中以「依据：官方规范 §X」标注。
  6. 输出：使用该文档中的 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 都执行）

按以下顺序执行，并在最终报告/汇报里写明走到了哪一支：

  1. 尝试在线抓取：调用 WebFetch，URL = https://code.claude.com/docs/en/skills.md，prompt 要求按官方原文返回完整 markdown（重点保留 frontmatter 字段表、调用控制、动态上下文、subagent、可见性、分发、字符串替换 ${CLAUDE_SKILL_DIR} 等条款）。
  2. 成功 → 覆盖缓存：把抓取到的官方文档整文件覆盖到 ${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md，并保留头部注释块（来源、fetched_at、method 字段）。本轮以「live」为基准。
  3. 失败 / 离线 / 用户要求离线 → 读缓存：Read ${CLAUDE_SKILL_DIR}/references/official-spec-fetch.md，本轮以「cache」为基准；在最终汇报第一行用一句话标注：⚠️ 使用本地缓存基准（fetched_at: <时间>）。
  4. 基准摘要：从 live 或 cache 中摘录本轮要用到的条款（frontmatter 字段、调用控制、动态上下文、subagent、分发、新增/废弃项），作为 Step 2 / Step 3 / Step 5 的判定基准；保留官方原句中的关键术语，禁止改写。
  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 快速裁定）

  1. 触发失败、确认缺失、流程不可执行
  2. 结构臃肿、重复、资源组织混乱
  3. 措辞与示例润色

与上游的关系

会话八维、评分与报告模板与 xget 镜像的 SKILL.md 对齐，并压缩进 references/session-audit-dimensions.md 以降低 Tier2 体积。

Install via CLI
npx skills add https://github.com/SummerSec/SumSec-Skills --skill skill-optimizer
Repository Details
star Stars 3
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
SummerSec
SummerSec Explore all skills →