用途
Markdown Optimization 是一套用于分析和优化 Markdown 文档的技能，主要关注文档的体积、结构与可维护性。当 Markdown 文件过大或过于冗长、文档结构存在问题、需要规范化维护时可以使用。它提供系统化的检查方法、优化模式与报告模板，帮助将文档整理得更简洁、一致。
主要能力
- 体积检查：通过命令行统计单个或文件夹内 Markdown 的行数，并找出超过 500 行的文件。
- 结构验证：检查常见问题，包括超过 100 行缺少目录（TOC）、标题层级违规（如 h1 直接跳到 h3、跳过 h2）、单节超过 200 行等。
- 文档配置（Document Profiles）：针对不同文档类型设定优化规则与目标，包括 claude-md、architecture、domain、feature-spec、readme、agent、skill、command、guidelines。每种配置有对应的重点，例如 readme 关注快速开始与链接，skill 关注渐进式披露。
- 体积分析：以表格形式展示各文件行数、限制与状态，并对超限文件给出拆分主题、提取示例、散文转表格、移至引用等操作建议。
- 重复检测：查找跨文件的相同段落、同一概念的不同解释、复制粘贴的代码块、重复的表格或列表，并给出合并或单一来源建议。
- 结构评估：标识多个 h1、跳过层级、超长无子节的章节、缺少 TOC 等问题。
- 链接校验：提取 Markdown 链接，检查内部相对路径、锚点目标，以及外部链接；发现断链、缺失锚点和孤立文件。
- 压缩机会识别：识别可压缩的冗长模式，例如散文列表转项目符号、多段解释转表格、自文档化代码、模板加实例替换重复结构，并给出大致节省比例。
- 具体优化技术：提供散文转表格、提取示例到独立文件、使用渐进式披露（核心概念内联、高级配置与 API 引用外链）等示例。
- 自定义配置：支持在 .claude/config/md-profiles.yaml 中定义自定义配置，指定匹配模式、最大行数、规则（如是否要求 TOC、示例、最大节行数）与压缩选项。
- 报告模板：提供审计报告结构，包含执行摘要、体积问题、结构问题、重复内容、断链与优先行动建议。
使用方式
- 通过命令行进行体积检查，例如使用 wc -l 统计单个文件或 folder 内所有 markdown 文件的行数，并筛选超过 500 行的文件。
- 按配置分析文档：根据文档类型选择对应 profile，应用其目标与规则。权威限制来自 GUIDELINES.md（针对 Claude Code 产物如 agent、skill、command、guidelines 定义体积限制），本技能执行这些限制。
- 结合 /docs:optimize-md 命令使用，可使用 --profile guidelines 适配 GUIDELINES.md 生态。
- 自定义 profile 时，在 .claude/config/md-profiles.yaml 中按 patterns、max_lines、rules、compaction 等字段定义。
适用场景
- Markdown 文件过大或过于冗长，需要精简。
- 文档结构混乱，存在标题层级问题或缺少目录。
- 多文件之间存在重复内容，需要统一来源。
- 需要按文档类型（如 readme、架构文档、业务文档、功能规格、agent 提示、技能文档、斜杠命令、元知识）落实不同的优化标准。
- 需要生成 Markdown 优化审计报告，或识别压缩与渐进式披露机会。
限制
- 资料未说明该技能支持的具体平台、运行环境依赖、收费方式或价格。
- 资料未提供实际效果数据或性能指标。
- 部分细节（如 GUIDELINES.md、profiles.md、compaction-patterns.md 的完整内容）需参考对应链接，资料中未完整展开。
- 使用自定义 profile 需遵循 .claude/config/md-profiles.yaml 的配置格式，资料未说明其他配置位置。