AI Skills
baoyu-format-markdown

baoyu-format-markdown

熱門

格式化純文字或 Markdown 檔案，補全或調整前置資料（frontmatter）、標題、摘要、小標題、粗體、清單與程式碼區塊。當使用者要求「格式化 markdown」、「美化文章」、「加入排版」或提升文章版面結構時使用。輸出結果至 {filename}-formatted.md。

2.2萬星標
2606分支
更新於 2026/6/18
獲取技能源代碼

相關技能

threat-model-analyst3.8萬nature-reader3萬content-research-writer6.8萬
SKILL.md
唯讀
名稱
baoyu-format-markdown
描述

格式化純文字或 Markdown 檔案，補全或調整前置資料（frontmatter）、標題、摘要、小標題、粗體、清單與程式碼區塊。當使用者要求「格式化 markdown」、「美化文章」、「加入排版」或提升文章版面結構時使用。輸出結果至 {filename}-formatted.md。

版本
1.57.0

Markdown Formatter

將純文字或 Markdown 轉換為結構清晰、易於閱讀的 Markdown 文件。目標是在不變更任何原始內容的前提下，協助讀者快速掌握核心重點、精華內容與整體架構。

核心原則：僅調整排版格式並修正明顯錯別字。切勿新增、刪除或重寫任何內容。

使用者輸入工具（User Input Tools）

當此 Skill 需要向使用者提問時，請遵循以下工具選擇規則（依優先順序）：

  1. 優先使用內建的使用者輸入工具：由目前 Agent 執行階段提供的工具 — 例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同等工具。
  2. 退路機制（Fallback）：若無此類工具，請發送帶有編號的純文字訊息，請使用者回覆各問題對應的編號或答案。
  3. 批次處理（Batching）：若工具支援單次呼叫提出多個問題，請將所有適用問題整合為單次呼叫；若僅支援單一問題，請依優先順序一次詢問一個。

下方內文提及的 AskUserQuestion 僅為範例 — 在其他 Agent 執行階段中請替換為相應的本地工具。

腳本目錄（Script Directory）

腳本位於 scripts/ 子目錄中。{baseDir} 為本 SKILL.md 所在的目錄路徑。解析 ${BUN_X} 執行階段：若已安裝 bun → bun；若可用 npx → npx -y bun；否則建議安裝 bun。請將 {baseDir} 與 ${BUN_X} 替換為實際數值。

腳本 用途
scripts/main.ts 帶有 CLI 選項的主入口點（使用 remark-cjk-friendly 處理中日韓強調標點）
scripts/quotes.ts 將 ASCII 引號替換為全形引號
scripts/autocorrect.ts 透過 autocorrect 自動補充中英文字元間的空格

偏好設定（EXTEND.md）

按優先順序檢查 EXTEND.md — 以最先找到的檔案為準：

優先權 路徑 作用域
1 .baoyu-skills/baoyu-format-markdown/EXTEND.md 專案（Project）
2 ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md XDG
3 $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md 使用者家目錄（User home）

若皆未找到，則使用預設值 — 本 Skill 首次使用無需進行初始設定。

EXTEND.md 支援的設定：

設定名稱 可選值 預設值 說明
auto_select true/false false 跳過標題與摘要選擇，自動挑選最佳選項
auto_select_title true/false false 僅跳過標題選擇
auto_select_summary true/false false 僅跳過摘要選擇
其他 — — 預設排版選項、字形與版面偏好

使用方式

工作流程分為兩個階段：分析（理解內容）與 格式化（套用排版）。Claude 負責執行內容分析與排版格式化（步驟 1 至 5），隨後執行腳本進行字形微調與排版修復（步驟 6）。

工作流程

步驟 1：讀取與偵測內容類型

讀取使用者指定的檔案，並偵測其內容類型：

特徵指標 分類
包含 --- YAML frontmatter Markdown
包含 #、##、### 等標題 Markdown
包含 **粗體**、*斜體*、清單、程式碼區塊、引用區塊 Markdown
不符合上述任何條件 純文字

若偵測為 Markdown，使用 AskUserQuestion 詢問使用者：

