Fixing Markdown

/palas-basic:fixing-markdown — Validate and Fix Markdown

IMPORTANT: Before starting execution, inform the user: "ESTOY EJECUTANDO EL SKILL /palas-basic:fixing-markdown"

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

CRITICAL: Execution Requirements

ALWAYS run ALL tools in sequence, regardless of exit codes.

1. markdownlint-cli2 may exit with code 1 if it finds errors it cannot auto-fix. This is expected behavior—proceed anyway.
2. fix_md_extra.py fixes issues markdownlint cannot auto-fix (MD040, MD025).
3. prettier must ALWAYS run after the previous steps.
4. After all tools complete, verify with a final markdownlint check.

Correct flow:

markdownlint-cli2 --fix → fix_md_extra.py → prettier --write → markdownlint-cli2 (verify)

Wrong flow (DO NOT DO THIS):

markdownlint-cli2 --fix → (sees exit code 1) → STOP

Usage

/palas:fixing-markdown <target>

Arguments:

• target (Required):
  • File path: Single file (e.g., src/content/posts/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.

Environment Setup

This skill uses zero-footprint dependency management:

• JavaScript CLI tools (markdownlint-cli2, prettier): Executed via pnpm dlx — no package.json or node_modules needed
• Python scripts: Executed via uv run with PEP 723 inline metadata — no requirements.txt or .venv needed

Prerequisites (must be installed on the system):

• pnpm — https://pnpm.io/
• uv — https://docs.astral.sh/uv/

No per-project setup required. Dependencies are cached globally and resolved on first run.

Commands

Replace <plugin-path> with the actual path to this plugin's installation directory.

Single File

# Step 1: Fix structural issues (ALWAYS run, ignore exit code)
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc --fix "path/to/file.md"

# Step 2: Fix issues markdownlint cannot auto-fix (MD040, MD025)
uv run <plugin-path>/skills/fixing-markdown/scripts/fix_md_extra.py "path/to/file.md"

# Step 3: Format (ALWAYS run, even if previous steps had errors)
pnpm dlx prettier --config <plugin-path>/skills/fixing-markdown/.prettierrc --write "path/to/file.md"

# Step 4: Check remaining errors (if any, fix manually)
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc "path/to/file.md"

Folder (recursive)

# Step 1: Fix structural issues (exclude .agent/, ignore exit code)
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc --fix "path/to/folder/**/*.md" "#.agent"

# Step 2: Fix issues markdownlint cannot auto-fix (MD040, MD025)
uv run <plugin-path>/skills/fixing-markdown/scripts/fix_md_extra.py "path/to/folder"

# Step 3: Format (exclude .agent/, ALWAYS run)
pnpm dlx prettier --config <plugin-path>/skills/fixing-markdown/.prettierrc --write "path/to/folder/**/*.md" --ignore-pattern ".agent/**"

# Step 4: Check remaining errors
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc "path/to/folder/**/*.md" "#.agent"

Root Directory (.)

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

# Step 1: Fix structural issues (ignore exit code)
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc --fix "**/*.md" "#.agent"

# Step 2: Fix issues markdownlint cannot auto-fix (MD040, MD025)
uv run <plugin-path>/skills/fixing-markdown/scripts/fix_md_extra.py "."

# Step 3: Format (ALWAYS run)
pnpm dlx prettier --config <plugin-path>/skills/fixing-markdown/.prettierrc --write "**/*.md" --ignore-pattern ".agent/**"

# Step 4: Check remaining errors
pnpm dlx markdownlint-cli2 --config <plugin-path>/skills/fixing-markdown/.markdownlint-cli2.jsonc "**/*.md" "#.agent"

Examples

/palas:fixing-markdown src/content/posts/example.md
-> Fixes and formats specific file

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

/palas:fixing-markdown docs
-> Fixes and formats all .md files in docs/ recursively

Output Format

Clean File

Fixing: src/content/posts/example.md

markdownlint: 0 errors
fix_md_extra: no changes
prettier: formatted

Done

With Issues Fixed

Fixing: src/content/posts/example.md

markdownlint: 2 errors fixed
fix_md_extra: added language to 1 code block
prettier: formatted

Done

Tools

Rules Enforced

markdownlint-cli2 (.markdownlint-cli2.jsonc)

fix_md_extra.py (scripts/)

• MD040: Adds text as default language to code blocks without one
• MD025: Demotes duplicate H1 headings to H2

prettier (.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. Detect target type: file or folder
4. Run markdownlint-cli2 with --fix: Fix structural issues (always exclude .agent/). IGNORE exit code—proceed regardless.
5. Run fix_md_extra.py: Fix MD040 and MD025 issues that markdownlint cannot auto-fix.
6. Run prettier: Format visual appearance (always exclude .agent/). ALWAYS run this step.
7. Run markdownlint-cli2 without --fix: Verify no remaining errors
8. Report: Show results from all tools

Notes

• Config files: .markdownlint-cli2.jsonc, .prettierrc (in skill folder)
• Requires: pnpm and uv installed on system
• markdownlint exit code 1 is normal when there are unfixable errors—do not stop execution
• No node_modules or .venv created—dependencies cached globally by pnpm/uv