From meta-skill
Use when optimizing documents for AI reading efficiency due to excessive word count, ambiguous language, poor structure, or information scattering.
How this skill is triggered — by the user, by Claude, or both
Slash command
/meta-skill:ai-doc-optimizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**输入**: 冗长文档 → **输出**: AI 高效读取文档(收敛版本或 max_iterations 内最优版本)
输入: 冗长文档 → 输出: AI 高效读取文档(收敛版本或 max_iterations 内最优版本)
原则:
| 原则 | 说明 |
|---|---|
| 压缩 | 是结果,非目标 |
| 语义 | 保留 100% |
| 歧义 | 澄清 100% |
| 锁定 | 定位/原则 修改需用户授权 |
| 独立 | 零依赖封闭语境 |
| 迭代 | 收敛或达上限停止 |
不适用: 创意写作、法律文档、营销文案
flowchart TD
Input[输入文档] --> S0[步骤 0: 前置分析]
S0 --> S1[步骤 1: 歧义澄清]
S1 --> S2[步骤 2: 移除冗余]
S2 --> S2_5[步骤 2.5: YAGNI 检查]
S2_5 --> S3[步骤 3: 结构化]
S3 --> S4[步骤 4: 渐进式披露]
S4 --> S5[步骤 5: 质检 + 收敛判断]
S5 -->|语义丢失 | SemCheck{iteration ≥ max?}
SemCheck -->|是 | OutputWarn[输出:last_valid + 警告]
SemCheck -->|否 | Restart[基于 last_valid 重新迭代]
Restart --> S1
S5 -->|语义完整但未收敛 | IterCheck{iteration ≥ max?}
IterCheck -->|是 | OutputProblems[输出:last_valid + 未解决问题]
IterCheck -->|否 | S1
S5 -->|收敛 | Output[输出:最终文档]
执行分工:
SubAgent 启动机制:
迭代状态:
| 变量 | 含义 |
|---|---|
| iteration_count | 当前迭代次数,初始 0 |
| max_iterations | 最大迭代次数,默认 5 |
| semantic_anchor | 语义锚点(输入原文的稳定语义基准,迭代中不可替换) |
| last_valid | 当前最新语义完整版本,初始值为输入原文 |
| convergence_streak | 连续收敛计数,初始 0;满足收敛标准时 +1;未满足时置 0 |
| unresolved_issues | 达上限时仍未解决的问题列表 |
AI 理解偏差: AI 易基于训练数据产生理解偏差;明确文档定位 → 锚定优化方向 → 避免错误优化
输出模板:
1. 文档定位:目标读者、使用场景、核心目的
2. 整体结构:章节数、平均长度、层级深度
3. 问题识别:歧义(KISS)、冗余(DRY)、结构(KISS)、过度设计(YAGNI)—类型详见步骤 1–2.5
4. 优化优先级:P0 / P1 / P2
章节调整规则:
| 问题 | 规则 |
|---|---|
| 层级>4 | 扁平化至≤4 级 |
| 节>500 字 | 拆分为多小节 |
| 顺序混乱 | 快速开始→认证→参考→故障排查 |
零依赖封闭语境: 文档内自解释,不依赖外部文件、链接或上下文;读者仅读本文即可理解所有术语与流程
AI 幻觉风险: AI 存在幻觉倾向,遇歧义时易自行填充假设;澄清歧义 → 流程确定 → 降低幻觉风险
歧义类型:
| 类型 | 处理 |
|---|---|
| 模糊词 | "快速响应" → <100ms (p95) |
| 指代不明 | "该功能" → 具体名词 |
| 隐含假设 | "测试通过后提交" → 所有单元测试通过 → 提交 |
| 术语未定义 | "TDD" → TDD=测试驱动开发 |
| 语境依赖 | "正常情况" → 枚举场景 |
AI 处理效率: 冗余增加 token 消耗与推理负担;精简表述 → 降低成本 → 提升响应速度
冗余类型:
| 类型 | 处理 | DRY 层次 |
|---|---|---|
| 填充语 | "为了...→为..."、删 "需要注意的是" | 语句 |
| 被动语态 | 转主动:"系统验证数据" | 语句 |
| 弱动词 | 强化:"计算总额" | 语句 |
| 重复陈述 | 合并保留一次 | 语句 |
| 概念重复 | 保留一处,他处引用或删除 | 段落 |
| 信息分散 | 聚合到单一章节 | 段落 |
| 章节重复 | 多个章节说同一件事→合并 | 章节 |
| 表格重复 | 多个表格结构相同→合并 | 结构 |
| 流程重复 | 多个流程图有重复步骤→抽取子流程 | 结构 |
边界: 不可丢失"完整"等关键语义
AI 检索效率: AI 检索文档时有注意力偏向;低频内容 → 大概率不被注意 → 增加 token 成本
过度设计类型:
| 类型 | 判断标准 | 处理 |
|---|---|---|
| 未来内容 | 包含 "未来可能"、"后续计划"、"待实现" | 删除或移至附录 |
| 低频场景 | 文档定位中未提及,或明确标注 "罕见"、"特殊情况" | 精简或移至附录 |
| 过度详细示例 | 示例长度 > 原理说明长度的 2 倍 | 精简示例,保留核心部分 |
| 错误位置内容 | 内容与当前章节主题不匹配 | 移动至正确章节 |
边界: 保留核心场景的完整说明
AI 解析效率: 结构化数据(表格/列表)比自然语言段落解析更快更准;结构化 → 降低解析错误 → 提升理解准确度
转换规则:
| 场景 | 规则 |
|---|---|
| 并列项目 | 3+ 项→列表;含多属性→表格 |
| 步骤序列 | 有时序/依赖→编号;无序→列表 |
| 对比/分类 | 表格 |
| 流程图 | Mermaid(优先)/DOT,禁止 ASCII |
AI 上下文窗口: AI 处理长文档时注意力衰减;渐进式披露 → 核心信息前置 → 提升关键信息提取率
| 文档大小 | 结构 |
|---|---|
| <300 行 | 单层 |
| ≥300 行 | 概述→核心→详情→示例 |
原则: 高频前置,低频后置
AI 自我验证: AI 易过度自信跳过验证;强制质检 → 对比 last_valid → 防止语义丢失与过度优化
收敛标准(同时满足):
| 检查项 | 标准 |
|---|---|
| 语义等价 | 与 semantic_anchor 100% 等价 |
| 结构稳定 | 章节/列表/表格无变化 |
| 表述一致 | 关键术语/定义无变化 |
| 无新增修复 | 本轮未新增歧义澄清或冗余移除 |
判定逻辑:
semantic_anchor)→ 回滚到 last_valid;达上限则输出 last_valid + 警告convergence_streak+1;convergence_streak>=2 才输出收敛版本convergence_streak=0,更新 last_valid 并进入下一轮last_valid + unresolved_issues质检项(部署时逐项勾选):
| 错误 | Red Flag | 修复 |
|---|---|---|
| 主 Agent 自己执行优化 | "这个很快,我直接做" | 必须调度 SubAgent 执行步骤 0-5 |
| 过度压缩 | "字数减少就是好" | 保留 100% 语义 |
| 微改动 | "改了一点就算优化" | 忽略(歧义澄清除外) |
| 未锁定区域 | "定位/原则可以优化" | 锁定定位/原则 |
| ASCII 流程图 | "ASCII 更简单" | 使用 Mermaid/DOT |
| 未达收敛停止 | "差不多就行了" | 连续 2 轮收敛或达上限 |
| 未检查章节重复 | "语句不重复就行" | 检查章节/表格/流程图重复 |
| 保留低频内容 | "AI 可能用得上" | 删除或移至附录 |
| 过度详细示例 | "示例越多越好" | 精简示例,保留核心 |
| 用最新版本替换语义锚点 | "每轮基准都更新更灵活" | semantic_anchor 固定为输入原文,不可替换 |
Red Flags(停止并重新开始):
| 情况 | 处理 |
|---|---|
| 主 Agent 未调度 SubAgent | 停止,调度 SubAgent 重新执行 |
| 语义丢失 | 基于 last_valid 重新迭代 |
| 定位/原则 被改 | 恢复并锁定 |
wc -w skills/<skill-name>/SKILL.md # 检查字数
rg "semantic_anchor|last_valid|convergence_streak|max_iterations" skills/<skill-name>/SKILL.md
npx claudepluginhub z-jade/meta-skill --plugin meta-skillProposes cuts, reorganization, and simplification to improve document structure, clarity, and flow while preserving comprehension. Use for structural or editorial reviews.
Proposes cuts, reorganization, and simplification to improve document structure, clarity, and flow while preserving comprehension. Use for structural or editorial reviews.
Mechanically tightens prose by restructuring sections, splitting/merging paragraphs, and removing redundancy. Preserves voice, register, and tone. Use for compressing plan files, READMEs, ADRs, and design docs.