baoyu-format-markdown
Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks
Install / Use
npx skills add JimLiu/baoyu-skills --skill baoyu-format-markdownInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of baoyu-format-markdown
baoyu-format-markdown scores 96/100 on our quality scale, 59th of 1,155 Content & Media skills we index (top 6%).
Its SKILL.md is 14 KB long, well organised into 26 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.
With 26,131 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so baoyu-format-markdown is actively maintained.
- Our last check on 2026-11-15 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit โ read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk โ read a skill before letting an agent act on it.
baoyu-format-markdown compared with similar skills
All 4 of these similar skills score higher than baoyu-format-markdown; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| baoyu-format-markdown (this skill)by JimLiu | 96 | 26.1k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install baoyu-format-markdown?
- Run
npx skills add JimLiu/baoyu-skills --skill baoyu-format-markdown. The install tabs above show the steps for each supported agent. - Which AI agents does baoyu-format-markdown work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is baoyu-format-markdown safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is baoyu-format-markdown still maintained?
- The repository was last updated about 2 months ago, so baoyu-format-markdown is actively maintained.
Skill content
View source on GitHubname: 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):
- Prefer built-in user-input tools exposed by the current agent runtime โ e.g.,
AskUserQuestion,request_user_input,clarify,ask_user, or any equivalent. - 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.
- 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]
## Formatting Issues
- [list specific issues with location references]
## Typos Found
- [list any obvious typos with corrections, or "None found"]
Step 3: Check/Create Frontmatter, Title & Summary
Check for YAML frontmatter (--- block). Create if missing.
| Field | Processing |
|-------|------------|
| title | See Title Generation below |
| slug | Infer from file path or generate from title |
| summary | One-sentence concise summary (see Summary Generation below) |
| description | Longer descriptive summary (see Summary Generation below) |
| 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:
- 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)
- Generate 1-2 straightforward titles (descriptive or declarative, no formula โ clear and accurate)
- If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
- 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 |
| description | 2-3 sentences, ~100-200 chars | Richer context โ for article previews, newsletter blurbs |
Principles:
- Convey core value to the reader, not just the topic
- Use concrete details (numbers, outcomes, specific methods) over vague descriptions
summaryshould be punchy and self-contained;descriptioncan expand with supporting details- If frontmatter already has
summaryordescription, keep the existing one and only generate the missing field
Prohibited patterns:
- "This article introduces...", "This article explores..."
- Pure topic description without value proposition
- Repeating the title in different words
Once the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).
Step 4: Format Content
Apply formatting guided by the Step 2 analysis. The goal is making the content scannable and the key points impossible to miss.
Formatting toolkit:
| Element | When to use | Format |
|---------|-------------|--------|
| Headings | Natural topic boundaries, section breaks | ##, ### hierarchy |
| Bold | Key conclusions, important terms, core takeaways | **bold** |
| Unordered lists | Parallel items, feature lists, examples | - item |
| Ordered lists | Sequential steps, ranked items, procedures | 1. item |
| Tables | Comparisons, structured data, option matrices | Markdown table |
| Code | Commands, file paths, technical terms, variable names | `inline` or fenced blocks |
| 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
- Fix obvious typos (based on Step 2 findings)
Step 5: Save Formatted File
Save as {original-filename}-formatted.md
Backup existing file:
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
Run the formatting script on the output file:
${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]
Script Options:
| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| --quotes | -q | Replace ASCII quotes with fullwidth quotes "..." | false |
| --no-quotes | | Do not replace quotes | |
| --spacing | -s | Add CJK/English spacing via autocorrect | true |
| --no-spacing | | Do not add CJK/English spacing | |
| --emphasis | -e | Fix CJK emphasis punctuation issues | true |
| --no-emphasis | | Do not fix CJK
Truncated for display โ read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu โ one CLI, zero API fees.
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together ๅผๆบใ้็งไผๅ ใ่ชๆ็ฎก็็ฅ่ฏๅทฅไฝ็ฉบ้ด๏ผ่ฎฉไบบไธๆบ่ฝไฝๅจๆญคๅไฝ
x402
121.0kSet up Browser Use Cloud payments with x402 โ pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit โ see the Safety scan above for what the skill file itself contains.
