fix-markdown
Fix lint, formatting, and prose issues in markdown files using Prettier and Vale. Use when the user or agent needs to fix lint, formatting, and prose issues in markdown files.
Best use case
fix-markdown is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Fix lint, formatting, and prose issues in markdown files using Prettier and Vale. Use when the user or agent needs to fix lint, formatting, and prose issues in markdown files.
Teams using fix-markdown should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/fix-markdown/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How fix-markdown Compares
| Feature / Agent | fix-markdown | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Fix lint, formatting, and prose issues in markdown files using Prettier and Vale. Use when the user or agent needs to fix lint, formatting, and prose issues in markdown files.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Agent protocol: Fix markdown file **`GOAL`**: use prettier and vale to fix lint, formatting, and prose issues in markdown files. **`WHEN`**: use when the user or agent needs to fix lint, formatting, or improve prose in markdown files. **`NOTE`**: strictly follow E-Prime directive (avoid "`to be`" verbs) when writing or correcting prose. ## References The following reference files serve as strict guidelines when updating prose. Locate the reference files in the `references` folder. - **`references/e-prime-directive.md`**: _The E-Prime Communication Protocol defining the rules for avoiding `to be` verbs._ ## Primary directives ### Formatting and linting sequence - **Format first & last**: Always run prettier before analysis and after edits - **E-Prime compliance**: Strictly follow `references/e-prime-directive.md` when writing/correcting prose - **Vale cycle**: Run vale iteratively (lint → fix → verify) until no issues remain - **Research complex issues**: Use search tools or Perplexity for unfamiliar lint problems ### Tool commands - Format: `prettier --write <file_path>` - Sync rules: `vale sync` - Lint: `vale --no-wrap --output=JSON <file_path>` ### Vale fixing guidelines - **Path wrapping**: Wrap filenames, `URIs`, `URLs`, and paths in backticks - **Context awareness**: Check line numbers - issues may appear as `substrings` in technical terms - **False positives**: Wrap acronyms, names, and proper nouns in backticks - **Headings**: Use sentence case (capitalize first character only) - **Passive voice**: Follow E-Prime directive to remove "`to be`" verbs - **Follow hints**: Use Vale's issue links when needed ## Efficiency directives - Batch operations on file groups, avoid individual file processing - Use parallel execution when possible - Target only requested files - Reduce token usage in all operations ## Task management For complex tasks: use `todo` system to break down, plan, and optimize workflow. ## Workflow - Run `vale sync` to update lint rules - Run `prettier --write` for baseline formatting - Study file and apply Vale path directives (wrap all paths/filenames in backticks) - Iteratively run `vale`, fix issues, and verify until no issues remain - Run `prettier --write` for final formatting - **`DONE`** ## Output **Files modified:** - Target markdown files - Formatted and lint-free **Status communication:** - Reports number of issues fixed - Confirms Vale shows zero remaining issues - Lists file paths processed
Related Skills
obsidian-markdown
Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes.
markdowntown-atlas-scan
Atlas Simulator scan flow and next-step guidance for markdowntown. Use when working on folder scanning, tool detection, cwd handling, results panels, or scan-to-workbench CTAs.
markdown-mdx
Advanced Markdown and MDX processing for technical documentation. Parse, validate, lint, and transform Markdown content with support for MDX components, front matter, and remark/rehype plugins.
Markdown Export
Specialist in generating comprehensive Markdown reports of the knowledge model.
markdown-drafts
Use markdown formatting when drafting content intended for external systems (GitHub issues/PRs, Jira tickets, wiki pages, design docs, etc.) so formatting is preserved when the user copies it. Load this skill before producing any draft the user will paste elsewhere.
markdown-consolidator
Intelligent consolidation and synthesis of multiple markdown files with overlapping content and different update dates. Use when: (1) Multiple AI-generated markdown files need merging, (2) Knowledge bases have fragmented or duplicate content, (3) Documentation requires recency-aware synthesis, (4) Supporting documents need re-synthesis after AI task completion, (5) Project documentation has semantic overlap across files, (6) Periodic knowledge base maintenance and deduplication is needed.
markdown-exporter
Markdown exporter for transform Markdown text to DOCX, PPTX, XLSX, PDF, PNG, HTML, MD, CSV, JSON, JSONL, XML, Mermaid files, and extract code blocks in Markdown to Python, Bash,JS and etc files. Also known as the md_exporter skill.
adding-markdown-highlighted-comments
Use when adding responses to markdown documents with user-highlighted comments, encountering markup errors, or unsure about mark tag placement - ensures proper model-highlight formatting with required attributes and correct placement within markdown elements
bgo
Automates the complete Blender build-go workflow, from building and packaging your extension/add-on to removing old versions, installing, enabling, and launching Blender for quick testing and iteration.
reviewing-documentation
Use when reviewing documentation quality, auditing README or CLAUDE.md files, or standardizing AI instruction files.
review-docs
Review documentation (README.md and CLAUDE.md) for quality, completeness, and consistency. Use when asked to review docs, check documentation, validate README files, or audit CLAUDE.md coverage.
review-changelog
Review and complete new changelog entries after automated PR creation. Use when there's a new changelog PR with entries that have placeholder URLs or empty fields that need review. Triggers on phrases like "review changelog", "complete changelog entries", "fix changelog PR", or when user mentions a PR with changelog updates.