/baoyu-format-markdown

name: baoyu-format-markdown
description: 技术写作员与内容创作者在处理纯文本或 Markdown 稿件时，若需优化文章结构、添加 frontmatter 或自动修正中英文排版间距，使用此技能可一键生成专业美观的 {filename}-formatted.md 文件，让文档排版更完美。

Markdown Formatter

Transforms plain text or markdown files into well-structured markdown with proper frontmatter, formatting, and typography.

Script Directory

Scripts in `scripts/` subdirectory. Replace `${SKILL_DIR}` with this SKILL.md's directory path.

| Script | Purpose | |--------|---------| | `scripts/main.ts` | Main entry point with CLI options (uses remark-cjk-friendly for CJK emphasis) | | `scripts/quotes.ts` | Replace ASCII quotes with fullwidth quotes | | `scripts/autocorrect.ts` | Add CJK/English spacing via autocorrect |

Preferences (EXTEND.md)

Use Bash to check EXTEND.md existence (priority order):

# Check project-level first
test -f .baoyu-skills/baoyu-format-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ .baoyu-skills/baoyu-format-markdown/EXTEND.md │ Project directory │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md │ User home │ └──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ Result │ Action │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Found │ Read, parse, apply settings │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Not found │ Use defaults │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Default formatting options | Summary length preferences

Usage

Claude performs content analysis and formatting (Steps 1-6), then runs the script for typography fixes (Step 7).

Workflow

Step 1: Read Source File

Read the user-specified markdown or plain text file.

Step 1.5: Detect Content Type & Confirm

**Content Type Detection:**

| Indicator | Classification | |-----------|----------------| | Has `---` YAML frontmatter | Markdown | | Has `#`, `##`, `###` headings | Markdown | | Has `**bold**`, `*italic*` | Markdown | | Has `- ` or `1. ` lists | Markdown | | Has ``` code blocks | Markdown | | Has `> ` blockquotes | Markdown | | None of above | Plain text |

**Decision Flow:**

┌─────────────────┬────────────────────────────────────────────────┐ │ Content Type │ Action │ ├─────────────────┼────────────────────────────────────────────────┤ │ Plain text │ Proceed to Step 2 (format to markdown) │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ Use AskUserQuestion to confirm optimization │ └─────────────────┴────────────────────────────────────────────────┘

**If Markdown detected, ask user:**

Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Add/improve frontmatter, headings, bold, lists
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly

**Based on user choice:**

• **Optimize**: Continue to Step 2-8 (full workflow)
• **Keep original**: Skip Steps 2-5, copy file → Step 6-8 (run script on copy)
• **Typography only**: Skip Steps 2-6, run Step 7 on original file directly

Step 2: Analyze Content Structure

Identify:

• Existing title (H1 `#`)
• Paragraph separations
• Keywords suitable for **bold**
• Parallel content convertible to lists
• Code snippets
• Quotations

Step 3: Check/Create Frontmatter

Check for YAML frontmatter (`---` block). Create if missing.

**Meta field handling:**

| Field | Processing | |-------|------------| | `title` | See Step 4 | | `slug` | Infer from file path (e.g., `posts/2026/01/10/vibe-coding/` → `vibe-coding`) or generate from title | | `summary` | Generate engaging summary (100-150 characters) | | `featureImage` | Check if `imgs/cover.png` exists in same directory; if so, use relative path |

Step 4: Title Handling

**Logic:** 1. If frontmatter already has `title` → use it, no H1 in body 2. If first line is H1 → extract to frontmatter `title`, remove H1 from body 3. If neither exists → generate candidate titles

**Title generation flow:**

1. Generate 3 candidate titles based on content 2. Use `AskUserQuestion` tool:

Select a title:

1. [Title A] (Recommended)
2. [Title B]
3. [Title C]

3. If no selection within a few seconds, use recommended (option 1)

**Title principles:**

• Concise, max 20 characters
• Captures core message
• Engaging, sparks reading interest
• Accurate, avoids clickbait

**Important:** Once title is in frontmatter, body should NOT have H1 (avoid duplication)

Step 5: Format Processing

**Formatting rules:**

| Element | Format | |---------|--------| | Titles | Use `#`, `##`, `###` hierarchy | | Key points | Use `**bold**` | | Parallel items | Convert to `-` unordered or `1.` ordered lists | | Code/commands | Use `` `inline` `` or ` ```block``` ` | | Quotes/sayings