Use baoyu-format-markdown when an article is complete but headings, lists, emphasis, or mixed Chinese-English typography need work. Its stated scope is formatting and obvious typo fixes rather than adding arguments. Content rewriting should be requested as a separate task.
Install and invoke
Run this in your project terminal to install only this skill for Claude Code:
npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown -a claude-code
Node.js and npx must be available. For Codex, replace -a claude-code with -a codex. In the agent conversation, explicitly ask it to use baoyu-format-markdown and supply your material. The installation command belongs in the terminal, not in your content brief.
State whether structure and titles may change
For existing Markdown, the workflow distinguishes structural optimization, preservation, and typography-only processing. Initially request a separate copy and identify fixed headings, quotations, or code.
Example brief:
Use baoyu-format-markdown on article.md and create a separate copy.
You may adjust heading hierarchy, lists, and selective emphasis, but do not add, remove, or rewrite body content.
Keep the title, code, and quotations unchanged. List any obvious typo corrections.
Fix mixed-language spacing and CJK emphasis; do not replace ASCII quotation marks.
The full process analyzes the article into article-analysis.md and produces article-formatted.md. It can fill title, slug, and summary frontmatter. An initial H1 may move into metadata, so compare both metadata and body before concluding that the title disappeared.
Distinguish structure from script processing
The agent organizes headings, paragraphs, and lists using the content. A subsequent script repairs typography. Spacing and emphasis fixes are enabled by default; ASCII quote replacement is off. --no-spacing and --no-emphasis disable those respective changes. The agent must locate the script inside the actual installation instead of executing a placeholder path.
Scripts use Bun, with npx -y bun available as the documented fallback. A missing command after installation may require PATH troubleshooting. Typography-only processing can operate in place, unlike the full copy-producing workflow, so requesting a separate file removes ambiguity.
Compare facts, figures, quotations, and code afterward. Ensure paragraphs were not removed for brevity and emphasis has not spread to every sentence. Render the result in the target editor and inspect nested lists, tables, code blocks, and emphasis near CJK punctuation. The analysis file is a working record; the formatted file is normally the deliverable. Use that approved version as input for any later HTML conversion.
Turn interview notes into a publishable draft
The input may mix long unheaded passages, numbered instructions, verbatim quotations, and code. Identify which sentences are a participant's exact words and which are instructions. Ask the agent to improve headings and lists without rewriting quotations as the author's claims. After article-analysis.md is produced, check that it classified the material correctly; then confirm that the formatted version preserves the sequence of every procedure. Line breaks and emphasis can improve reading, but cannot silently correct unverified facts.
If the draft already has a deliberate heading structure, choose the option that preserves it and writes a typography-only copy. If you select the in-place typography path, copy the original first. Review a diff for code blocks, numbers, quotes, and links, then render the output so frontmatter is not displayed as body text. If the first heading moves into metadata, make sure the downstream page still renders a title before treating the missing body H1 as a deletion.
Format just before producing the publishable version
Run it on near-final Markdown rather than mixing factual edits with layout cleanup. In Just Jason’s article workflow, baoyu-format-markdown follows writing and image compression and precedes WeChat HTML conversion, a useful point for a final pass over headings, summary, and emphasis. After formatting, diff the factual text, links, code blocks, and image paths, then preview in the target renderer. If your site uses extended syntax such as MkDocs Material, separately inspect equations, tables, and admonitions; a general formatter may not know the target renderer’s rules.
A MkDocs Material writer adapted Baoyu’s formatting workflow for 300–400-line notes with many equations and tables. Their derivative uses an AST to identify structures, adds whitespace required by that renderer, and preserves the text. This does not mean the original skill contains those rules. For equations or extended blocks, preview a small sample in the destination site before deciding whether a specialized post-processing step is needed.