/baoyu-format-markdown

name: baoyu-format-markdown
description: 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.
version: 1.57.0
metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-format-markdown
    requires:
      anyBins:
        - bun
        - npx

Markdown Formatter

Transforms plain text or markdown into well-structured, reader-friendly markdown. The goal is to help readers quickly grasp key points, highlights, and structure — without changing any original content.

**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent. 2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question. 3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.

Script Directory

Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.

| 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)

Check EXTEND.md in priority order — the first one found wins:

| Priority | Path | Scope | |----------|------|-------| | 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 |

If none found, use defaults — no first-time setup required for this skill.

**EXTEND.md supports**:

| Setting | Values | Default | Description | |---------|--------|---------|-------------| | `auto_select` | `true`/`false` | `false` | Skip both title and summary selection, auto-pick best | | `auto_select_title` | `true`/`false` | `false` | Skip title selection only | | `auto_select_summary` | `true`/`false` | `false` | Skip summary selection only | | Other | — | — | Default formatting options, typography preferences |

Usage

The workflow has two phases: **Analyze** (understand the content) then **Format** (apply formatting). Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).

Workflow

Step 1: Read & Detect Content Type

Read the user-specified file, then detect content type:

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

**If Markdown detected, use `AskUserQuestion` to ask:**

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

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists for readability
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script only
   - 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 (full workflow)
• **Keep original**: Skip to Step 5, copy file then run Step 6
• **Typography only**: Skip to Step 6, run on original file directly

Step 2: Analyze Content (Reader's Perspective)

Read the entire content carefully. Think from a reader's perspective: what would help them quickly understand and remember the key information?

Produce an analysis covering these dimensions:

**2.1 Highlights & Key Insights**

• Core arguments or conclusions the author makes
• Surprising facts, data points, or counterintuitive claims
• Memorable quotes or well-phrased sentences (golden quotes)

**2.2 Structure Assessment**

• Does the content have a clear logical flow? What is it?
• Are there natural section boundaries that lack headings?
• Are there long walls of text that could benefit from visual breaks?

**2.3 Reader-Important Information**

• Actionable advice or takeaways
• Definitions, explanations of key concepts
• Lists or enumerations buried in prose
• Comparisons or contrasts that would be clearer as tables

**2.4 Formatting Issues**

• Missing or inconsistent heading hierarchy
• Paragraphs that mix multiple topics
• Parallel items written as prose instead of lists
• Code, commands, or technical terms not marked as code
• Obvious typos or formatting errors

**Save analysis to file**: `{original-filename}-analysis.md`

The analysis file serves as the blueprint for Step 3. Use this format:

# Content Analysis: {filename}

## Highlights & Key Insights
- [list findings]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [list heading candidates with brief rationale]

## Reader-Important Information
- [list actionable items, key concepts, buried lists, potential tables]

## For