偵測到既有的 Markdown 格式。請問您希望如何處理？

1. 最佳化排版格式（推薦）
   - 分析內容，改進標題、粗體、清單以提升可讀性
   - 執行排版修復腳本（空格、強調標點修正）
   - 輸出：{filename}-formatted.md

2. 保留原始排版格式
   - 維持現有的 Markdown 架構
   - 僅執行排版修復腳本
   - 輸出：{filename}-formatted.md

3. 僅執行排版修復
   - 直接在原始檔案上執行排版修復腳本
   - 不建立副本，直接修改原檔

根據使用者的選擇：

  • 最佳化：繼續執行步驟 2（完整工作流程）
  • 保留原始格式：跳至步驟 5，複製檔案後執行步驟 6
  • 僅排版修復：跳至步驟 6，直接在原檔上執行

步驟 2：內容分析（讀者視角）

仔細閱讀全文。站在讀者的角度思考：什麼樣的排版能幫助他們快速理解並記住核心資訊？

產出一份涵蓋以下維度的分析報告：

2.1 亮點與核心洞察

  • 作者提出核心論點或結論
  • 令人驚喜的事實、數據或反直覺的觀點
  • 令人印象深刻的金句或精彩句式

2.2 架構評估

  • 內容是否有清晰的邏輯流向？其脈絡為何？
  • 是否存在自然的分段邊界但缺乏小標題？
  • 是否有大段沉悶的文字可以透過視覺分隔來改善？

2.3 對讀者至關重要的資訊

  • 可落實的建議或核心收穫
  • 定義、重要概念的說明
  • 埋沒在段落中的清單或列舉項
  • 若改用表格呈現會更清晰的對比或比較

2.4 排版問題

  • 缺少標題層級或層級不一致
  • 單一段落混合了多個主題
  • 並列項目以散文段落撰寫而非清單
  • 程式碼、命令或技術術語未標註為程式碼格式
  • 明顯的錯別字或排版錯誤

將分析結果儲存至檔案：{original-filename}-analysis.md

此分析檔案將作為步驟 3 的藍圖。請使用以下格式：

# 內容分析：{filename}

## 亮點與核心洞察
- [列出分析發現]

## 架構評估
- 當前脈絡：[說明]
- 建議小標題：[列出候選標題及其簡要理由]

## 對讀者重要的資訊
- [列出可行動項目、核心概念、段落中的清單、潛在表格]

## 排版問題
- [列出具體問題與對應位置]

## 發現的錯別字
- [列出明顯的錯別字與修正建議，若無則填「無」]

步驟 3：檢查/建立 Frontmatter、標題與摘要

檢查是否存在 YAML frontmatter（--- 區塊）。若缺失則建立。

欄位 處理方式
title 請參閱下方的標題生成
slug 從檔案路徑推斷或根據標題生成
summary 單句精練摘要（請參閱下方的摘要生成）
description 較詳細的描述性摘要（請參閱下方的摘要生成）
coverImage 檢查同目錄下是否存在 imgs/cover.png；若存在，使用相對路徑
標題生成

無論原本是否已有標題，除非已設定 auto_select_title，否則皆需執行標題最佳化流程。

準備工作 — 閱讀全文並擷取：

  • 核心論點（一句話：「這篇文章在講什麼？」）
  • 最具影響力的觀點或結論
  • 讀者的痛點或引發好奇心的誘因
  • 最令人印象深刻的比喻或金句

生成候選標題：使用 references/title-formulas.md 中的公式：

  1. 根據文章內容、語氣與架構，挑選 2-3 個最適切的吸睛公式（hook formulas）（請參閱參考檔案中的「何時選擇各公式」）
  2. 生成 1-2 個平實直白標題（描述性或陳述性，不使用公式 — 清晰且準確）
  3. 若使用者指定了特定方向（例如「製造懸念感」），優先考慮該方向
  4. 總計生成 4-5 個候選標題

透過 AskUserQuestion 呈現：

請選擇一個標題：

