Package manager detection
Before any operation, detect which package manager the project uses:
- Check for lock files:
- pnpm-lock.yaml → use pnpm - yarn.lock → use yarn - package-lock.json → use npm - bun.lockb → use bun
- Check
packageManagerfield in package.json:"packageManager": "pnpm@8.0.0" - If no indicators, ask the user which package manager they prefer
Throughout this skill, commands use pnpm as examples. Replace with the detected package manager:
pnpm add -D→npm install --save-dev/yarn add -D/bun add -dpnpm run→npm run/yarn run/bun runpnpm install→npm install/yarn install/bun install
Operation selection guide
Identify what the user needs and read the appropriate reference file:
- Initial Setup → Read references/setup.md
- First time installation - Creating config files (.markdownlint.yaml,.markdownlintignore) - Adding npm scripts - Adding verification to AGENTS.md - Husky integration
- Modifying Rules → Read references/rules.md
- Enabling/disabling specific rules - Configuring rule options (heading-style, ul-style, etc.) - Understanding rule names and codes (MD###)
- Updating Ignore Patterns → Read references/ignoring.md
- Adding files/folders to.markdownlintignore - Gitignore-style pattern syntax - Verifying ignored files
- Fixing Violations → Read references/fixing.md
- Understanding error messages - Auto-fix with --fix flag - Common violations (MD009, MD012, MD022, MD040, etc.) - Manual fixes for specific errors
- Integration Management → Read references/integration.md
- Updating npm scripts - Modifying Husky hooks - CI/CD integration (GitHub Actions, GitLab CI) - VS Code extension setup
- Troubleshooting → Read references/troubleshooting.md
- Too many errors - Files not being checked - Hook failures - Module not found errors - Performance issues
Quick reference: Common commands
# Install
pnpm add -D markdownlint markdownlint-cli
# Run linting
pnpm run lint:markdown
# Auto-fix issues
markdownlint '**/*.md' --fix
# Lint specific file
markdownlint README.md
# Lint specific directory
markdownlint 'docs/**/*.md'Quick reference: Config file basics
.markdownlint.yaml in project root:
$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json
# Disable a rule
line-length: false
# Enable a rule
no-duplicate-heading: true
# Configure a rule
heading-style:
style: "atx".markdownlintignore in project root (gitignore syntax):
node_modules
dist/
build/
CHANGELOG.mdKey examples
Example 1: Basic setup
User: "Add markdownlint to my project"
Action: Read references/setup.md and follow Steps 1-9 for complete initial setup.
Example 2: Disable annoying rule
User: "Stop complaining about duplicate headings"
Action: Read references/rules.md → Removing rules section. Add no-duplicate-heading: false to .markdownlint.yaml.
Example 3: Fix many errors
User: "I have 50 markdown errors, fix them"
Action: Read references/fixing.md → Auto-fixing section. Run markdownlint '**/*.md' --fix, show diff, handle remaining errors.
Example 4: Ignore folder
User: "Don't lint the dist folder"
Action: Read references/ignoring.md. Add dist/ to .markdownlintignore.
Example 5: Add to CI
User: "Add markdown linting to GitHub Actions"
Action: Read references/integration.mdtions"
Action: Read references/integration.md → CI integration section. Create workflow file with pnpm setup and linting step.
Progressive workflow
For complex requests that span multiple operations:
- Start with the main operation - Read the primary reference file first
- Chain related operations - Read additional reference files as needed
- Verify each step - Run commands to confirm changes work
- Document what was done - Summarize changes for the user
Example: "Set up markdownlint with strict rules and CI"
- Read references/setup.md → complete initial setup
- Read references/rules.md → enable strict rules
- Read references/integration.md → add CI configuration
- Test all steps work together
When to use which reference
User mentions installation, setup, "add markdownlint": → references/setup.md
User mentions specific rules, MD codes, enabling/disabling: → references/rules.md
User mentions ignoring files, excluding folders: → references/ignoring.md
User has errors and wants to fix them: → references/fixing.md
User mentions npm scripts, husky, pre-commit, CI, GitHub Actions: → references/integration.md
User reports issues, things not working, errors: → references/troubleshooting.md
Default configuration philosophy
When setting up markdownlint, use this opinionated default configuration:
$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json
line-length: false # Modern editors handle wrappingRationale: Start permissive, enable rules gradually. The line-length rule is disabled by default because:
- Modern editors and viewers handle text wrapping automatically
- Fixed line length creates unnecessary friction in most projects
- Semantic issues are more valuable to catch than presentation issues
Only add more rules if user explicitly requests them or if the project needs stricter validation.