name: baoyu-format-markdown description: 格式化纯文本或Markdown文件，添加前端数据、标题、摘要、标题、粗体、列表和代码块。当用户要求“格式化Markdown”、“美化文章”、“添加格式化”或改善文章布局时使用。输出到{filename}-formatted.md。

Markdown 格式化器

将纯文本或Markdown文件转换为结构良好的Markdown，具有适当的前端数据、格式化和排版。

脚本目录

脚本在 scripts/ 子目录中。将 ${SKILL_DIR} 替换为此 SKILL.md 的目录路径。

脚本	用途
`scripts/main.ts`	主要入口点，带有CLI选项（使用remark-cjk-friendly进行CJK强调）
`scripts/quotes.ts`	将ASCII引号替换为全角引号
`scripts/autocorrect.ts`	通过autocorrect添加CJK/英文间距

偏好设置 (EXTEND.md)

使用Bash检查EXTEND.md存在性（优先级顺序）：

# 首先检查项目级别
test -f .baoyu-skills/baoyu-format-markdown/EXTEND.md && echo "project"

# 然后用户级别（跨平台：$HOME 在 macOS/Linux/WSL 上工作）
test -f "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ .baoyu-skills/baoyu-format-markdown/EXTEND.md │ 项目目录 │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md │ 用户主目录 │ └──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 结果 │ 操作 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 找到 │ 读取、解析、应用设置 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 未找到 │ 使用默认值 │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持：默认格式化选项 | 摘要长度偏好

使用方式

Claude执行内容分析和格式化（步骤1-6），然后运行脚本进行排版修复（步骤7）。

工作流程

步骤1：读取源文件

读取用户指定的Markdown或纯文本文件。

步骤1.5：检测内容类型并确认

内容类型检测：

指标	分类
有 `---` YAML前端数据	Markdown
有 `#`, `##`, `###` 标题	Markdown
有 `粗体`, `斜体`	Markdown
有 `-` 或 `1.` 列表	Markdown
有 ``` 代码块	Markdown
有 `>` 块引用	Markdown
以上皆无	纯文本

决策流程：

┌─────────────────┬────────────────────────────────────────────────┐ │ 内容类型 │ 操作 │ ├─────────────────┼────────────────────────────────────────────────┤ │ 纯文本 │ 继续到步骤2（格式化为Markdown） │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ 使用AskUserQuestion确认优化 │ └─────────────────┴────────────────────────────────────────────────┘

如果检测到Markdown，询问用户：

检测到现有的Markdown格式。您想做什么？

1. 优化格式化（推荐）
   - 添加/改进前端数据、标题、粗体、列表
   - 运行排版脚本（间距、强调修复）
   - 输出：{filename}-formatted.md

2. 保留原始格式
   - 保留现有Markdown结构
   - 运行排版脚本（间距、强调修复）
   - 输出：{filename}-formatted.md

3. 仅排版修复
   - 在原始文件上直接运行排版脚本
   - 不创建副本，直接修改原始文件

基于用户选择：

优化：继续步骤2-8（完整工作流程）
保留原始：跳过步骤2-5，复制文件 → 步骤6-8（在副本上运行脚本）
仅排版：跳过步骤2-6，直接在原始文件上运行步骤7

步骤2：分析内容结构

识别：

现有标题（H1 #）
段落分隔
适合粗体的关键词
可转换为列表的并行内容
代码片段
引用

步骤3：检查/创建前端数据

检查YAML前端数据（--- 块）。如果缺失则创建。

元字段处理：

字段	处理
`title`	见步骤4
`slug`	从文件路径推断（例如 `posts/2026/01/10/vibe-coding/` → `vibe-coding`）或从标题生成
`summary`	生成吸引人的摘要（100-150字符）
`coverImage`	检查同一目录中是否存在 `imgs/cover.png`；如果存在，使用相对路径（也接受 `featureImage`）

步骤4：标题处理

逻辑：

如果前端数据已有 title → 使用它，正文中无H1
如果第一行是H1 → 提取到前端数据 title，从正文中移除H1
如果两者都不存在 → 生成候选标题

标题生成流程：

基于内容生成3个候选标题
使用 AskUserQuestion 工具：

选择一个标题：

1. [标题 A]（推荐）
2. [标题 B]
3. [标题 C]

如果几秒内无选择，使用推荐的（选项1）

标题原则：

简洁，最多20字符
捕捉核心信息
吸引人，激发阅读兴趣
准确，避免点击诱饵

重要： 一旦标题在前端数据中，正文不应有H1（避免重复）

步骤5：格式化处理

格式化规则：

元素	格式
标题	使用 `#`, `##`, `###` 层级
关键点	使用 `粗体`
并行项目	转换为 `-` 无序或 `1.` 有序列表
代码/命令	使用 `内联` 或 ```块```
引用/名言	使用 `>` 块引用
分隔符	在适当处使用 `---`

格式化原则：

保留原始内容和观点
仅添加格式化，不修改文本
格式化服务于可读性
避免过度格式化

步骤6：保存格式化文件

保存为 {original-filename}-formatted.md

示例：

final.md → final-formatted.md
draft-v1.md → draft-v1-formatted.md

如果用户选择“保留原始格式”（从步骤1.5）：

复制原始文件到 {filename}-formatted.md，无修改
继续步骤7仅进行排版修复

备份现有文件：

如果 {filename}-formatted.md 已存在，覆盖前备份：

# 检查格式化文件是否存在
if [ -f "{filename}-formatted.md" ]; then
  # 用时间戳备份
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

示例：

final-formatted.md 存在 → 备份到 final-formatted.backup-20260128-143052.md

步骤7：执行文本格式化脚本

保存后，必须运行格式化脚本：

npx -y bun ${SKILL_DIR}/scripts/main.ts {output-file-path} [options]

脚本选项：

选项	短选项	描述	默认
`--quotes`	`-q`	将ASCII引号替换为全角引号 `"..."`	false
`--no-quotes`		不替换引号
`--spacing`	`-s`	通过autocorrect添加CJK/英文间距	true
`--no-spacing`		不添加CJK/英文间距
`--emphasis`	`-e`	修复CJK强调标点问题	true
`--no-emphasis`		不修复CJK强调问题
`--help`	`-h`	显示帮助消息

示例：

# 默认：间距 + 强调启用，引号禁用
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# 启用所有功能包括引号替换
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

# 仅修复强调问题，跳过间距
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

# 禁用所有处理，除了前端数据格式化
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis

脚本执行（基于选项）：

修复CJK强调/粗体标点问题（默认：启用）
通过autocorrect添加CJK/英文混合文本间距（默认：启用）
将ASCII引号 "..." 替换为全角引号 "..."（默认：禁用）
格式化前端数据YAML（始终启用）

步骤8：显示结果

**格式化完成**

文件：posts/2026/01/09/example/final-formatted.md

更改：
- 添加标题：[标题内容]
- 添加 X 个粗体标记
- 添加 X 个列表
- 添加 X 个代码块

格式化示例

之前：

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

之后：

---
title: 三个核心优势
slug: three-core-advantages
summary: 发现推动现代项目成功的三个关键好处。
---

This is plain text.

**主要优势：**
- 效率提升
- 成本降低
- 体验优化

使用 `npm install` 安装依赖。

备注

保留原始写作风格和语调
指定代码块的正确语言（例如 python, javascript）
保持CJK/英文间距标准
不添加原始内容中未出现的内容

扩展支持

通过EXTEND.md自定义配置。参见 偏好设置 部分了解路径和支持选项。