---
title: How to write Markdown docs your AI agent can follow
slug: write-markdown-docs-your-ai-agent-can-follow
excerpt: 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.
quickAnswer: Write one task per file. Start with a short YAML front matter block that holds the status, owner, date and goal. Use short headings that name what is under them, put the goal and the next step near the top, and write steps as a numbered list with one action each. Keep the same headings in every file so the agent knows where to write and you know where to look. When the agent rewrites the file, the change stays small and easy to review.
keyTakeaways:
  - One file per task keeps the agent focused and keeps each review small.
  - A short front matter block with status, owner, date and goal lets you judge a file before you read the body.
  - Short headings that name their content work as a map for both the agent and you.
  - A fixed file skeleton means the agent always knows where to write, and you always know where to look.
  - Ask the agent to edit in place and keep headings stable, so what changed between reads stays easy to see.
publishedDate: 2026-10-19
dateModified: 2026-10-19
author: Bobby Huang
cluster: A
role: post
status: published
faq:
  - q: Should I write the file or let the agent write it?
    a: Either works. A common split is that you write the front matter and the goal by hand, then let the agent fill in the steps and keep the status current. What matters is that both of you use the same skeleton.
  - q: How long should one Markdown task file be?
    a: Long enough to hold one task. If you need more than two screens to scroll past the steps, the file probably holds two tasks. Split it and link the two files.
  - q: Which front matter fields does an agent need?
    a: A status, an owner, a date and a one-line goal cover most cases. Add a field only when you or the agent will read it. Unused fields go stale and send the wrong signal.
related:
  - how-to-review-markdown-your-ai-agents-write
  - what-is-an-agent-handoff-file
  - front-matter-fields-status-date-owner
---

Most advice about Markdown files from AI agents is about reading them. This page is about the other half: writing the files your agent works from, so it follows them well and you can check its work fast.

The same habits help both readers. An agent reads a file top to bottom and acts on what it finds. You skim it between other jobs, looking for the part that needs you. Short headings, one task per file and a clear header serve both. This page is part of a series on [reviewing the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md).

## Why structure matters more with an agent

A person can fill gaps. If a note says "fix the thing from Tuesday," a colleague knows what you mean or asks. An agent may guess, and a confident guess is hard to spot later.

Structure removes the gaps. When the goal sits in the same place in every file, the agent reads it first. When the steps are numbered, it works through them in order and marks where it stopped. When the status lives in the header, you can tell at a glance whether the file needs you.

It also keeps reviews small. A file with stable headings changes in a few lines when the agent updates it. A file the agent rewrites from scratch changes everywhere, and you end up reading all of it again.

## One task per file

The single habit with the biggest payoff is one task per file. A file that holds a feature, two bug fixes and a note about next quarter gives the agent four jobs and no order. It also gives you a long file to re-read every time any one of them moves.

A task file should answer one question: what does done look like for this one piece of work? If you can't say that in a line, split the file.

Name each file after its task, with a date if you keep many of them. For example, `settings-dark-theme.md` or `2026-10-19-invoice-export.md`. A folder of small, well-named files is easier for an agent to search than one long running log, and easier for you to scan.

When two tasks depend on each other, link the files instead of merging them. A line such as "Blocked by: invoice-export.md" tells the agent where to look and tells you why the work stopped.

## A front matter block both of you can read

Front matter is the YAML block between two `---` lines at the top of a Markdown file. It holds facts about the file rather than the content itself. If the format is new to you, the guide to [front matter fields like status, date and owner](front-matter-fields-status-date-owner.md) covers the common ones one by one.

For an agent task file, four fields do most of the work: status, owner, date and goal. Here is a sample you can copy. The values are placeholders.

```yaml
---
title: Add a dark theme to the settings page
status: in-progress
owner: Jane Doe
updated: 2026-10-19
goal: Users can switch the settings page to a dark theme and the choice persists.
next: Agent wires the toggle to saved preferences.
blocked_by: none
---
```

A few rules keep this block useful:

- **Pick a fixed set of status values.** For example `todo`, `in-progress`, `blocked`, `review`, `done`. Tell the agent the list and ask it to use only those.
- **One date format.** `YYYY-MM-DD` sorts correctly and is hard to misread.
- **The owner is a real person or a named agent.** "Team" owns nothing.
- **Keep the goal to one line.** If it needs a paragraph, the body is the place for it.
- **Quote values with colons or special characters.** A stray colon breaks the YAML, and a broken header can hide the whole block.