1. [吸睛標題 A] — (推薦) [公式名稱]
2. [吸睛標題 B] — [公式名稱]
3. [吸睛標題 C] — [公式名稱]
4. [直白標題 D] — 平實直白
5. [直白標題 E] — 平實直白

請輸入數字，或直接輸入自訂標題：

將吸引力最強的標題放在第一位並標註 (推薦)。有關原則與禁止模式，請參閱 references/title-formulas.md。

若文章第一行是 H1 標題，請將其擷取至 frontmatter 中，並從本文中移除。若 frontmatter 已有 title，請將其作為參考背景，但仍需生成新的候選標題 — 原有標題可能不夠吸引人。

跳過行為：若設定 auto_select: true 或 auto_select_title: true，則跳過使用者提示，直接採用最佳候選標題。

摘要生成

直接生成兩種版本的摘要（無需使用者選擇），皆儲存於 frontmatter 中：

欄位 長度 用途
summary 1 句話，約 50-80 字 精練的賣點/引子 — 用於 Feed 訂閱、社群分享、SEO meta
description 2-3 句話，約 100-200 字 豐富的背景資訊 — 用於文章預覽、電子報簡介

生成原則：

  • 向讀者傳達核心價值，而非僅僅描述主題
  • 使用具體細節（數字、成果、具體方法）替代模糊的描述
  • summary 應精練且語意完整；description 可進一步展開補充支援細節
  • 若 frontmatter 已有 summary 或 description，請保留既存欄位，僅生成缺失的欄位

禁止模式：

  • 「本文介紹了……」、「這篇文章探討了……」
  • 僅描述主題而未展現價值主張
  • 用不同詞彙重複標題內容

一旦標題移入 frontmatter 後，本文內不應再包含 H1 標題（避免重複）。

步驟 4：格式化內容

在步驟 2 分析報告的指引下套用排版格式。目標是讓內容易於快速掃視，並使核心重點一目了然。

排版工具箱：

元素 使用時機 格式
標題 自然的主題邊界、章節分隔 ##、### 層級
粗體 核心結論、重要術語、關鍵收穫 **粗體**
無序清單 並列項目、功能清單、範例 - 項目
有序清單 步驟順序、排名項目、操作流程 1. 項目
表格 比較對照、結構化資料、選項矩陣 Markdown 表格
程式碼 命令、檔案路徑、技術術語、變數名稱 `行內程式碼` 或程式碼區塊
引用區塊 金句、重要警告、引述文字 > 引用
分隔線 重大主題轉折 ---

排版原則 — 切勿（NOT）做的事：

  • 切勿新增任何句子、解釋或評註
  • 切勿刪除或縮減任何內容
  • 切勿重述或修改作者的原話
  • 切勿新增帶有主觀評論的標題（例如「驚人的發現」 — 請使用中立客觀的描述性標題）
  • 切勿過度排版：並非每句話都需要加粗，也非每個段落都需要小標題

排版原則 — 務必（TO）做的事：

  • 完整保留作者的語氣、風格與每一個字
  • 加粗核心結論與關鍵收穫 — 即讀者會劃重點的句子
  • 僅在結構明確時，將段落中的並列項目提取為清單
  • 在主題確實轉折處新增標題 — 優先使用生動、具體的標題，而非泛泛之詞（例如以「3 天搞定 vs 傳統方案」替代「方案對比」）
  • 對於埋沒在散文段落中的比較或結構化資料，使用表格呈現
  • 對於金句、令人印象深刻的表述或重要警告，使用引用區塊
  • 修正明顯的錯別字（基於步驟 2 的發現）

步驟 5：儲存格式化後的檔案

儲存為 {original-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

步驟 6：執行排版修復腳本

在輸出檔案上執行排版格式化腳本：

${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]

腳本選項：

選項 簡寫 說明 預設值
--quotes -q 將 ASCII 引號替換為全形引號 "..." false
--no-quotes 不替換引號
--spacing -s 透過 autocorrect 自動補充中英文字元間的空格 true
--no-spacing 不自動補充空格
--emphasis -e 修正中日韓（CJK）強調標點符號問題 true
--no-emphasis 不修正中日韓強調標點

<!-- truncated for translation batch; full body continues in source -->