Motion Document Agent

intent

use this skill when the user pastes a Motion invite URL (contains /invite/ or /agent/), asks to edit a Motion document, connect to Motion, collaborate on a document, write to Motion, or provides a document_id/agent_token/invite_token. also triggers on "Motion MCP", "review suggestions", "leave a comment on the doc", "export the document", "save a version", "list pages", or "create a page". this skill connects to Motion's real-time collaborative editor, where your edits appear live in the user's browser and show up in the presence bar alongside human collaborators. by default edits are wrapped in suggestion marks for human review, but you can operate in direct mode if authorized.

inputs

authentication (choose one):

• agent_token: 64-character hex string. workspace admins generate this from Settings > Agent tokens. grants full workspace access. preferred method.
• invite_token + document_id: extract from invite URL pattern https://{APP_HOST}/invite/{INVITE_TOKEN}/{DOCUMENT_ID}. legacy method, document-scoped.

session context:

• agent_name: your identifier in the Motion workspace (e.g., "Claude"). appears in presence bar and comments.
• base_url: Motion MCP server endpoint (default: https://motion-mcp-server.fly.dev).

external connection:

• Motion workspace with MCP server running. requires network access to motion-mcp-server.fly.dev or your custom Motion deployment.

optional runtime context:

• document_id or page_id: target document UUID. if not provided, you create a workspace-only session first.
• mode: "suggest" (default, wraps edits in review marks) or "direct" (applies edits immediately).

procedure

initialization (one-time per conversation or task)

1. determine auth method. check if user provided agent_token or (invite_token + document_id).

   • input: user message, URL, or token strings.
   • output: normalized auth payload.

2. create session. POST to /sessions with agent_token or invite_token.

   • input: {"agent_token": "{TOKEN}", "agent_name": "Claude"} or {"invite_token": "{TOKEN}", "document_id": "{DOC_ID}", "agent_name": "Claude"}.
   • output: session_id (UUID), workspace_id, active connection status.
   • store session_id for all subsequent calls in this conversation.

3. optional: browse workspace without document. if using agent_token and no specific document yet:

   • input: session_id.
   • output: paginated list of pages (with titles, IDs, folder hierarchy), folders.
   • decision: show user the list and ask which document to edit, or create a new one.

document connection

4. connect to document (if not already connected during session creation).

   • input: session_id, document_id.
   • POST /sessions/{session_id}/connect with {"document_id": "{PAGE_ID}"}.
   • output: document metadata, block tree.

5. read document structure. GET /sessions/{session_id}/document.

   • input: session_id.
   • output: full document JSON (all blocks with stable UUIDs, marks, metadata).
   • store block IDs locally. these persist across concurrent edits.

editing workflow

6. choose edit operation based on user intent (insert, update, delete, format, find-and-replace, comment, version, export).

7. insert block (if adding content).

   • input: session_id, block type (paragraph, heading, list, callout, etc.), content, position (after_id or at_index).
   • POST /sessions/{session_id}/blocks with block JSON.
   • output: new block UUID, updated document tree.
   • note: send entire list as one insert call if building multi-item list.

8. format text (if changing style, bold, italic, links, etc.).

   • input: session_id, block_id, text string to match, format marks (bold, italic, link, code, etc.).
   • POST /sessions/{session_id}/blocks/{block_id}/format-by-match with {"match": "{TEXT}", "marks": [...], "mode": "suggest"}.
   • output: updated block with marks applied.
   • do not use character offsets; use exact text matching (handles nested blocks correctly).

9. delete block (if removing content).

   • input: session_id, block_id.
   • DELETE /sessions/{session_id}/blocks/{block_id}.
   • output: updated document tree.

10. find and replace (if making bulk text changes).

    • input: session_id, find string, replace string, optional occurrence number.
    • POST with find-and-replace payload.
    • output: count of replacements, updated blocks.

11. re-read document after edits if you need to continue editing or verify changes took effect.

    • input: session_id.
    • GET /sessions/{session_id}/document.
    • output: fresh document tree with all changes applied.

collaboration features

12. list comments (if reviewing discussion).

    • input: session_id.
    • GET /sessions/{session_id}/comments.
    • output: all comment threads with replies, resolved status, author.

13. create or reply to comment (if adding feedback).

    • input: session_id, optional block_id, comment text.
    • POST /sessions/{session_id}/comments with thread payload.
    • output: comment thread UUID, your identity as agent:Claude.

14. list suggestions (if reviewing pending edits from other agents or humans).

    • input: session_id.
    • GET /sessions/{session_id}/suggestions.
    • output: all pending suggestions (additions, deletions, replacements) with suggestion IDs, ranges, author.

15. accept or reject suggestion (if reviewing).

    • input: session_id, suggestion_id, action (accept or reject).
    • POST /sessions/{session_id}/suggestions/{suggestion_id}/accept or /reject.
    • output: suggestion marked accepted/rejected, document updated if accepted.

16. bulk suggestion operations (if clearing all pending).

    • input: session_id, bulk action (accept-all or reject-all).
    • POST to bulk endpoint.
    • output: all suggestions processed, document finalized.

page and folder management

17. create new page (if user asks to create a document).

    • input: session_id, title, optional folder_id, optional auto_connect: true.
    • POST /sessions/{session_id}/pages with {"title": "...", "auto_connect": true}.
    • output: new page UUID. if auto_connect, session is now connected to it.

18. rename page (if user asks to rename).

    • input: session_id, page_id, new title.
    • PATCH /sessions/{session_id}/pages/{page_id} with {"title": "..."}.
    • output: updated page metadata.

19. list pages (if user asks to see all pages).

    • input: session_id.
    • GET /sessions/{session_id}/pages.
    • output: paginated list of all workspace pages with folder info.

20. move page (if user asks to reorganize).

    • input: session_id, page_id, new folder_id, new position.
    • POST /sessions/{session_id}/pages/move with move payload.
    • output: updated page location.

21. delete page (if user asks to remove).

    • input: session_id, page_id.
    • DELETE /sessions/{session_id}/pages/{page_id}.
    • output: page marked deleted (soft delete), or hard deleted if requested.

22. restore page (if user asks to recover a deleted page).

    • input: session_id, page_id.
    • POST /sessions/{session_id}/pages/{page_id}/restore.
    • output: page restored.

version and export

23. save version (before making large changes).

    • input: session_id, optional version name.
    • POST /sessions/{session_id}/versions with {"name": "..."}.
    • output: version snapshot UUID, timestamp.

24. export document (if user asks to download or view as markdown/html).

    • input: session_id, format (markdown or html).
    • GET /sessions/{session_id}/export?format=markdown.
    • output: document content as plain text (markdown or html).

cleanup

25. disconnect session when task is complete (or user switches workspaces).
    • input: session_id.
    • DELETE /sessions/{session_id}.
    • output: session terminated, presence removed from workspace.

decision points

auth method branch:

• if user provided agent_token: use workspace-first flow (create session, list pages, connect on demand). preferred.
• if user provided invite_token + document_id only: skip workspace browsing, connect directly to the target document.
• if user provided Motion URL with /invite/ or /agent/: extract tokens from URL before creating session.
• if no auth provided: ask user for agent token or invite link. cannot proceed without one.

document scope branch:

• if user wants to browse workspace or create new pages: use workspace-level endpoints (list, create pages, folders). no document connection needed.
• if user wants to edit an existing document: connect to document first via step 4, then read structure via step 5.
• if user asks to switch documents mid-session: use POST /sessions/{session_id}/connect (step 4) rather than creating a new session.

edit mode branch:

• if user says "suggest" or "review" or "mark for approval": set "mode": "suggest" in all edit endpoints. edits appear as green underlines (additions) or strikethroughs (deletions).
• if user has explicit direct-edit permission or says "apply immediately" or "no review needed": set "mode": "direct". edits apply without suggestion marks.
• default to suggest mode unless user or workspace policy says otherwise.

concurrent editing branch:

• if user continues editing after a pause: re-read document (step 11) before making more changes. other users may have edited the same blocks. block IDs are stable, but content may have shifted.
• if you receive a 409 conflict or stale block ID error: re-read document and retry with fresh IDs.

empty or error branch:

• if list pages returns empty: workspace has no pages yet. offer to create one.
• if document read fails (404): target document does not exist or is not in your workspace. ask user to verify document_id or invite link.
• if suggest/accept endpoints return no suggestions: no pending reviews. confirm with user that all edits are finalized.
• if export fails (500): document may be too large or have unsupported block types. fall back to reading document JSON and converting manually.
• if session times out (401): token was revoked or expired. ask user to generate a new token and create a fresh session.

network/rate limit branch:

• if you receive 429 (too many requests): back off exponentially (wait 2s, 4s, 8s) before retrying.
• if you receive 503 (service unavailable): Motion MCP server is down. tell user to retry later or check status page.
• if you receive timeout after 30s: retry with smaller batch size (fewer blocks per insert, fewer characters per find-and-replace).

output contract

successful session creation:

• session_id (UUID string)
• workspace_id
• auth_status: "authenticated"

successful document read:

• document JSON with blocks array, each block containing:
  • id (UUID)
  • type (paragraph, heading, list, callout, etc.)
  • content (plain text or ProseMirror JSON)
  • marks (bold, italic, link, code, etc.)
  • metadata (created_at, updated_at, author)

successful edit operation:

• updated block(s) with new id, content, marks
• affected_block_ids array (for tracking changes)
• suggestion_id (if mode was suggest) or immediate confirmation (if direct)

successful comment operation:

• comment_id (UUID)
• thread_id
• author: "agent:Claude"
• timestamp

successful page/folder operation:

• page_id or folder_id (UUID)
• parent_folder_id
• position_in_folder
• title
• updated_at timestamp

successful version save:

• version_id (UUID)
• version_name (user-provided or auto-generated timestamp)
• created_at

successful export:

• content (markdown or html string)
• format_type (markdown or html)
• character_count, word_count (optional metadata)

all responses:

• error messages include error_code (e.g., WORKSPACE_MISMATCH, STALE_BLOCK_ID, AUTH_EXPIRED) and user-readable description.
• timestamps in ISO 8601 format (UTC).

outcome signal

the user knows the skill worked when:

1. session creation: you report back with a session_id and confirm "connected to Motion workspace {workspace_id}".

2. document read: you display the document structure in a readable format (outline of headings, blocks, etc.) and confirm "loaded X blocks from document {document_id}".

3. edits applied: you confirm "inserted {count} blocks", "formatted text in block {block_id}", or "deleted block {block_id}". if in suggest mode, you report "sent for review" and provide suggestion_id. if in direct mode, you say "applied immediately".

4. comments added: you confirm "comment posted as agent:Claude" and show the comment thread_id.

5. suggestions reviewed: you confirm "accepted {count} suggestions" or "rejected {count} suggestions" and show which blocks changed.

6. pages created or renamed: you confirm "created new page '{title}' with id {page_id}" or "renamed to '{new_title}'".

7. version saved: you confirm "saved version '{version_name}' at {timestamp}".

8. export complete: you return the markdown or html content and confirm "exported {character_count} characters".

9. document switch: you confirm "switched to document {new_document_id}" without creating a new session.

10. session ended: you confirm "disconnected from Motion. presence removed." when task is done.

11. visual confirmation in user's browser: user sees your agent name in the presence bar, sees suggestion marks appear (if suggest mode) or text updated live (if direct mode), and sees your comments or reactions in the discussion threads.