Resist adding fields. Every field is a promise someone will keep it current. A `priority` field nobody updates is worse than none, because it looks true.

A raw YAML block gets hard to scan once it grows. A good Markdown reader should show the header as a small table of keys and values, so you can check status and date in a second. Sashmark is being built for this; the [roadmap](/roadmap) shows where it stands.

## Short headings that work as a map

Headings are how both readers find their way. An agent uses them to decide where to write. You use them to jump to the part you care about.

Keep them short and literal. "Goal," "Steps," "Open questions" and "Next step" usually beat clever titles. A heading should name what sits under it, so you never have to read the section to learn what it is.

Use the same headings in every file of the same kind. When every task file has an "Open questions" section in the same place, you build a habit: open the file, jump there, answer, close. The agent picks up the same habit, so it is less likely to invent new section names for the same thing.

Two levels of heading are usually enough. If you find yourself writing a fourth level, the file is probably holding more than one task.

## A file skeleton you can copy

Here is a full skeleton for an agent task file. Copy it, keep the headings, and replace the placeholder text.

```markdown
---
title: Short task name
status: todo
owner: Jane Doe
updated: 2026-10-19
goal: One line on what done looks like.
next: The single next action.
blocked_by: none
---

## Goal

One or two sentences. What is this for, and how will you know it worked?

## Context

Links to related files, specs or earlier handoffs. Keep it to a short list.

## Steps

1. One action per step.
2. Each step can be checked as done or not done.
3. The agent ticks steps off here as it finishes them.

## Checks

- [ ] Tests pass
- [ ] Page renders in light and dark themes

## Open questions

- Questions the agent can't decide alone. Each one names who should answer.

## Next step

The one thing that happens next, and who does it.

## Log

Short dated lines the agent adds after each session. Newest at the bottom.
```

Two parts of this skeleton earn their place more than the rest. The checks list turns "done" into something you can verify; a task marked done with no checks ticked proves nothing yet. The open questions section gives the agent a place to stop and ask instead of guessing. If you only adopt two sections, adopt those.

When a session ends, the same file can serve as the handoff. The [guide to agent handoff files](what-is-an-agent-handoff-file.md) covers what the next reader needs to find.

## Tell the agent how to use the file

A good skeleton helps only if the agent follows it. Put a few plain instructions in your prompt or project notes:

> Work from the task file named in this request. Read the front matter and the Goal first. Update the status and the `updated` date when you change the file. Tick steps and checks as you finish them. Add anything you can't decide to Open questions and stop. Edit the file in place. Do not rename or reorder headings.

That last line matters for your review. When the agent edits in place and leaves headings alone, each update touches a few lines. A good reader should show only the lines your agent changed since you last looked, so you review the change rather than the whole file. That is the job Sashmark is being built for, and the [roadmap](/roadmap) shows how far along it is. For a method that works with any tool, see [how to see what changed in a Markdown file](see-what-changed-in-a-markdown-file.md).

## Write for the skim

Write these files for a quick skim:

- Lead each section with the point, then the detail.
- Keep paragraphs to two or three sentences.
- Use lists for steps and checks, and prose for reasoning.
- Put file paths and commands in backticks so they stand out.
- Use a blockquote for the one warning that matters most in the file.

The agent benefits too. Short, direct sections are easier to follow than long ones, and lists are easier to tick off than paragraphs.

## A short checklist before you hand a file to an agent

Run through this in thirty seconds:

1. The file holds one task.
2. The front matter has a status, owner, date and one-line goal.
3. Status uses a value from your fixed list.
4. Headings match your skeleton, in the same order.
5. Each step is one action that can be checked.
6. Checks say how you'll know the task is done.
7. There is an Open questions section, even if it's empty.
8. The next step names who acts.
9. Placeholder names are placeholders, such as Jane Doe, not real people.

If a file fails two or more of these, fix it before the agent starts. A few minutes on the file can save a long review later.

## Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released, and the app itself has no AI features. It is being built around the loop on this page. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

Sashmark is in development. See what it is at [sashmark.com](https://www.sashmark.com/).