name: fixing-markdown
description: Validate and fix markdown formatting in files and folders. Use when the user wants to check formatting, validate markdown, fix lint errors, revisar formato, validar notas, comprobar markdown, arreglar markdown, limpiar markdown, or clean up files.
metadata:
skillport:
category: documentation
tags: [markdown, linting, formatting, prettier, markdownlint]

/fixing-markdown — Validate and Fix Markdown

Run markdownlint-cli2 + prettier to auto-fix markdown formatting issues.

Usage

/fixing-markdown <target>

Arguments:

• target (Required):
• File path: Single file (e.g., src/content/posts/2025-11-30-example.md)
• Folder path: All .md files recursively (e.g., src/content/posts)

No argument = show this usage.

Exclusions

NEVER modify files under .agent/ directory.

The .agent/ directory (git-ignored) contains Antigravity Kit 2.0—optional tooling for Antigravity IDE users. These files are managed externally and have their own formatting conventions. This skill must:

1. Reject any target that is .agent/ or starts with .agent/
2. Exclude .agent/ when target is . or root directory
3. Skip any file path containing /.agent/ or \.agent\

If user requests .agent/ formatting, respond:

⚠️ Skipping .agent/ — this directory is managed externally (Antigravity Kit).
Use Antigravity's own formatting tools if needed.

Prerequisites

Run initializing-environment first to ensure Node.js environment is ready.

Tools required in .claude/_tooling/node_modules/:

• markdownlint-cli2
• prettier

Commands

Single File

# Step 1: Fix structural issues
node .claude/_tooling/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs --config .claude/_tooling/.markdownlint-cli2.jsonc "path/to/file.md"

# Step 2: Format (table alignment, spacing)
node .claude/_tooling/node_modules/prettier/bin/prettier.cjs --config .claude/_tooling/.prettierrc --write "path/to/file.md"

Folder (recursive)

# Step 1: Fix structural issues (exclude .agent/)
node .claude/_tooling/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs --config .claude/_tooling/.markdownlint-cli2.jsonc "path/to/folder/**/*.md" "#.agent"

# Step 2: Format (exclude .agent/)
node .claude/_tooling/node_modules/prettier/bin/prettier.cjs --config .claude/_tooling/.prettierrc --write "path/to/folder/**/*.md" --ignore-pattern ".agent/**"

Root Directory (.)

When target is . or root, always exclude .agent/:

# Step 1: Fix structural issues
node .claude/_tooling/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs --config .claude/_tooling/.markdownlint-cli2.jsonc "**/*.md" "#.agent"

# Step 2: Format
node .claude/_tooling/node_modules/prettier/bin/prettier.cjs --config .claude/_tooling/.prettierrc --write "**/*.md" --ignore-pattern ".agent/**"

Examples

/fixing-markdown src/content/posts/2025-11-30-navaja-pdfly.md
→ Fixes and formats specific file

/fixing-markdown src/content/posts
→ Fixes and formats all .md files in posts/ recursively

/fixing-markdown .claude/skills
→ Fixes and formats all .md files in skills/ recursively

Output Format

Clean File

Fixing: src/content/posts/2025-11-30-navaja-pdfly.md

markdownlint: 0 errors
prettier: formatted

✅ Done

With Issues Fixed

Fixing: src/content/posts/2013-12-23-ip-fija-systemd.md

markdownlint: 2 errors fixed
prettier: formatted

✅ Done

Tools

Rules Enforced

markdownlint-cli2 (.claude/_tooling/.markdownlint-cli2.jsonc)

prettier (.claude/_tooling/.prettierrc)

• Table column alignment
• Consistent spacing
• Prose wrap preserved (no line breaking)

Behavior

1. Check argument: If no target provided, show usage and exit
2. Check exclusions: If target is .agent/ or inside it, show warning and exit
3. Run initializing-environment: Ensure Node.js environment is ready
4. Detect target type: file or folder
5. Run markdownlint-cli2: Fix structural issues (always exclude .agent/)
6. Run prettier: Format visual appearance (always exclude .agent/)
7. Report: Show results from both tools

Notes

• Config files: .claude/_tooling/.markdownlint-cli2.jsonc, .claude/_tooling/.prettierrc
• Requires: Node.js environment (handled by initializing-environment)