Markdown 文档格式化 Skill

工作流程

当用户要求格式化文档时，按以下顺序执行：

1. 语法检查和修复

使用 markdown-checker 脚本检查文档：

python3 ~/.claude/skills/markdown-checker/scripts/check_markdown.py "文件路径"

修复优先级：

• ❌ 错误：必须修复（链接格式、代码块闭合、列表格式）
• ⚠️ 警告：建议修复（行尾空格、标点符号、缩进）
• ℹ️ 提示：可选修复（排版建议）

注意：

• YAML frontmatter 的 --- 会被误报为列表，忽略这个错误
• 只修复真正影响语法的问题，不要过度优化

2. 智能分段

分段原则：

• 长段落（超过 100 字符）需要分段
• 在句号、问号、感叹号后分段
• 在冒号、分号后分段（如果后面是完整句子）
• 保持语义完整性，不要破坏逻辑连贯性

分段示例：

原句：今天研究了语音输入法，基于 fun-asr-nano，很有意思。其实核心是速度和准确度。

分段后：
今天研究了语音输入法，基于 fun-asr-nano，很有意思。

其实核心是速度和准确度。

3. 排版优化

必须修复：

• 移除行尾多余空格
• 移除连续空行（最多保留 2 行）
• 修复明显的排版错误

可选优化：

• 中英文之间添加空格（如 。Claude → 。 Claude）
• 中文标点后添加空格（如果后面是英文）

为什么：

• 必须修复的问题影响文档质量
• 可选优化是个人偏好，不要过度修改

4. 内容清理

检查项：

• 移除重复的空行
• 统一列表符号（使用 - 或 *，保持一致）
• 检查 YAML frontmatter 格式
• 验证图片链接是否有效

5. Emoji 图片引用处理

识别模式：

![😂](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg "乐极而泣脸")

处理规则：

• 如果 alt text 中包含 emoji（如 😂），直接用 emoji 替代整个图片引用
• 如果 alt text 中没有 emoji，删除整个图片引用
• Twitter/X 的 emoji 图片链接通常来自 abs-0.twimg.com/emoji/v2/svg/

处理示例：

原内容：![😂](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg "乐极而泣脸")
替换后：😂

原内容：![图像](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg)
替换后：（删除）

为什么：

• Emoji 图片在阅读时会占满一个很大的区域，影响阅读体验
• 直接使用 emoji 更简洁，不占用额外空间
• Twitter/X 的 emoji 链接是 SVG 格式，不适合在 markdown 中直接显示

用户偏好

格式化风格：

• 优先保证语法正确性
• 保持原文语义不变
• 段落落落要合理，便于阅读
• 不要过度修改原文

处理 clipping 文档时：

• 这些文档通常从 Twitter/X 等平台抓取
• 内容可能很密集，需要合理分段
• 保留原始信息，只优化格式

验证步骤

格式化完成后：

1. 重新运行 markdown-checker 确认错误已修复
2. 读取文件确认内容语义正确
3. 告诉用户修复了哪些问题
4. 询问是否需要进一步优化

特殊情况

不要自动修改：

• 代码块内容（除非用户明确要求）
• 特殊格式（如表格、数学公式）
• 用户自定义的格式

需要确认：

• 大量修改（超过 10 处）先告知用户
• 涉及内容重写的操作先询问
• 不确定是否应该修改的地方先询问