Getting started

Writing with agents

Agents draft most documents now, and they already write Markdown. Give them Markset's eight constructs and a checker, and what they write is a page people want to read: still plain text, still easy to review, and checked before anyone opens it.

The loop

1. Point your agent at the guide. It ships with the command line tool: the eight constructs, when each earns its place and when it does not, and the rules that keep a document portable.
2. Ask for the document. Say who it is for and what it has to do. The agent writes the content first, then gives a construct only to content that already has its shape.
3. The agent checks its own work. markset check names every problem with a code, and the guide tells the agent to fix them all before it hands the document over.
4. You review the source and the page. The source is Markdown, so the diff is the content. The preview shows the page as a reader will see it.
5. Change what you would say differently. Edit a line in VS Code or in the visual editor, without asking for the whole document again.

Set it up

Install the command line tool beside your project:

npm install --save-dev @markset-lang/cli

pnpm add --save-dev @markset-lang/cli

Then add one line to the file your agent reads, so it loads the guide before it writes:

@node_modules/@markset-lang/cli/guide.md

Before writing a Markset document, read node_modules/@markset-lang/cli/guide.md and follow it.

Read https://markset.org/guide.md and follow it.

Installed, the guide stays in step with the version you run. markset guide prints it.

Read the guide The markset command

A test of the guide

The same document, twice

Before the guide was released, it was tested. A fresh agent was given the authoring guide, the same file your agent reads from node_modules, and nothing else: no specification and no examples. It was asked for a two-page review of an invented product's checkout rollout, written for engineering and product leaders. Its document passed markset check on the first run. It then wrote the same content as plain Markdown, so the two could be compared.

Both are drawn below by the same renderer with the same stylesheet, so the only difference is the constructs. The product, its numbers and its team are invented; the documents are exactly as the agent wrote them.

The headline numbers

The agent split the numbers into two blocks because two of them improve by going down, and the guide says a block has one direction.

The trend behind them

The chart is added to the table, not swapped for it: a reader who wants the exact number still has it, and anywhere Markset is not supported the table is all there is.

Every other week of the agent's ten, to fit a column. The full documents have them all.

Open the Markset version Open the plain version

What it chose, and what it left out

• One card, for the summary at the top. No other section is wrapped in one.
• A line chart, because the trend is the argument: the lift held for ten weeks, and the one dip is the week of the incident.
• Steps for the six stages of the rollout, which happened in order.
• One warning, for the risk that is still live. The incident itself stays in paragraphs.
• A grid for the three options the readers have to choose between, with a badge on the recommended one.
• No columns and no tabs. Nothing in the content had their shape.

That restraint comes from the guide, which spends as long on when not to use a construct as on how to write one.