Revise Skill

The Revise Skill (atelier-revise) reads a markdown document that contains annotation feedback from the Atelier editor, proposes targeted edits using inline tracked changes, and replies to each annotation in an embedded conversation thread.

Annotations are stored directly in the document as HTML tags — no separate file or data structure. The skill edits the document in place; the Atelier editor renders the proposed changes for you to accept or reject.

When to use

• A markdown document has annotations in the Atelier editor and you want AI to address the feedback
• You are iterating on a plan or spec and want to send follow-up comments on previous suggestions
• You want AI to revise a document based on inline comments without leaving the editor

Arguments

• file — Path to the markdown document being revised.

What it does

The skill classifies each annotation in the document and processes it accordingly:

State	Condition	What the skill does
New feedback	Highlighted text with a first user: comment	Proposes edits and replies in the thread
Follow-up	Existing edit with a new user: comment	Revises the edit and replies
Ambiguous	Comment too vague to act on confidently	Asks a clarifying question
Resolved	Last turn in the thread is from the agent	Left unchanged
Document-wide	user: comment with no highlighted span	Reads the full document and applies edits across sections

For annotations that reference an external file (e.g. [data-model.md](./specs/data-model.md)), the skill delegates to a grounding subagent that reads the relevant section before making edits.

Follow-up mode

When you reply to an existing annotation in the sidebar, the editor sends a targeted prompt that lists only the annotation IDs with new replies. The skill reads just those sections and skips a full document pass, making follow-up rounds faster.

Annotation format

Annotations are stored as HTML tags embedded in the markdown file. All four tag types for one annotation share the same data-ann ID:

• <mark data-ann="a1"> — Text you highlighted in the editor
• <aside data-ann="a1"> — The conversation thread (turns prefixed with user: or agent:)
• <del data-ann="a1"> — Text the skill suggests removing
• <ins data-ann="a1"> — Text the skill suggests inserting

Block-level structural changes (heading level, table rows, list type) use data-ann and data-op attributes on the block element directly instead of inline <del>/<ins> tags.

Invocation

From the Atelier markdown editor, click the Revise button on any annotated plan or document. The default prompt template is:

Revise '{{title}}' using /atelier-revise file={{file}}

You can also run directly in Claude Code: /atelier-revise file=path/to/document.md