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.
Installs just this skill. Get the whole plugin for auto-invocation.
โก How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/baoyu-format-markdown
๐๏ธ Context preview
The summary Claude sees to decide when to auto-load this skill.
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.
๐ Stats
Stars24,058
Forks2,686
LanguageTypeScript
LicenseMIT
๐ฆ Ships with baoyu-skills
</> SKILL.md
baoyu-format-markdown.SKILL.md
---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:
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:
| `coverImage` | Check if `imgs/cover.png` exists in same directory; if so, use relative path |
#### Title Generation
Whether or not a title already exists, run the title optimization flow unless `auto_select_title` is set.
**Preparation** โ read the full text and extract:
- Core argument (one sentence: "what is this article about?")
- Most impactful opinion or conclusion
- Reader pain point or curiosity trigger
- Most memorable metaphor or golden quote
**Generate candidates** using formulas from `references/title-formulas.md`:
1. 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)
2. Generate **1-2 straightforward titles** (descriptive or declarative, no formula โ clear and accurate)
3. If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
4. Total: **4-5 candidates**
Present via `AskUserQuestion`:
```
Pick a title:
1. [Hook title A] โ (recommended) [formula name]
2. [Hook title B] โ [formula name]
3. [Hook title C] โ [formula name]
4. [Straightforward title D] โ straightforward
5. [Straightforward title E] โ straightforward
Enter number, or type a custom title:
```
Put the strongest hook first and mark it `(recommended)`. See `references/title-formulas.md` for principles and prohibited patterns.
If 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.
**Skip behavior**: If `auto_select: true` or `auto_select_title: true`, skip the user prompt and use the top candidate directly.
#### Summary Generation
Generate two versions directly (no user selection), both stored in frontmatter:
| Field | Length | Purpose |
|-------|--------|---------|
| `summary` | 1 sentence, ~50-80 chars | Concise hook โ for feeds, social sharing, SEO meta |
| Blockquotes | Notable quotes, important warnings, cited text | `> quote` |
| Separators | Major topic transitions | `---` |
**Formatting principles โ what NOT to do:**
- Do NOT add sentences, explanations, or commentary
- Do NOT delete or shorten any content
- Do NOT rephrase or rewrite the author's words
- Do NOT add headings that editorialize (e.g., "Amazing Discovery" โ use neutral descriptive headings)
- Do NOT over-format: not every sentence needs bold, not every paragraph needs a heading
**Formatting principles โ what TO do:**
- Preserve the author's voice, tone, and every word
- **Bold key conclusions and core takeaways** โ the sentences a reader would highlight
- Extract parallel items from prose into lists only when the structure is clearly there
- Add headings where the topic genuinely shifts โ prefer vivid, specific headings over generic ones (e.g., "3 ๅคฉๆๅฎ vs ไผ ็ปๆนๆก" over "ๆนๆกๅฏนๆฏ")
- Use tables for comparisons or structured data buried in prose
- Use blockquotes for golden quotes, memorable statements, or important warnings
