// Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions.
| name | markdownlint |
| description | Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions. |
| compatibility | Requires Node.js (npx). Works with any project containing markdown files. |
Validate markdown files follow formatting standards. Enables consistent documentation, readable diffs, and POSIX compliance.
markdownlint-cli is installed; installs if missing.--fix flag; reports errors
with specific rules and fixes.# Check if markdownlint is available
markdownlint --version 2>/dev/null
If not installed, install globally:
npm install -g markdownlint-cli
If installation fails (permissions, no npm), stop validation and report the issue with remediation steps:
sudo npm install -g ... or fix npm permissionsDo not silently skip validation.
.markdownlint.json in project root.markdownlint.yaml in project root.markdownlintrc in project rootmarkdownlint field in package.jsonreferences/markdownlint-config.json)If no project config exists, create a temporary .markdownlint.json using
the default config from the reference file before running validation.
1. Check markdownlint installation
├─ Installed → continue
└─ Missing → install, then continue (fail if install fails)
2. Detect project config
├─ Found → use it
└─ Not found → use default config from references/
3. Run validation
├─ Check only:
│ markdownlint <files-or-directories>
└─ Auto-fix:
markdownlint --fix <files-or-directories>
4. Report results
├─ Valid → confirm and proceed
└─ Invalid → show errors, suggest fixes, re-validate after correction
markdownlint README.md CHANGELOG.md docs/
markdownlint --fix README.md CHANGELOG.md docs/
Note: some issues (like MD001 heading-increment) cannot be auto-fixed and
require manual correction. Re-run without --fix after fixing to confirm
all issues resolved.
If markdownlint cannot be installed, report the error and provide remediation steps. Do not proceed with validation.
When validation fails, report each error with:
MD022/blanks-around-headings)Example:
Validation failed:
1. MD022/blanks-around-headings: heading not surrounded by blank lines
File: README.md:15
Fix: add blank lines before and after the heading
2. MD047/single-trailing-newline: file does not end with newline
File: CHANGELOG.md:89
Fix: add a single newline at end of file
After reporting errors, suggest running markdownlint --fix for
auto-fixable issues and provide manual fixes for the rest. Re-validate
after corrections.
See references/markdownlint-rules.md for the full rule reference, common
fixes, and auto-fixable rules.
Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
Validate commit messages against the Conventional Commits specification. Auto-detects and installs commitlint CLI if missing. Checks project config or falls back to sensible defaults. Use when validating commit messages, preparing PRs, or enforcing commit conventions.
Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked.
Generate a PR_MESSAGE.md file from session context using GitHub CLI. Detects related issues via branch-keyword search, writes a structured PR description with commit subject, summary, test plan, and changelog. Validates with commitlint and markdownlint. Use when preparing a pull request on GitHub.
Strategic roadmap management for GitHub repositories. Syncs ROADMAP.md with GitHub Issues and labels, bootstraps roadmap files from scratch, runs brainstorming sessions with boundary checking, and provides quick status summaries. Use when managing project planning, syncing roadmap state, or exploring feature ideas.
