BA

baoyu-format-markdown

Automatically formats markdown and plain text for readability. Adds structure without altering your original content.

Install

mkdir -p .claude/skills/baoyu-format-markdown && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/1103" && unzip -o skill.zip -d .claude/skills/baoyu-format-markdown && rm skill.zip

Installs to .claude/skills/baoyu-format-markdown

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

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.
255 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Beginner

Key capabilities

  • →Adds frontmatter and structured headers to markdown
  • →Normalizes list structures and bold styling
  • →Applies CJK spacing standards for readability
  • →Replaces ASCII quotes with fullwidth counterparts
  • →Generates formatted output to new file destinations

How it works

Runs remark-based scripts to process document styling, spacing, and metadata without modifying the core content.

Inputs & outputs

You give it
Raw markdown or plain text
You get back
A prettified, formatted markdown file

When to use baoyu-format-markdown

  • →Format raw documentation
  • →Beautify a blog draft
  • →Add structured headings to plain text
  • →Clean up markdown syntax

About this skill

Markdown Formatter

Make plain text or markdown scannable so readers grasp key points and structure fast.

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

{baseDir} = this SKILL.md's directory. ${BUN_X} = bun if installed; else npx -y bun if npx available; else suggest installing bun. Replace {baseDir} and ${BUN_X} with actual values.

ScriptPurpose
scripts/main.tsMain entry point with CLI options (uses remark-cjk-friendly for CJK emphasis)
scripts/quotes.tsReplace ASCII quotes with fullwidth quotes
scripts/autocorrect.tsAdd CJK/English spacing via autocorrect

Preferences (EXTEND.md)

First one found wins:

