mcpbeat

Markdown

aiskillstore/markdown

>

This is a copy. The original lives at comeonoliver/markdown.

11k tokens
context cost
the whole folder, loaded on every use
2
files
instructions only
0
copies elsewhere
how many repositories repackaged it
404
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/aiskillstore/marketplace --skill markdown

What comes with it

39 318 bytes besides the instruction
skill-report.json

The instruction itself

19 sections, as written by the author

Markdown Lint

Automated markdown validation and fixing using markdownlint-cli2.

Workflow Overview

1. Run auto-fix     → markdownlint-cli2 --fix <file>
2. Check remaining  → markdownlint-cli2 <file>
3. Fix manually     → str_replace for structural issues
4. Verify           → markdownlint-cli2 <file> (should show 0 errors)

Expected results: Auto-fix resolves 70-90% of issues. Remaining 3-5

issues require manual correction.

Basic Commands

# Auto-fix single file
markdownlint-cli2 --fix document.md

# Check file
markdownlint-cli2 document.md

# Multiple files
markdownlint-cli2 --fix file1.md file2.md

# All markdown in directory
markdownlint-cli2 --fix "**/*.md"

# With custom config
markdownlint-cli2 --config .markdownlint.json document.md

File Paths

# Uploaded files
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# Working directory
markdownlint-cli2 --fix /home/claude/document.md

# Output to user
cp /path/to/fixed.md /mnt/user-data/outputs/

Manual Fixes Required

Auto-fix cannot resolve these issues - they need Claude's judgment:

MD025 - Multiple H1 Headers

Why: Requires understanding document hierarchy

Fix: Convert extra H1s to appropriate level

# Main Title

# Second Title → Change to: ## Second Title

MD036 - Emphasis as Header

Why: Requires determining author intent

Fix: Replace bold/italic with proper header

**Section Title** → Change to: ## Section Title

MD013 - Line Too Long

Why: Requires deciding where to break content

Fix: Wrap at natural points (spaces, punctuation)

This is a very long line exceeding 80 characters that needs wrapping.
↓
This is a very long line exceeding 80 characters that needs
wrapping.

Exception: URLs typically exempt

MD041 - Missing First Line Header

Why: Requires structural decision

Fix: Add H1 at start or restructure

Execution Pattern

For Uploaded Files

# 1. Auto-fix
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# 2. Check remaining
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 3 error(s)"
# Lists specific errors like "MD025/single-title Multiple top-level headings"

# 3. Manual fixes (example)
str_replace "# Extra Title" → "## Extra Title"

# 4. Verify
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 0 error(s)"

# 5. Output
cp /mnt/user-data/uploads/document.md /mnt/user-data/outputs/

For New Content

create_file /home/claude/doc.md "content..."
markdownlint-cli2 --fix /home/claude/doc.md
markdownlint-cli2 /home/claude/doc.md
# Fix remaining issues if any
cp /home/claude/doc.md /mnt/user-data/outputs/

Configuration

Create .markdownlint.json to customize rules:

{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD033": false
}

Common adjustments:

  • "MD013": false - Disable line length checking
  • "MD013": { "line_length": 120 } - Increase limit to 120
  • "MD013": { "code_blocks": false } - Exclude code blocks
  • "MD033": false - Allow HTML
  • "MD041": false - Don't require first line header

Config file search order:

  • .markdownlint-cli2.jsonc
  • .markdownlint-cli2.yaml
  • .markdownlint.jsonc / .markdownlint.json
  • .markdownlint.yaml / .markdownlint.yml

Reporting to User

Provide clear summary of fixes:

✅ Markdown linting complete!

Initial: 18 errors
After auto-fix: 4 errors
Manual fixes:
  • MD025: Converted 2 H1 headers to H2
  • MD036: Replaced bold with proper header
  • MD013: Wrapped long line

Final: 0 errors

Error Count Interpretation

Before auto-fix:

  • 0-5: Minor issues
  • 6-15: Moderate issues
  • 16+: Significant issues

After auto-fix:

  • 0-2: Excellent
  • 3-5: Typical
  • 6+: Check if config needed

Common Fix Patterns

# Multiple H1s - analyze structure first
# If sections: convert to H2
str_replace "# Introduction" → "## Introduction"

# If subsections: convert to H3
str_replace "# Details" → "### Details"

# Emphasis as headers - determine appropriate level
str_replace "**Important**" → "## Important"
str_replace "_Note_" → "### Note"

# Long lines - break at natural points
# After conjunctions: and, but, or
# After punctuation: , . ;
# Preserve URLs on single line

Troubleshooting

Auto-fix not working:

# Check file exists
view /path/to/file.md

# Verify permissions
ls -l /path/to/file.md

# Use absolute path
markdownlint-cli2 --fix /full/path/to/file.md

Too many errors after auto-fix:

# Create relaxed config
echo '{"MD013": false, "MD041": false}' > .markdownlint.json
markdownlint-cli2 --config .markdownlint.json --fix file.md

Specific rule causing issues:

  • Disable in config: "MD013": false
  • Or adjust parameters: "MD013": { "line_length": 120 }

When NOT to Lint

Skip linting when:

  • Code examples intentionally violate rules
  • Embedded HTML/JSX required (disable MD033)
  • Generated docs with different conventions
  • Legacy docs where changes break references

Use custom config to disable problematic rules.

Quick Rule Reference

Most common rules Claude will encounter:

  • MD001 - Header increment by one level
  • MD004 - Consistent list markers
  • MD009 - No trailing spaces
  • MD010 - No hard tabs
  • MD012 - No multiple blank lines
  • MD013 - Line length (default: 80)
  • MD018 - Space after # in headers
  • MD022 - Blank lines around headers
  • MD025 - Single H1 only
  • MD031 - Blank lines around code
  • MD032 - Blank lines around lists
  • MD034 - Bare URLs in <>
  • MD036 - No emphasis as headers
  • MD040 - Language for code blocks

Full rule documentation: <https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md>

How to use it

Copy the folder

Take aiskillstore/markdown from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.