Blog
How to write Markdown docs your AI agent can follow
Short headings, one task per file and a clear front matter block make Markdown files from AI agents faster to read, for the agent and for you. Copy the sample header, file skeleton and checklist.
Common front matter fields: status, date and owner
A field-by-field guide to the front matter you will often see in agent-written Markdown, what each field tends to mean, and what to check when you read it.
How to diff Markdown files with git
Use git diff, word diffs, commit history and no-index comparisons to read Markdown changes without whole-paragraph noise.
What is a byte-for-byte round-trip save?
A byte-for-byte round-trip save keeps untouched Markdown bytes unchanged, including line endings, whitespace and the final newline.
What is front matter in Markdown?
Front matter is a block of data at the top of a Markdown file. Here is what it looks like, what it does, and where it breaks.
Why editors reformat Markdown on save and bloat diffs
Why a one-word Markdown fix can produce a large diff, and how list markers, wrapping and whitespace settings cause formatting churn.
Quoting strings, dates and lists in YAML front matter
When to quote values in Markdown front matter, how dates and lists parse, and the unquoted values that silently change type.
Markdown syntax guide: common elements with examples
A plain Markdown syntax reference. Each element shows the source you type and the result you get, from headings and lists to tables and code blocks.
Markdown task lists: - [ ] and - [x] explained
How Markdown task lists work, why some boxes do not render, how to nest and tick them, and how to count open tasks in a plan from the terminal.
Reviewing Codex handoff notes: a checklist
A short checklist that tells you in a few minutes whether a Codex handoff note shows the work is done, plus how to ask Codex for notes that pass it.
See what changed in a Markdown file: git, diffs, readers
How to see what changed in a Markdown file, with or without git. Line, word and rendered diffs, plus save habits that keep diffs small.
What is a .md file, and how do you open one?
A .md file is a plain text file written in Markdown. What is inside one, where you see them, and how to open, read and create one on any computer.
Common YAML front matter errors and how to fix them
Most broken YAML front matter comes from a few mistakes. Find the bad line, then fix colons, comments, tabs, indentation, quotes and type changes.
YAML front matter in Markdown: a practical guide
Front matter is the YAML block at the top of a Markdown file. How it works, which tools read it, and why it sometimes shows up as plain text.
How to review the Markdown your AI agents write
A plain review loop for the plans, handoffs and drafts your AI agents save as Markdown. Read rendered, check what changed, keep your place, fix a line.
Where Claude Code saves its plan file and how to read it
You don't need a code editor to review a Claude Code plan file. Light ways to open it, what to check, and how to follow the plan as it changes.
What is an agent handoff file?
An agent handoff file is a Markdown file an AI agent writes so the next session can pick up the work. What one holds and how to read it fast.