spb/ultra-sharp-agent-skills Public

1---2name: processing-markdown3description: Creates, reads, restructures, and converts Markdown files. Use when the user asks to write, edit, reorganize, lint, or fix a .md file, update a specific section of a README or docs page, generate a table of contents, or convert Markdown to or from HTML, DOCX, or PDF with pandoc. Do not use for writing user-facing release notes in house style (the writing-release-notes skill covers that) and not for HTML files.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Processing Markdown1213## When to use / when NOT to use14- **Use for:** creating or editing `.md` files (READMEs, docs, notes), structure-aware edits ("update the Installation section"), generating tables of contents, and converting md ↔ html/docx/pdf.15- **Do NOT use for:** user-facing release notes in house style (use the writing-release-notes skill) or HTML files (use the HTML skill).1617## Quick reference1819**Default:** Markdown is plain text — create and modify by writing/editing the file directly. No library needed. **Conversion:** pandoc (`brew install pandoc`; PDF output also needs a LaTeX engine: `brew install basictex`).2021```bash22# Convert23pandoc README.md -o README.html                 # md → HTML24pandoc report.md -o report.docx                 # md → Word25pandoc report.md -o report.pdf                  # md → PDF (needs LaTeX)26pandoc page.html -t gfm -o page.md              # HTML → md27pandoc document.docx -t gfm -o document.md      # Word → md28```2930**Structure-aware edit** — locate sections by heading lines, then edit only that slice:3132```python33lines = open("README.md").read().splitlines(keepends=True)34starts = [i for i, l in enumerate(lines) if l.startswith("#")]35# a section runs from its heading to the next heading of same-or-higher level36```3738## Rules39- **Match the file's existing conventions** when editing: heading style (`#` vs underline), bullet marker (`-` vs `*`), emphasis (`_` vs `*`), code-fence style. Never reformat untouched sections.40- One H1 (`#`) per document, at the top; sections descend without skipping levels (`##` → `###`).41- Fenced code blocks always carry a language tag (```python, ```bash, ```text for plain).42- Blank line before and after headings, lists, and code fences — most renderers require it.4344## Workflow451. Identify the operation: create / read-extract / section edit / convert.462. For edits, read the file first and note its conventions (heading style, bullets, fence style).473. Perform the edit on the smallest possible region (recipes in references/recipes.md).484. For conversion, verify every relative link and image path referenced in the file exists before running pandoc; report missing targets.495. **Validate:** re-read the result — heading hierarchy has no skipped levels, all fences are closed (even count of ``` lines), links/images resolve. For conversions, confirm the output file exists and is non-empty. Fix and repeat until clean.5051## Edge cases & failure modes52- **pandoc missing** → `brew install pandoc` (macOS) / `apt-get install pandoc` (Linux); PDF errors about `pdflatex` → `brew install basictex`.53- **Unclosed code fence** → everything after it renders as code; check for an odd number of ``` lines before editing by heading.54- **Duplicate section names** → confirm with the user which occurrence to edit; never guess.55- **Markdown flavor mismatch** (tables, task lists, footnotes) → target GitHub-Flavored Markdown (`-t gfm` in pandoc) unless the user states another renderer.56- **Huge files (>5,000 lines)** → edit by line-range around the located heading; never rewrite the whole file for a one-section change.5758## References59Deeper copy-paste recipes (section replace, TOC generation, link checking, pandoc options): see [references/recipes.md](references/recipes.md).60