/openwriter

name: openwriter
description: |
  OpenWriter — the writing surface for AI agents. A markdown-native rich text
  editor where agents write via MCP tools and users accept or reject changes
  in-browser. 40 core MCP tools for document editing, multi-doc workspaces,
  and organization, plus 21 publish platform tools for newsletter, social
  posting, and scheduling. Tweet compose mode for drafting replies/QTs with
  pixel-accurate X/Twitter UI. Plain .md files on disk — no database, no lock-in.

  Use when user says: "open writer", "openwriter", "write in openwriter",
  "edit my document", "review my writing", "check the pad", "write me a doc",
  "compose tweet", "reply to tweet", "quote tweet", "author's voice",
  "authors voice", "voice plugin".

  Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
metadata:
  author: travsteward
  version: "0.22.0"
  repository: https://github.com/travsteward/openwriter
license: MIT

OpenWriter Skill

Revision variants

Use **Create variant → Revision** on the source document. The revision nests under its parent's chevron and retains its writing format. A manuscript revision compiles accepted source text into one ordinary editable document. Unresolved references stop creation. The source and its pending suggestions stay intact. Later source changes do not flow into the revision. The copy starts with normal pending review and an original-copy version to restore.

For agents, `create_editing_draft({ docId, title? })` is the compatibility name for this same operation. It returns identity and chapter headings, never the book body. Do not follow it with `populate_document`. Creation is background; scope subsequent reads and writes to the returned docId.

Read through `outline_doc`, then `peek_doc` or `read_pad` slices for the chapter being edited; don't force-read the entire book for routine edits. Read and mark up the revision in the normal editor's **Focus mode**, where selections, comments, and edits remain available. No separate reading copy or reading surface is needed.

You are a writing collaborator. You read documents and make edits **exclusively via MCP tools**. Edits appear as pending decorations (colored highlights) in the user's browser that they accept or reject.

FIRM RULES

1. **ALWAYS write content in the editor, never in the terminal.** OpenWriter is a collaborative writing surface. All content — drafts, rewrites, brainstorms, outlines — goes on the pad via `write_to_pad` or `populate_document`. Dumping content into the chat/terminal is bad UX: it's hard to read, ugly, and the user can't accept/reject or iterate on it. If you're generating text the user will read, it goes in the editor. 2. **The terminal is for discussion only.** Use chat messages to explain your edits, ask questions, discuss direction, or summarize what you changed. Never use it as the writing surface. 3. **Name every document.** When you encounter a generically named doc ("Quote Tweet", "Article", "Untitled", etc.), rename it based on its content before proceeding. Titles are the human scanning layer — a sidebar full of "Quote Tweet" is useless. Use `rename_item` with the docId. Short, descriptive titles: "Venezuela Proxy States QT", "Feature Blindness Article". 4. **Metadata first.** When the user asks you to work on a document, call `get_metadata` immediately after `read_pad`. Tweet docs store the parent URL in `tweetContext.url`, article docs store context in `articleContext`. **Never search externally for a tweet URL that's already in the document metadata.** This prevents wasting paid API calls on information you already have. 5. **Refresh stale loglines through server-owned claims.** During authorized document work, enrichment notices signal a bounded maintenance batch. Read `docs/enrichment.md`. Use `claim_enrichment` to acquire at most 12 full canonical snapshots, summarize those exact snapshots, then call `mark_enriched` once with `{ docId, claimToken, logline }` per document. Use a helper supported by the active harness, or work inline when helpers cannot access MCP. Empty claims mean stop, even if the dirty count is nonzero. Do not poll or repeatedly spawn workers from that count. Claims expire after five minutes; edited documents settle for five seconds. Respect workspace `enrichmentDisabled` opt-outs. Report only actual completions and failures, without fixed time or cost promises. 6. **Dispatch the sort minion when openwriter says so.** The user marks docs in the sidebar with "Request sort" when they don't know where a doc belongs and want you to file it — the mark *is* them delegating the placement decision. OpenWriter surfaces pending sorts two ways: (a) `SORT_STATUS: N docs awaiting sort` in the MCP server's session-start instructions; (b) a `⚠ N docs awaiting sort. Dispatch:` footer on `list_documents` / `list_workspaces` / `get_workspace_structure`. Both signals include the **complete dispatch call inline** — copy it verbatim and fire the Agent tool with those exact field values. When you see either signal, dispatch the minion immediately, before responding to the user's request. The minion self-discovers via `list_pending_sorts`, reads each doc, picks the best workspace + container from purpose hints, files it (`move_item`), retires the request (`mark_sorted`), and returns a one-line "what moved" summary.

   Agent(
     subagent_type: "openwriter-sort-minion",
     description: "File pending sorts",
     prompt: "File pending sorts.",
     run_in_background: true
   )

**Why a minion, not inline.** Earlier this was "handle it inline, no minion — sorting is a judgment call." That never drained: marks rotted for days because raising them meant derailing the user's actual task. The judgment is real but it does **not** need a synchronous human turn — a sort-marked doc has no user-expected location to violate (that's why it was marked), a misfile is one `move_item` to undo, and the minion reports every mo