name: maraudersmapmd-skill
description: Rewrite Markdown documents to maximize readability and scan-ability using the MaraudersMapMD skill. Use this skill when the user asks to improve, rewrite, or optimize a Markdown document for readability, or when asked to apply MaraudersMapMD readability formatting.
metadata:
version: "4.0.0"
source: "MaraudersMapMD src/ai/aiService.ts buildReadabilityPrompt()"
tags:
- markdown
- readability
- formatting
- maraudersmapmd

MaraudersMapMD Skill

When to Use

• User asks to improve readability, rewrite for clarity, or optimize a Markdown document for scanning
• User asks to apply MaraudersMapMD formatting or make a document AI-readable
• User provides a Markdown document and asks for editorial polish

Canonical Prompt

The text below is copied verbatim from buildReadabilityPrompt() in src/ai/aiService.ts of the MaraudersMapMD extension. Apply it as-is. ${source} stands for the user-provided Markdown.

You are an expert technical editor. Rewrite the Markdown to maximize readability and scan-ability while preserving meaning and intent.

Core requirements:
- Keep the final language the same as the original (do not translate). If mixed, use the dominant language.
- Preserve all facts, constraints, and technical details. Do not add new information.
- Keep Markdown semantics correct (headings, lists, tables, code fences, links).
- Use the project's AI hint block format where it helps: "> [AI RULE]", "> [AI DECISION]", "> [AI TODO]", "> [AI CONTEXT]".
- Prefer short paragraphs, clear headings, and consistent numbering.
- Use tables for settings, options, or structured comparisons when helpful.
- Keep code blocks and inline code exactly as-is.
- Remove fluff and redundancy; keep only what's necessary.
- Output ONLY the final Markdown. No commentary.

Formatting guidance:
- Ensure headings follow a clean hierarchy.
- Convert dense prose into bullet lists where it improves readability.
- Keep a concise top summary if the document is long.

SOURCE MARKDOWN (do not omit any content):
<<>>

Procedure

Follow these five phases in order. Each phase uses a MaraudersMapMD artifact as its primary reference.

Artifact paths (generated by the extension on save):
- AI Map: docs/MaraudersMap/<docId>/ai-map.md
- Section Pack: docs/MaraudersMap/<docId>/sections/*.md
- Search Index: docs/MaraudersMap/<docId>/index.json

Phase 1 — Baseline capture (before any rewriting)

Read the AI Map (ai-map.md). It contains a table of every section with line ranges, token counts, and one-line summaries. Read the Search Index (index.json). It lists keywords, links, and AI Hint Blocks per section. Together these two artifacts are the ground truth for what the source contains. Do not rewrite anything yet.

Phase 2 — Create working copy

Create a temp/ folder next to the original file. Copy the original into it as the working copy: temp/temp_<filename>.rewritten.md. Example: guide.md → temp/temp_guide.rewritten.md. All intermediate files go inside this temp/ folder. All subsequent edits happen ONLY on this copy. Never modify the original.

Phase 3 — Skeleton

Using the AI Map table as a guide, write a flat heading list in the working copy. Next to each heading note its one-line purpose. Fix heading levels so they descend without skips (single #, then ##, then ###). If the document is long, place a concise summary after the title.

Phase 4 — Section-by-section rewrite

Open each Section Pack file (sections/*.md) one at a time, in order. For each section:
1. Check the Search Index entry for that section's keywords, links, and AI Hint Blocks.
2. Apply the canonical prompt rules: shorten paragraphs, convert dense prose to bullets, use tables for settings/options, keep code blocks unchanged.
3. Preserve every keyword, link, and AI Hint Block listed in the index entry.
4. Make the section self-contained. Use brief cross-references ("see Section X") instead of repeating content.

Phase 5 — Verification and cleanup

Compare the finished output against the original Search Index:
1. Every keyword in the index must appear in the output.
2. Every AI Hint Block in the index must appear in the output.
3. Every link in the index must appear in the output.
4. Token count of the output should not significantly exceed the original (check AI Map's total).
5. Run the checklist below.

After verification passes:
1. Move temp/temp_<filename>.rewritten.md to the original file's directory as <filename>.rewritten.md.
2. Delete the temp/ folder entirely.
3. Delete all MaraudersMapMD artifacts (docs/MaraudersMap/<docId>/ directory).
4. Confirm only the original source file and <filename>.rewritten.md remain. No temp/ folder or temp_ files should exist.

Checklist

After rewriting, verify every item below. Each maps to a rule in the canonical prompt.

• [ ] Heading hierarchy is correct (single # title, levels descend without skips)
• [ ] Concise summary present at the top for long documents
• [ ] Paragraphs are short (2–4 lines); dense prose converted to bullets
• [ ] Tables used for settings, options, or structured comparisons
• [ ] No hard line breaks inside paragraphs
• [ ] No extra blank lines inside lists
• [ ] Typos fixed; product names, command names, and identifiers preserved exactly
• [ ] AI Hint Blocks (> [AI RULE], > [AI DECISION], > [AI TODO], > [AI CONTEXT]) used only where the source content warrants them
• [ ] All facts, constraints, and technical details from the source are present in the output
• [ ] Code blocks and inline code unchanged
• [ ] Output language matches the source's dominant language
• [ ] Output is only the final Markdown — no commentary or preamble