MD Formatter

该 Skill 提供 md-formatter，通过本地 Python 脚本对 Markdown 文件做规范化：统一标题从一级开始且不跳级、把下划线式标题转为井号式、规范链接写法、清理尾随空格、统一粗斜体符号，并保证标题与代码块前后空行；同时附带标题语法参考文档以及检查、运行、验证、迭代的工作流程。

terrycarter1985

热度 11.85

最近更新 2026-07-22 10:16:15

分类：效率依赖：代码执行 / 读写文件应用场景：文件转换 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add md-formatter

Metadata

name: md-formatter
description: Format and lint markdown files for consistency and readability. Use when Codex needs to normalize markdown documents, fix heading levels, standardize link formats, add missing alt text, or apply consistent formatting conventions across markdown files. Triggers include "format markdown", "clean up this md", "lint markdown", "normalize headings in this file".

MD Formatter

Format and lint markdown files with consistent conventions.

Quick Start

Run the formatter script on a file:

python3 scripts/format_md.py <file.md>

The script performs:

Heading normalization: Promote headings to start at #, ensure no level skips (e.g., # → ###), convert ===/--- underlined headings to # style.
Link formatting: Convert <https://url> to [url](https://url) when appropriate, standardize bare URLs.
Trailing whitespace: Remove it.
Bold/italic consistency: Prefer **bold** over __bold__, *italic* over _italic_.
Empty lines: Ensure one blank line before and after headings and code blocks.

Workflow

1. Inspect the file

Read the markdown file to understand its current state.

2. Run the formatter script

Execute scripts/format_md.py with the target path. Check the diff output.

3. Verify formatting

Read the formatted file to confirm changes are correct and no content was accidentally altered.

4. Iterate if needed

For complex documents, manually review or adjust formatting the script doesn't cover.

References

See references/heading-syntax.md for markdown heading specification details.