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 等平台抓取
内容可能很密集，需要合理分段
保留原始信息，只优化格式

验证步骤

格式化完成后：

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

特殊情况

不要自动修改：

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

需要确认：

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

markdown-formatter