How to use the Markdown Formatter agent skill (baoyu-format-markdown)

What the Markdown Formatter skill makes the agent do

The skill takes a plain text or markdown article and reorganizes its layout for easier reading. It adds a frontmatter block with title, summary and description, improves headings, bolds key points, turns parallel items into lists or tables, and fixes obvious typos.

The skill is designed not to add, delete or rewrite your content. Its stated core principle is to only adjust formatting and fix obvious typos. Typography fixes such as spacing between Chinese and English text and quote style are then applied by bundled TypeScript scripts.

• Adds frontmatter with title, summary and description
• Improves heading hierarchy and bolds key points
• Converts parallel items into lists or tables
• Fixes obvious typos
• Proposes several title and summary options when asked

Install the skill (ZIP download or Claude apps)

Download the baoyu-format-markdown ZIP from this page and unzip it into one of two locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills → upload

Check the requirements before you run it

The skill runs TypeScript scripts, so it needs a runtime. The source prefers Bun and accepts npx as an alternative. The scripts depend on npm packages listed in scripts/package.json, including unified, remark plugins, yaml and autocorrect-node. An optional EXTEND.md preferences file can be placed in a config directory, but none is required.

• Bun (preferred) or npx to run the scripts
• npm packages declared in scripts/package.json
• Optional EXTEND.md preferences file
• Network access is used by this skill

Trigger the skill with natural requests

You do not need a special command. Ask the agent in plain language, using phrases that match the skill's description. The skill is described as triggered by requests such as "format markdown", "beautify article", "add formatting", or a request to improve article layout.

Point the agent at the file you want formatted. The output is saved as a new file named with a -formatted suffix, for example {filename}-formatted.md.

• "Format markdown for draft.md"
• "Beautify article notes.md"
• "Add formatting to this post and improve the layout"
• "Improve the layout of my article and suggest title options"

Choose an option when the agent asks

If your file already contains markdown, the agent asks what to do. Optimize formatting runs the full workflow and writes a -formatted file. Keep original formatting preserves the existing structure and runs only the typography script. Typography fixes only edits the original file in place with no copy created.

For titles, the agent presents several candidates, usually two or three hook-style options and one or two straightforward ones, and marks the strongest first. You can type your own title instead. If you set auto_select or auto_select_title in EXTEND.md, the title choice is skipped and the best option is picked automatically.

• Optimize formatting: full workflow, output is a -formatted file
• Keep original formatting: typography script only, output is a copy
• Typography fixes only: edits the original file in place, no backup

Safety notes: scripts, network and in-place edits

The skill runs scripts and uses the network, so review the bundled files before use if your environment restricts script execution. The typography step executes scripts. Where running Bun, npx or npm packages is not allowed, do not use this skill.

The typography-only option changes your original file directly and does not keep a backup. Make a copy of anything you cannot afford to modify before choosing that option.

• Runs scripts: yes. Uses network: yes.
• Typography-only mode overwrites the original file with no backup.
• Not suitable where Bun, npx or npm packages are blocked.

Tips for better results

Give the skill a rough draft that already has the wording you want. Because it is restricted to formatting and typo fixes, it will not improve weak sentences. For Chinese, Japanese or mixed-language text, the typography step handles spacing and quote style, which is the main reason to use it for those languages.

Add an EXTEND.md file to store default preferences, for example to skip title selection once you trust the output.

• Use it for wording you have already settled
• Keep a copy of the original if you plan to use typography-only mode
• Store preferences in EXTEND.md to avoid repeated prompts