baoyu-skills/skills/baoyu-format-markdown/SKILL.md

name, description

name	description
baoyu-format-markdown	Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or improve article layout. Outputs to {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
scripts/cjk-emphasis.ts	Fix CJK emphasis/bold punctuation issues
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 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	Use > blockquote
Separators	Use --- where appropriate

Formatting principles:

• Preserve original content and viewpoints
• Add formatting only, do not modify text
• Formatting serves readability
• Avoid over-formatting

Step 6: Save Formatted File

Save as {original-filename}-formatted.md

Examples:

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

Backup existing file:

If {filename}-formatted.md already exists, backup before overwriting:

# Check if formatted file exists
if [ -f "{filename}-formatted.md" ]; then
  # Backup with timestamp
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

Example:

• final-formatted.md exists → backup to final-formatted.backup-20260128-143052.md

Step 7: Execute Text Formatting Script

After saving, must run the formatting script:

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

Script Options:

Option	Short	Description	Default
--quotes	-q	Replace ASCII quotes with fullwidth quotes "..."	false
--no-quotes		Do not replace quotes
--spacing	-s	Add CJK/English spacing via autocorrect	true
--no-spacing		Do not add CJK/English spacing
--emphasis	-e	Fix CJK emphasis punctuation issues	true
--no-emphasis		Do not fix CJK emphasis issues
--help	-h	Show help message

Examples:

# Default: spacing + emphasis enabled, quotes disabled
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# Enable all features including quote replacement
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

# Disable all processing except frontmatter formatting
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis

Script performs (based on options):

1. Fix CJK emphasis/bold punctuation issues (default: enabled)
2. Add CJK/English mixed text spacing via autocorrect (default: enabled)
3. Replace ASCII quotes "..." with fullwidth quotes "..." (default: disabled)
4. Format frontmatter YAML (always enabled)

Step 8: Display Results

**Formatting complete**

File: posts/2026/01/09/example/final-formatted.md

Changes:
- Added title: [title content]
- Added X bold markers
- Added X lists
- Added X code blocks

Formatting Example

Before:

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.

After:

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

Notes

• Preserve original writing style and tone
• Specify correct language for code blocks (e.g., python, javascript)
• Maintain CJK/English spacing standards
• Do not add content not present in original

Extension Support

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.