proof_skill

Overview

This skill integrates with Proof to create, edit, comment on, and share collaborative Markdown documents via Proof's web API and local macOS bridge. It streamlines creating shareable docs, reading document state, adding comments, suggesting edits, and performing bulk rewrites. Use the web API for easy sharing and the local bridge to drive a running Proof.app instance for richer presence and mark operations.

How this skill works

The skill calls Proof's web endpoints to create a shared document and returns a tokenized shareable URL. It reads document state from the /api/agent/{slug}/state endpoint and posts operations to /api/agent/{slug}/ops (comments, suggestions, rewrites) using the provided token. For macOS, it can call the local bridge at localhost:9847 with required headers to list windows, read state, suggest marks, reply, resolve, accept, reject, and push full rewrites.

When to use it

• When asked to "proof", review, or suggest edits to a Markdown document.
• When you need to create and share a collaborative document with a single API call.
• When given a proofeditor.ai URL and you must extract slug and token to operate.
• When driving a local Proof.app on macOS to create presence, suggestions, or accept/reject marks.
• When you want real-time comments and suggestions that authors see immediately.

Best practices

• Use the web /api/agent/{slug}/ops endpoint (not /api/documents/{slug}/ops) for edits and comments.
• Always read /state before making changes; treat it as the source of truth.
• Include the by field (e.g., "ai:your-agent") for attribution on comments and suggestions.
• Prefer suggestion.replace for insert-like changes or use rewrite.apply for larger rewrites.
• For bridge endpoints include required client headers and presence headers when needed.

Example use cases

• Create a draft report and return a tokenized share URL so collaborators can view and edit.
• Review a shared proofeditor.ai document URL: extract slug/token, read state, add inline comments.
• Suggest replacements for unclear sentences using suggestion.add with kind: replace.
• Drive a local Proof.app to insert suggestions, post replies, resolve comments, and set presence.
• Apply a bulk markdown rewrite for a full-structure update using rewrite.apply or /rewrite on the bridge.