| name | format-markdown |
| description | Formats Markdown files consistently using project-native tooling first (repo scripts/config), then safe fallback formatters, and verifies the result with lint/check commands. Invoked when the user asks to format markdown, tidy docs, normalize README files, or fix markdown style drift.
|
| version | 1.0.0 |
| tags | ["documentation","markdown","formatting","linting"] |
| resources | ["rules.md"] |
| vendor_support | {"claude":"native","opencode":"native","copilot":"prompt-inject","codex":"prompt-inject","gemini":"prompt-inject"} |
Markdown Formatting Skill
Format Markdown files so they are structurally correct, readable, and consistent with
the repository's formatting/lint rules.
Step 1 - Determine Scope
- If the user provides files, format only those files.
- Otherwise format changed Markdown files in the current branch/diff.
- If no changed Markdown files exist, ask for explicit paths before proceeding.
Step 2 - Load Local Conventions
- Read project formatting/lint config when present (for example
.prettierrc*,
.markdownlint*, lint scripts in package.json, justfile, Makefile).
- Apply the repository's conventions over generic defaults.
- Read
rules.md and treat those rules as baseline behavior.
Step 3 - Apply Formatter (Preferred Order)
- Run repository-native formatting command if one exists (for example
just, make, or package script targeting markdown).
- If none exists, use a standard Markdown formatter available in the repo toolchain (for example Prettier).
- If Markdown linter auto-fix is configured, run it after formatting.
Do not introduce formatting tools that are not already part of the repository unless the user asks.
Step 4 - Validate
- Run markdown checks/lint commands available in the repository.
- If checks fail with auto-fixable findings, apply fixes and re-run checks.
- Report any remaining non-auto-fixable violations with file paths.
Step 5 - Safety Rules
- Preserve document meaning and code block content.
- Do not rewrite prose for style unless the user asks.
- Do not alter links/anchors in ways that break navigation.
- Keep frontmatter valid and unchanged semantically.
Step 6 - Output
Report:
- files formatted
- command(s) used
- verification command(s) and results
- any remaining manual fixes required
