AI-Native Markdown in Markdown

Lessons in this section

1. AGENTS.md Files

   Write the AGENTS.md file AI coding agents read at the start of every session. Prune a 156-line file to the facts the code cannot say, apply the always-on test, share one file with CLAUDE.md and Cursor rules, and use nested files in bigger repos.

2. Skills and Subagents

   Write a SKILL.md that gets picked for the right tasks. Fix a skill whose vague description never loads, follow the name rules, write a description with what, when and when not, keep the body small with progressive disclosure, and write a reviewer subagent file.

3. Specs and Plans

   Turn a vague ticket into a spec an agent can build from. Write a goal, non-goals, requirements and checkable acceptance criteria, remove vague words and open questions, and write plans, decision records and reusable prompt files.

4. LLM-Friendly Docs

   Write docs that AI tools can find their way through. Fix a page whose answer a chatbot missed, give each section a heading that names its topic, make sections stand alone, and write an llms.txt that maps your docs.

5. Cleaning AI Output

   Fix the Markdown that AI tools write. Clean an answer buried in bold, headings, nested bullets and emoji, repair broken tables, adapt text for email and chat apps, and write style rules that agents follow.

6. Capstone Project

   Build a Markdown kit for your own repo: README, AGENTS.md and tool files, a skill and a subagent, a spec, plan and ADR, docs and llms.txt, and lint settings. Audit your existing files, pass the graded checks and download the kit as a zip.