PriorityPathScope
1.baoyu-skills/baoyu-format-markdown/EXTEND.mdProject
2${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.mdXDG
3$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.mdUser home

None found → use defaults (no first-time setup for this skill).

SettingValuesDefaultDescription
auto_selecttrue/falsefalseSkip both title and summary selection, auto-pick best
auto_select_titletrue/falsefalseSkip title selection only
auto_select_summarytrue/falsefalseSkip summary selection only
Other——Default formatting options, typography preferences

Workflow

The agent analyzes and formats (Steps 1-5), then runs the typography script (Step 6).

Step 1: Read & Detect Content Type

Read the file. It is Markdown if it has --- YAML frontmatter, #/##/### headings, or **bold**/*italic*/lists/code blocks/blockquotes; otherwise plain text.

If Markdown, 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
  • Optimize → Step 2 (full workflow)
  • Keep original → skip to Step 5 (copy file), then Step 6
  • Typography only → skip to Step 6 on the original file

Step 2: Analyze Content (Reader's Perspective)

Read the whole text and ask what would help a reader quickly understand and remember it. Save {original-filename}-analysis.md — the blueprint for Step 4:

# Content Analysis: {filename}

## Highlights & Key Insights
- [core arguments/conclusions, surprising facts or data, counterintuitive claims, golden quotes]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [heading candidates with brief rationale; unheaded section boundaries; walls of text needing breaks]

## Reader-Important Information
- [actionable takeaways, key definitions, lists buried in prose, comparisons that should be tables]

## Formatting Issues
- [specific issues with location: heading hierarchy, mixed-topic paragraphs, parallel items as prose, unmarked code/commands/terms]

## Typos Found
- [obvious typos with corrections, or "None found"]

Step 3: Check/Create Frontmatter, Title & Summary

Create a YAML frontmatter block if missing.

FieldProcessing
titleSee Title Generation
slugInfer from file path or generate from title
summaryOne-sentence summary (see Summary Generation)
descriptionLonger descriptive summary (see Summary Generation)
coverImageIf imgs/cover.png exists in the same directory, use its relative path

Title Generation

Run this flow even if a title exists, unless auto_select_title is set.

  1. Extract: core argument (one sentence), most impactful opinion/conclusion, reader pain point or curiosity trigger, most memorable metaphor or golden quote
  2. Using references/title-formulas.md: pick the 2-3 best-matching hook formulas ("When to pick each formula"), plus 1-2 straightforward titles (descriptive or declarative, no formula). If the user gave a direction (e.g., "make it suspenseful"), prioritize it. Total 4-5 candidates, obeying the reference's principles and prohibited patterns
  3. Ask, strongest hook first and marked (recommended):
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:
  • First line is an H1 → move it to frontmatter and remove it from the body. An existing frontmatter title is context only; still generate fresh candidates.
  • auto_select: true or auto_select_title: true → skip the prompt, use the top candidate.
  • Once the title is in frontmatter, the body must NOT contain an H1.

Summary Generation

Generate both directly (no user selection):

FieldLengthPurpose
summary1 sentence, ~50-80 charsConcise hook — feeds, social sharing, SEO meta
description2-3 sentences, ~100-200 charsRicher context — article previews, newsletter blurbs
  • Convey core value to the reader, not just the topic; prefer concrete details (numbers, outcomes, specific methods)
  • summary punchy and self-contained; description may add supporting details
  • Keep an existing summary/description; only generate the missing one
  • Prohibited: "This article introduces...", "This article explores..."; pure topic description without value; restating the title

Step 4: Format Content

Guided by the Step 2 analysis, make content scannable and key points impossible to miss, using headings (##/###), bold, ordered/unordered lists, tables, inline/fenced code (commands, paths, technical terms), blockquotes, and --- for major transitions.

Don't:

  • Add sentences, explanations, or commentary
  • Delete or shorten any content
  • Rephrase or rewrite the author's words
  • Add editorializing headings (e.g., "Amazing Discovery" — use neutral descriptive ones)
  • Over-format: not every sentence needs bold, not every paragraph a heading

Do:

  • Preserve the author's voice, tone, and every word
  • Bold key conclusions and core takeaways — what a reader would highlight
  • Turn prose into lists only when the parallel structure is clearly there
  • Add headings where the topic genuinely shifts — vivid and specific over generic (e.g., "3 天搞定 vs 传统方案" over "方案对比")
  • Tables for comparisons or structured data buried in prose
  • Blockquotes for golden quotes, memorable statements, or important warnings
  • Fix obvious typos (from Step 2)
  • Specify the language on code blocks (e.g., python, javascript)
  • Maintain CJK/English spacing standards

Step 5: Save Formatted File

Save as {original-filename}-formatted.md, backing up any existing one:

if [ -f "{filename}-formatted.md" ]; then
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

Step 6: Execute Typography Script

${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]
OptionShortDescriptionDefault
--quotes-qReplace ASCII quotes with fullwidth quotes "..."false
--no-quotesDo not replace quotes
--spacing-sAdd CJK/English spacing via autocorrecttrue
--no-spacingDo not add CJK/English spacing
--emphasis-eFix CJK emphasis punctuation issuestrue
--no-emphasisDo not fix CJK emphasis issues

Frontmatter YAML is always formatted. Examples: main.ts article.md (defaults), --quotes (add quote replacement), --no-spacing (emphasis only).

Step 7: Completion Report

Report actual changes; omit categories with none:

**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}-formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Code markers added: X
- Blockquotes added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Typography Script:**
- CJK spacing: [applied/skipped]
- Emphasis fixes: [applied/skipped]
- Quote replacement: [applied/skipped]

Extension Support

Custom configurations via EXTEND.md — see Preferences above.

When not to use it

  • →For obfuscated or minified code files
  • →When existing document structure must remain strictly untouched

Prerequisites

bunnpx

Limitations

  • →Cannot improve the quality of original prose
  • →Might break deeply nested or non-standard markdown syntax
  • →Formatting logic is restricted by defined script capabilities

How it compares

It uses CJK-specific typography rules that standard formatters typically ignore.

Compared to similar skills

baoyu-format-markdown side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
baoyu-format-markdown (this skill)77moReviewBeginner
ml-paper-writing489moReviewAdvanced
docs-review1011moNo flagsBeginner
claude-md-improver2110moReviewBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

baoyu-xhs-images

JimLiu

Generates Xiaohongshu (Little Red Book) infographic series with 10 visual styles and 8 layouts. Breaks content into 1-10 cartoon-style images optimized for XHS engagement. Use when user mentions "小红书图片", "XHS images", "RedNote infographics", "小红书种草", or wants social media infographics for Chinese platforms.

2051

baoyu-article-illustrator

JimLiu

Analyzes article structure, identifies positions requiring visual aids, generates illustrations with Type × Style two-dimension approach. Use when user asks to "illustrate article", "add images", "generate images for article", or "为文章配图".

1848

baoyu-comic

JimLiu

Knowledge comic creator supporting multiple art styles and tones. Creates original educational comics with detailed panel layouts and sequential image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial comic", or "Logicomix-style comic".

1329

baoyu-infographic

JimLiu

Generates professional infographics with 20 layout types and 17 visual styles. Analyzes content, recommends layout×style combinations, and generates publication-ready infographics. Use when user asks to create "infographic", "信息图", "visual summary", or "可视化".

1230

baoyu-compress-image

JimLiu

Compresses images to WebP (default) or PNG with automatic tool selection. Use when user asks to "compress image", "optimize image", "convert to webp", or reduce image file size.

1129

baoyu-cover-image

JimLiu

Generates article cover images with 5 dimensions (type, palette, rendering, text, mood) combining 9 color palettes and 6 rendering styles. Supports cinematic (2.35:1), widescreen (16:9), and square (1:1) aspects. Use when user asks to "generate cover image", "create article cover", or "make cover".

1020

You might also like

ml-paper-writing

davila7

Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.

4897

docs-review

metabase

Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.

1085

claude-md-improver

anthropics

Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".

2167

write-docs

tldraw

Writing SDK documentation for tldraw. Use when creating new documentation articles, updating existing docs, or when documentation writing guidance is needed. Applies to docs in apps/docs/content/.

665

update-docs

vercel

This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.

2543

wiki-architect

microsoft

Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or understand a project's architecture at a high level.

1144

Search skills

Search the agent skills registry