---
description: Generates a word-for-word accurate Markdown companion file for an HTML blog post or article page, for AI agents requesting a text/markdown representation instead of scraped HTML. Use when a post's HTML is finalized (or just changed) and needs its .md sibling created or brought back in sync.
---

## What this produces

Given a blog post or article's HTML file, produce (or update) a `.md` file with the same base name, sitting next to it, that is **word-for-word accurate** to the HTML's visible content - not a summary, not a paraphrase, not a "close enough" rewrite. This file is meant to be servable as a `text/markdown` representation of that page, so an AI agent reading it should get the same information a human reader gets from the rendered page. (Actually serving it - content negotiation, headers, routing - is a separate concern this skill doesn't handle; see "What this skill does NOT do" below.)

## Structural mapping (HTML -> Markdown)

- `<title>` / the post's `<h1>` -> a single `#` heading, exact text.
- `<meta name="description">` -> one italicized line near the top: `*<description text>*`.
- Byline / attribution metadata (a brand name, an author, a post-type label like "Case Study," a publish or last-verified date) -> plain text line(s), preserving any links within them per the Links rule below (an author name linking to a `mailto:` address, for instance, becomes a normal Markdown link). Don't drop these - they're real content, not decoration. If the page has more than one such line (e.g. a brand/category line AND a separate author/date line), keep each as its own line, in the same top-to-bottom order they appear in the HTML - don't merge them into one, and don't drop the second one just because the mapping rule above only gives one example.
- Tag chips -> a single line of backtick-wrapped hashtags, e.g. `` `#Tag1` `#Tag2` ``.
- `<blockquote>` -> a real Markdown blockquote (`>`), as its own block. Do NOT flatten a blockquote into inline italic text inside a surrounding paragraph - that changes the structure an agent would parse, even if the words are identical.
- `<pre><code>` blocks -> fenced code blocks (use a language tag like ```` ```xml ```` when the HTML's `<pre>` implies one, otherwise a bare ```` ``` ````). Preserve the exact code content, including any HTML-entity-escaped characters decoded back to their literal form (e.g. `&lt;` -> `<`).
- A `<figcaption>` sitting under a code panel (a filename or label like `robots.txt` or `Request`) -> an italic line placed immediately after the closing code fence, exact same text: `*robots.txt*`. Always put it directly under the block it labels, never above.
- Links (`<a href="...">text</a>`) -> `[text](url)`, preserving the href exactly, including relative paths (`/contact.html`) and non-http schemes (`mailto:...`).
- `<strong>` / `<em>` -> `**bold**` / `*italic*`.
- `<ul><li>` -> `-` bullet lists, preserving any bolded lead-in per item.
- A styled CTA button (`<a class="...">Label</a>` styled as a button rather than an inline link) -> its own line as a plain Markdown link: `[Label](url)`. Do not invent surrounding sentence text that isn't in the button itself, and do not carry over old prose that used to accompany a link before it became a button - check what the button's visible label actually says today, word for word.

## Process

1. Read the full HTML file end to end - don't skim. Note every piece of visible text: headings, paragraphs, list items, code blocks, captions, link text, button labels, every byline-style metadata line (there may be more than one), tags, and the meta description.
2. Check whether a `.md` file already exists for this post.
   - **If one exists:** read it end to end too, then diff the two section by section, in document order. Look specifically for:
     - Prose that was edited in one file and not the other (the most common drift - a later small wording tweak applied to only one file).
     - Structural mismatches (a blockquote in HTML flattened to inline text in MD, or vice versa).
     - Missing metadata (description, byline/attribution lines, tags) that exists in one file but not the other - including a second byline line (author, date) that the first pass might miss if it isn't watching for more than one.
     - Code blocks missing their caption/footer line.
     - A CTA or link whose surrounding sentence changed in one file (e.g. a trailing clause that got dropped when a plain link became a styled button) but not the other.
   - **If none exists yet:** there's nothing to diff - just produce a complete, fresh transcription of the HTML following the structural mapping above. Don't skip metadata (byline lines, tags, description) just because there's no prior version to check against; the same completeness rules apply either way.
3. Fix or write the `.md` file to match the HTML's current, real content - the HTML is the source of truth, since it's what's actually rendered to human visitors.
4. If the project has its own documented house style rules (an `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, or similar), apply them to the result. Otherwise, keep the tone and wording exactly as written - this is a format conversion, not a rewrite, and it's not the place to introduce your own stylistic preferences.
5. Report back a short list of what actually changed (or, for a fresh file, what was produced), section by section, rather than just "updated the file" - the point of this skill is catching drift or gaps, so the diff itself is the useful output, not just the final file.

## What this skill does NOT do

- It does not deploy the file or wire up server-side content negotiation (serving it in response to `Accept: text/markdown`, setting `Content-Type`, caching headers, etc.) - that's a separate, project-specific piece of infrastructure work.
- It does not summarize or shorten the post. If the HTML is long, the Markdown is exactly as long.
- It does not run automatically on every edit - invoke it deliberately once a post's HTML is considered finalized, or after a batch of edits, to bring the `.md` companion back in sync.