collaborate-in-markdown

Co-edit a markdown document the user has open and is typing in. Read the document, find `@agent` markers, do the work each one asks for, then present every proposed change in chat and get approval before writing anything. Use when the user points at a markdown file containing `@agent` markers, asks you to fill in or answer parts of a doc you are both working on, or says to collaborate on / work through a document together. Exists to keep writes from clobbering content the user is editing live.

Plugin	`authoring`
Invoke	`/authoring:collaborate-in-markdown`
Allowed tools	`Read Edit Grep Glob Bash AskUserQuestion`
Source	SKILL.md

The user has the file open in an editor and is typing in it while you work. Their draft is authoritative and in motion. Your job is to answer the markers they left you and hand back changes they approve — not to tidy the document.

Steps

Read the document fresh. Read it immediately before acting, even if you read it earlier in the session. The user has been typing since.
Find the markers. A marker is @agent at the start of a line or inline, in one of two forms:
```
@agent:<verb> <instruction>
@agent <instruction>
```
A misspelled verb is still that verb (@agent:survye → survey). If a marker is ambiguous, or there are more than three, list what you found and your reading of each before starting the work.
Do the work. Each marker’s scope is its own section — the heading it sits under, down to the next heading of the same or higher level — unless the instruction says otherwise. Lines following a marker that read as continuations of it (Existing X: summarize its functionality) are part of that marker’s instruction.
Queue the changes. Write nothing yet. Hold every edit as a pending change.
Present the queue in chat. For each pending change give: the target heading, the disposition (marker consumed / section replaced / content appended), and the content. Show it verbatim if short; if long, summarize faithfully and show the structure — headings, table columns, item counts — so the user can judge shape without reading it twice.
Ask. Offer: write all, write a subset, revise first, or hold. Then wait. If the user already said to write without asking, skip to step 7.
Re-read, then write. Read the file again right before editing. If it changed since step 1, re-anchor each edit against the current text; report any queued change that no longer applies instead of forcing it in.
Report what landed, by heading, and say what you left out.

Rules of engagement

Rule	Detail
Consume the marker	Replace the `@agent…` line with the result. Leaving the marker in place means the work gets redone next pass. Keep it only if the marker says to.
Stay inside the scope	Typos, half-finished sentences, stray `[]()` fragments, and placeholder text elsewhere in the document are work in progress. Leave them exactly as they are.
Never reformat the file	No wholesale reflow, heading renumbering, or table realignment. Match the surrounding style in what you add; change nothing you were not asked to change.
Questions go at the bottom	Collect open questions into one `## Questions` section at the end, each with an `A:` line beneath it for the user to answer inline. Do not scatter questions through the body.
Say it in chat, not in the doc	If a marker asks for something you cannot answer or verify, raise it in the queue. Do not write a hedge, a TODO, or an apology into the document.
Report conflicts, don’t resolve them	When the work you produce contradicts something the user already wrote, present both and name the conflict. The document is theirs to reconcile.

Marker vocabulary

Verbs are a convenience, not a closed set — an unrecognized verb is read literally.

Verb	Means
`survey`	Research the named scope and summarize the findings in place
`draft`	Write the section from scratch
`expand`	Develop the existing bullets or notes into prose
`answer`	Respond to the question stated in the marker
`review`	Assess what is already written; report rather than rewrite
`fix`	Correct the specific problem named
(none)	Follow the instruction as written