1---
2name: baoyu-format-markdown
3description: 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.
4version: 1.57.0
5metadata:
6  openclaw:
7    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-format-markdown
8    requires:
9      anyBins:
10        - bun
11        - npx
12---
13 
14# Markdown Formatter
15 
16Transforms 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.
17 
18**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.
19 
20## User Input Tools
21 
22When this skill prompts the user, follow this tool-selection rule (priority order):
23 
241. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
252. **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.
263. **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.
27 
28Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
29 
30## Script Directory
31 
32Scripts 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.
33 
34| Script | Purpose |
35|--------|---------|
36| `scripts/main.ts` | Main entry point with CLI options (uses remark-cjk-friendly for CJK emphasis) |
37| `scripts/quotes.ts` | Replace ASCII quotes with fullwidth quotes |
38| `scripts/autocorrect.ts` | Add CJK/English spacing via autocorrect |
39 
40## Preferences (EXTEND.md)
41 
42Check EXTEND.md in priority order — the first one found wins:
43 
44| Priority | Path | Scope |
45|----------|------|-------|
46| 1 | `.baoyu-skills/baoyu-format-markdown/EXTEND.md` | Project |
47| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md` | XDG |
48| 3 | `$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md` | User home |
49 
50If none found, use defaults — no first-time setup required for this skill.
51 
52**EXTEND.md supports**:
53 
54| Setting | Values | Default | Description |
55|---------|--------|---------|-------------|
56| `auto_select` | `true`/`false` | `false` | Skip both title and summary selection, auto-pick best |
57| `auto_select_title` | `true`/`false` | `false` | Skip title selection only |
58| `auto_select_summary` | `true`/`false` | `false` | Skip summary selection only |
59| Other | — | — | Default formatting options, typography preferences |
60 
61## Usage
62 
63The 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).
64 
65## Workflow
66 
67### Step 1: Read & Detect Content Type
68 
69Read the user-specified file, then detect content type:
70 
71| Indicator | Classification |
72|-----------|----------------|
73| Has `---` YAML frontmatter | Markdown |
74| Has `#`, `##`, `###` headings | Markdown |
75| Has `**bold**`, `*italic*`, lists, code blocks, blockquotes | Markdown |
76| None of above | Plain text |
77 
78**If Markdown detected, use `AskUserQuestion` to ask:**
79 
80```
81Detected existing markdown formatting. What would you like to do?
82 
831. Optimize formatting (Recommended)
84   - Analyze content, improve headings, bold, lists for readability
85   - Run typography script (spacing, emphasis fixes)
86   - Output: {filename}-formatted.md
87 
882. Keep original formatting
89   - Preserve existing markdown structure
90   - Run typography script only
91   - Output: {filename}-formatted.md
92 
933. Typography fixes only
94   - Run typography script on original file in-place
95   - No copy created, modifies original file directly
96```
97 
98**Based on user choice:**
99- **Optimize**: Continue to Step 2 (full workflow)
100- **Keep original**: Skip to Step 5, copy file then run Step 6
101- **Typography only**: Skip to Step 6, run on original file directly
102 
103### Step 2: Analyze Content (Reader's Perspective)
104 
105Read the entire content carefully. Think from a reader's perspective: what would help them quickly understand and remember the key information?
106 
107Produce an analysis covering these dimensions:
108 
109**2.1 Highlights & Key Insights**
110- Core arguments or conclusions the author makes
111- Surprising facts, data points, or counterintuitive claims
112- Memorable quotes or well-phrased sentences (golden quotes)
113 
114**2.2 Structure Assessment**
115- Does the content have a clear logical flow? What is it?
116- Are there natural section boundaries that lack headings?
117- Are there long walls of text that could benefit from visual breaks?
118 
119**2.3 Reader-Important Information**
120- Actionable advice or takeaways
121- Definitions, explanations of key concepts
122- Lists or enumerations buried in prose
123- Comparisons or contrasts that would be clearer as tables
124 
125**2.4 Formatting Issues**
126- Missing or inconsistent heading hierarchy
127- Paragraphs that mix multiple topics
128- Parallel items written as prose instead of lists
129- Code, commands, or technical terms not marked as code
130- Obvious typos or formatting errors
131 
132**Save analysis to file**: `{original-filename}-analysis.md`
133 
134The analysis file serves as the blueprint for Step 3. Use this format:
135 
136```markdown
137# Content Analysis: {filename}
138 
139## Highlights & Key Insights
140- [list findings]
141 
142## Structure Assessment
143- Current flow: [describe]
144- Suggested sections: [list heading candidates with brief rationale]
145 
146## Reader-Important Information
147- [list actionable items, key concepts, buried lists, potential tables]
148 
149## Formatting Issues
150- [list specific issues with location references]
151 
152## Typos Found
153- [list any obvious typos with corrections, or "None found"]
154```
155 
156### Step 3: Check/Create Frontmatter, Title & Summary
157 
158Check for YAML frontmatter (`---` block). Create if missing.
159 
160| Field | Processing |
161|-------|------------|
162| `title` | See **Title Generation** below |
163| `slug` | Infer from file path or generate from title |
164| `summary` | One-sentence concise summary (see **Summary Generation** below) |
165| `description` | Longer descriptive summary (see **Summary Generation** below) |
166| `coverImage` | Check if `imgs/cover.png` exists in same directory; if so, use relative path |
167 
168#### Title Generation
169 
170Whether or not a title already exists, run the title optimization flow unless `auto_select_title` is set.
171 
172**Preparation** — read the full text and extract:
173- Core argument (one sentence: "what is this article about?")
174- Most impactful opinion or conclusion
175- Reader pain point or curiosity trigger
176- Most memorable metaphor or golden quote
177 
178**Generate candidates** using formulas from `references/title-formulas.md`:
179 
1801. Select the **2-3 best-matching hook formulas** based on the article's content, tone, and structure (see "When to pick each formula" in the reference)
1812. Generate **1-2 straightforward titles** (descriptive or declarative, no formula — clear and accurate)
1823. If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
1834. Total: **4-5 candidates**
184 
185Present via `AskUserQuestion`:
186 
187```
188Pick a title:
189 
1901. [Hook title A] — (recommended) [formula name]
1912. [Hook title B] — [formula name]
1923. [Hook title C] — [formula name]
1934. [Straightforward title D] — straightforward
1945. [Straightforward title E] — straightforward
195 
196Enter number, or type a custom title:
197```
198 
199Put the strongest hook first and mark it `(recommended)`. See `references/title-formulas.md` for principles and prohibited patterns.
200 
201If the first line is an H1, extract it to frontmatter and remove it from the body. If frontmatter already has a `title`, include it as context but still generate fresh candidates — the existing title may be weak.
202 
203**Skip behavior**: If `auto_select: true` or `auto_select_title: true`, skip the user prompt and use the top candidate directly.
204 
205#### Summary Generation
206 
207Generate two versions directly (no user selection), both stored in frontmatter:
208 
209| Field | Length | Purpose |
210|-------|--------|---------|
211| `summary` | 1 sentence, ~50-80 chars | Concise hook — for feeds, social sharing, SEO meta |
212| `description` | 2-3 sentences, ~100-200 chars | Richer context — for article previews, newsletter blurbs |
213 
214**Principles**:
215 
216- Convey **core value** to the reader, not just the topic
217- Use concrete details (numbers, outcomes, specific methods) over vague descriptions
218- `summary` should be punchy and self-contained; `description` can expand with supporting details
219- If frontmatter already has `summary` or `description`, keep the existing one and only generate the missing field
220 
221**Prohibited patterns**:
222 
223- "This article introduces...", "This article explores..."
224- Pure topic description without value proposition
225- Repeating the title in different words
226 
227Once the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).
228 
229### Step 4: Format Content
230 
231Apply formatting guided by the Step 2 analysis. The goal is making the content scannable and the key points impossible to miss.
232 
233**Formatting toolkit:**
234 
235| Element | When to use | Format |
236|---------|-------------|--------|
237| Headings | Natural topic boundaries, section breaks | `##`, `###` hierarchy |
238| Bold | Key conclusions, important terms, core takeaways | `**bold**` |
239| Unordered lists | Parallel items, feature lists, examples | `- item` |
240| Ordered lists | Sequential steps, ranked items, procedures | `1. item` |
241| Tables | Comparisons, structured data, option matrices | Markdown table |
242| Code | Commands, file paths, technical terms, variable names | `` `inline` `` or fenced blocks |
243| Blockquotes | Notable quotes, important warnings, cited text | `> quote` |
244| Separators | Major topic transitions | `---` |
245 
246**Formatting principles — what NOT to do:**
247- Do NOT add sentences, explanations, or commentary
248- Do NOT delete or shorten any content
249- Do NOT rephrase or rewrite the author's words
250- Do NOT add headings that editorialize (e.g., "Amazing Discovery" — use neutral descriptive headings)
251- Do NOT over-format: not every sentence needs bold, not every paragraph needs a heading
252 
253**Formatting principles — what TO do:**
254- Preserve the author's voice, tone, and every word
255- **Bold key conclusions and core takeaways** — the sentences a reader would highlight
256- Extract parallel items from prose into lists only when the structure is clearly there
257- Add headings where the topic genuinely shifts — prefer vivid, specific headings over generic ones (e.g., "3 天搞定 vs 传统方案" over "方案对比")
258- Use tables for comparisons or structured data buried in prose
259- Use blockquotes for golden quotes, memorable statements, or important warnings
260- Fix obvious typos (based on Step 2 findings)
261 
262### Step 5: Save Formatted File
263 
264Save as `{original-filename}-formatted.md`
265 
266**Backup existing file:**
267 
268```bash
269if [ -f "{filename}-formatted.md" ]; then
270  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
271fi
272```
273 
274### Step 6: Execute Typography Script
275 
276Run the formatting script on the output file:
277 
278```bash
279${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]
280```
281 
282**Script Options:**
283 
284| Option | Short | Description | Default |
285|--------|-------|-------------|---------|
286| `--quotes` | `-q` | Replace ASCII quotes with fullwidth quotes `"..."` | false |
287| `--no-quotes` | | Do not replace quotes | |
288| `--spacing` | `-s` | Add CJK/English spacing via autocorrect | true |
289| `--no-spacing` | | Do not add CJK/English spacing | |
290| `--emphasis` | `-e` | Fix CJK emphasis punctuation issues | true |
291| `--no-emphasis` | | Do not fix CJK emphasis issues | |
292 
293**Examples:**
294 
295```bash
296# Default: spacing + emphasis enabled, quotes disabled
297${BUN_X} {baseDir}/scripts/main.ts article.md
298 
299# Enable all features including quote replacement
300${BUN_X} {baseDir}/scripts/main.ts article.md --quotes
301 
302# Only fix emphasis issues, skip spacing
303${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing
304```
305 
306**Script performs (based on options):**
3071. Fix CJK emphasis/bold punctuation issues (default: enabled)
3082. Add CJK/English mixed text spacing via autocorrect (default: enabled)
3093. Replace ASCII quotes with fullwidth quotes (default: disabled)
3104. Format frontmatter YAML (always enabled)
311 
312### Step 7: Completion Report
313 
314Display a report summarizing all changes made:
315 
316```
317**Formatting Complete**
318 
319**Files:**
320- Analysis: {filename}-analysis.md
321- Formatted: {filename}-formatted.md
322 
323**Content Analysis Summary:**
324- Highlights found: X key insights
325- Golden quotes: X memorable sentences
326- Formatting issues fixed: X items
327 
328**Changes Applied:**
329- Frontmatter: [added/updated] (title, slug, summary)
330- Headings added: X (##: N, ###: N)
331- Bold markers added: X
332- Lists created: X (from prose → list conversion)
333- Tables created: X
334- Code markers added: X
335- Blockquotes added: X
336- Typos fixed: X [list each: "original" → "corrected"]
337 
338**Typography Script:**
339- CJK spacing: [applied/skipped]
340- Emphasis fixes: [applied/skipped]
341- Quote replacement: [applied/skipped]
342```
343 
344Adjust the report to reflect actual changes — omit categories where no changes were made.
345 
346## Notes
347 
348- Preserve original writing style and tone
349- Specify correct language for code blocks (e.g., `python`, `javascript`)
350- Maintain CJK/English spacing standards
351- The analysis file is a working document — it helps maintain consistency between what was identified and what was formatted
352 
353## Extension Support
354 
355Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.
356