---
name: markdownto-todo
description: Create or edit portable Markdown To checklists with actionable, verifiable tasks.
---
# Markdown To todo
## Contract and workflow
Read `mdto spec todo` (or the adjacent `SPEC.md` in a checkout) and the
[shared conventions](https://markdownto.ai/specs/conventions.md) before authoring or
repairing content. Outside a checkout, use the [published spec](https://markdownto.ai/specs/todo.md).
This skill accompanies `[email protected]`. The spec and its fixtures govern conformance;
editorial advice below is non-normative and should adapt to the user's brief.
If the source declares another version, obtain its matching contract before changing it.
Use `markdownto: [email protected]`. Sections are optional; checkboxes are `[ ]`, `[x]`, or
`[X]`. An in-progress or dropped state belongs to backlog, not an invented todo marker.
Use the spec's `add`, `done`, `undone`, `rm`, and `move` verbs when they cover the edit.
Moving a todo does not change its completion state.
## Content quality
Write tasks as actions with a visible finish: “Send the revised estimate to Jo” is more
useful than “Estimate.” Split a task when its parts can be completed independently; keep
small steps together when splitting would obscure the outcome. Use section names to help
someone find work, not to invent workflow semantics. Preserve the user's granularity and
avoid turning reference notes into obligations.
## Check and deliver
Validate the file with `mdto validate <path>` before editing existing content and again
after changes. Read diagnostics against the spec's rationale; preserve meaning when
repairing syntax. Prefer spec-owned verbs for edits they support, checking their current
`--help`; otherwise make a focused source edit, preserving unrelated content and IDs.
Render with `mdto render <path>` and inspect the result when available. Validation checks
structure, not editorial quality: review the content against the user's purpose as well.
Without the CLI, use the contract and examples and report that validation was not run.
Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Contract and workflow
Read mdto spec todo (or the adjacent SPEC.md in a checkout) and the shared conventions before authoring or repairing content. Outside a checkout, use the published spec. This skill accompanies [email protected]. The spec and its fixtures govern conformance; editorial advice below is non-normative and should adapt to the user's brief. If the source declares another version, obtain its matching contract before changing it.
Use markdownto: [email protected]. Sections are optional; checkboxes are [ ], [x], or [X]. An in-progress or dropped state belongs to backlog, not an invented todo marker. Use the spec's add, done, undone, rm, and move verbs when they cover the edit. Moving a todo does not change its completion state.
Content quality
Write tasks as actions with a visible finish: “Send the revised estimate to Jo” is more useful than “Estimate.” Split a task when its parts can be completed independently; keep small steps together when splitting would obscure the outcome. Use section names to help someone find work, not to invent workflow semantics. Preserve the user's granularity and avoid turning reference notes into obligations.
Check and deliver
Validate the file with mdto validate <path> before editing existing content and again after changes. Read diagnostics against the spec's rationale; preserve meaning when repairing syntax. Prefer spec-owned verbs for edits they support, checking their current --help; otherwise make a focused source edit, preserving unrelated content and IDs. Render with mdto render <path> and inspect the result when available. Validation checks structure, not editorial quality: review the content against the user's purpose as well. Without the CLI, use the contract and examples and report that validation was not run. Deliver the Markdown source and any requested artifacts, stating what was actually checked.