baoyu-format-markdown

$npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown
SKILL.md

Baoyu Format Markdown

Transforms plain text or markdown files into well-structured markdown with proper frontmatter, formatting, and typography. Scripts in `scripts/` subdirectory. Replace `${SKILL_DIR}` with this SKILL.md's directory path. Script

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:
LHOST_PH_1
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:
LHOST_PH_2
  1. 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
If user chose "Keep original formatting" (from Step 1.5):
  • Copy original file to {filename}-formatted.md without modifications
  • Proceed to Step 7 for typography fixes only
Backup existing file:
If {filename}-formatted.md already exists, backup before overwriting:
LHOST_PH_3
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:
LHOST_PH_4
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

LHOST_PH_5

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:
LHOST_PH_6

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.