用途
baoyu-format-markdown 用于将纯文本或 Markdown 文件格式化为结构良好、对读者友好的 Markdown。目标是在不改变任何原始内容的前提下，帮助读者快速抓住要点、高亮信息与整体结构。
其核心原则是：只调整格式并修正明显错别字，绝不增加、删除或重写内容。
主要能力
- 检测内容类型：根据是否含 YAML frontmatter、
#/##/###标题、加粗/斜体/列表/代码块/引用等特征，判断为 Markdown 或纯文本。 - 内容分析（Step 2）：从读者视角提炼亮点与关键洞见、评估结构、识别读者重要信息与格式问题，并保存为
{original-filename}-analysis.md。 - frontmatter 处理（Step 3）：检查或创建 YAML frontmatter，字段包括
title、slug、summary、description、coverImage。 - 标题生成：根据内容生成 4–5 个候选标题（含钩子式与直白式），并通过用户输入工具让用户选择，或用自定义标题。
- 摘要生成：直接生成
summary（约 50–80 字，一句话）和description（约 100–200 字，2–3 句），无需用户选择。 - 内容格式化（Step 4）：使用标题、加粗、无序/有序列表、表格、代码、引用、分隔线等元素，使内容易扫读。
- 排版脚本（Step 6）：运行
scripts/main.ts，处理 CJK 强调标点、CJK/英文混排间距、引号替换和 frontmatter YAML 格式化。 - 完成报告（Step 7）：汇总文件、分析结果、已应用的变更和排版脚本执行情况。
使用方式
该技能的工作流分两个阶段：分析（理解内容）与格式化（应用格式）。由 Claude 执行内容分析与格式化（Step 1–5），随后运行脚本进行排版修正（Step 6）。
工作流步骤：
- 读取并检测内容类型。若检测为 Markdown，则通过 AskUserQuestion 询问用户选择：优化格式（推荐）、保留原格式，或仅做排版修正。
- 从读者视角分析内容，并保存分析文件。
- 检查/创建 frontmatter、标题与摘要。
- 依据分析结果格式化内容。
- 保存为
{original-filename}-formatted.md，若已存在则先备份。 - 执行排版脚本。
- 输出完成报告。
用户输入工具选择规则（优先级顺序）：优先使用当前 agent 运行时暴露的内置用户输入工具（如 AskUserQuestion、request_user_input、clarify、ask_user 或等价工具）；若无此类工具，则回退为编号纯文本消息，请用户回复所选编号/答案。若工具支持单次多问题，则合并为一次调用；若仅支持单问题，则按优先级逐个提问。
脚本运行方式：
- 脚本位于
scripts/子目录，{baseDir}为此 SKILL.md 所在目录路径。 - 解析
${BUN_X}运行时：若已安装 bun 则用bun；若可用 npx 则用npx -y bun；否则建议安装 bun。 - 运行命令：
${BUN_X} {baseDir}/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 强调问题 |
示例：
# 默认：启用间距与强调，禁用引号
${BUN_X} {baseDir}/scripts/main.ts article.md
# 启用所有功能，包括引号替换
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes
# 仅修复强调问题，跳过间距
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing
脚本执行内容（取决于选项）：
- 修复 CJK 强调/加粗标点问题（默认启用）
- 通过 autocorrect 添加 CJK/英文混排间距（默认启用）
- 将 ASCII 引号替换为全角引号（默认禁用）
- 格式化 frontmatter YAML（始终启用）
偏好设置（EXTEND.md）
按优先级顺序检查 EXTEND.md，第一个找到的生效：
| 优先级 | 路径 | 范围 |
|---|---|---|
| 1 | .baoyu-skills/baoyu-format-markdown/EXTEND.md |
项目 |
| 2 | ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md |
XDG |
| 3 | $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md |
用户主目录 |
若均未找到，则使用默认值，此技能无需首次设置。
EXTEND.md 支持的设置：
| 设置 | 取值 | 默认 | 说明 |
|---|---|---|---|
auto_select |
true/false | false | 跳过标题与摘要选择，自动选择最佳 |
auto_select_title |
true/false | false | 仅跳过标题选择 |
auto_select_summary |
true/false | false | 仅跳过摘要选择 |
| 其他 | — | — | 默认格式选项、排版偏好 |
适用场景
- 用户要求「格式化 markdown」或将纯文本整理为结构化 Markdown 时。
- 需要为文章补充 frontmatter、标题、摘要，同时保留原文字句不变的场景。
- 需要处理中日韩与英文混排间距、CJK 强调标点、全角引号替换等排版细节的场景。
限制
- 不增加、删除、重写内容，也不添加句子、解释或评论。
- 不添加带有主观评价的标题，仅使用中性描述性标题。
- 不过度格式化：并非每句都需要加粗，每段都需要标题。
- 标题公式细节参见
references/title-formulas.md，本次资料未提供该文件的具体内容。 - 脚本依赖 bun 或 npx 运行时；若均不可用，需先安装 bun。
- 摘要生成不使用用户选择，直接生成；标题生成在启用自动选择时跳过用户提示。