agent-markdown

Note

This skill now lives in the TarasShyn/skills collection and gets its updates there — install with npx skills add TarasShyn/skills or grab just skills/agent-markdown. Skill page: tarasshynkarenko.com/skills/agent-markdown. This repo stays up as-is.

A Claude Code skill for implementing the agent markdown pattern: serving a Markdown twin of every indexable page to AI agents and CLI clients.

What it does

Guides an agent through shipping the full pattern:

• .md suffix URLs (/pricing.md) and Accept: text/markdown negotiation on canonical URLs
• /sitemap.md, llms.txt, llms-full.txt, and rel="alternate" discovery links
• Hand-authored Markdown overrides with automatic HTML→Markdown conversion as fallback
• Both dynamic-server and static-export site variants

What it's for

Getting your site read correctly (and cheaply) by LLMs, AI crawlers, and curl — without breaking SEO, caching, or auth in the process. The skill carries 39 production gotchas from shipping this on Next.js + Cloudflare Workers (CDNs ignore Vary, config header rules clobbering no-store, cache poisoning at canonical URLs, rewrite recursion, suffix-URL redirect collisions, auth pages leaking into public caches), written stack-agnostically so the pattern ports anywhere.

Files

• skills/agent-markdown/SKILL.md — the pattern, detection precedence, caching rules
• skills/agent-markdown/references/gotchas.md — the full gotcha registry
• skills/agent-markdown/references/rollout.md — implementation recipes and code sketches

Install

npx skills add TarasShyn/agent-markdown

Or copy skills/agent-markdown/ into ~/.claude/skills/ (global) or a project's .claude/skills/.