[Skill Submission] proof-collab

skills/proof-collab/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: proof-collab
+description: >
+  Collaborate on documents using Proof, Every's agent-native markdown editor.
+  Use this skill when a human shares a proofeditor.ai link, asks you to create
+  a Proof doc, leave comments, make suggestions, or do a bulk rewrite.
+  Invoke with: "put this in a Proof doc", "create a Proof doc", "leave a comment on [proofeditor.ai URL]", "suggest edits in Proof".
+tags: [writing, collaboration, documents, proof, every]
+---
+
+# Proof Collaboration
+
+Proof is Every's agent-native markdown editor. It tracks who wrote what (human vs AI) and lets agents collaborate through suggestions, comments, and rewrites — all via HTTP API.
+
+## Create a New Doc
+
+```bash
+curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg title "Doc Title" --arg markdown "# Content here" '{title: $title, markdown: $markdown}')"
+```
+
+Returns: `{shareUrl, slug, ownerSecret, accessToken}`
+
+Share URL format: `https://www.proofeditor.ai/d/<slug>`
+
+**Always write markdown to a temp file and use jq to build the JSON payload** — shell escaping breaks with inline heredocs for complex content.
+
+```bash
+# Recommended pattern for complex content:
+cat > /tmp/content.md << 'EOF'
+# Your Content Here
+...
+EOF
+CONTENT=$(cat /tmp/content.md)
+curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg title "Title" --arg markdown "$CONTENT" '{title: $title, markdown: $markdown}')"
+```
+
+## Read a Doc
+
+Given a URL like `https://www.proofeditor.ai/d/abc123`:
+
+```bash
+curl -s https://www.proofeditor.ai/api/agent/abc123/state
+```
+
+Returns `{content: "markdown..."}` — use `content` as source of truth, not `plainText`.
+
+## Edit a Doc (Ops)
+
+```bash
+curl -s -X POST https://www.proofeditor.ai/api/documents/abc123/ops \
+  -H "Content-Type: application/json" \
+  -d '{"type": "comment.add", "quote": "text to comment on", "text": "your comment", "by": "ai:your-name"}'
+```
+
+Always include `"by": "ai:<your-name>"` for attribution.
+
+### Supported op types
+
+- `comment.add` — leave a comment on specific text
+- `comment.reply` — reply to a comment thread
+- `comment.resolve` — resolve a comment thread
+- `suggestion.add` with `kind: "insert" | "delete" | "replace"` — tracked change suggestion
+- `suggestion.accept` / `suggestion.reject` — accept or reject a suggestion
+- `rewrite.apply` — bulk rewrite with automatic diff (use for large edits)
+
+### Rewrite (bulk edits)
+
+```json
+{
+  "type": "rewrite.apply",
+  "content": "# Full new markdown content here",
+  "by": "ai:your-name"
+}
+```
+
+Or use changes mode for targeted replacements:
+
+```json
+{
+  "type": "rewrite.apply",
+  "changes": [{"find": "old text", "replace": "new text"}],
+  "by": "ai:your-name"
+}
+```
+
+## Auth
+
+- Public docs: no token needed for comments/suggestions
+- Protected actions: `x-bridge-token: <ownerSecret>` or `Authorization: Bearer <accessToken>`
+
+## Safety Rules
+
+- Use `content` from `/state`, not `plainText`, as your source of truth
+- For table edits, update one cell at a time or use `rewrite.apply` with changes mode
+- Never edit the underlying markdown file directly — always use the API
+- `POST /share/markdown` is the canonical create route (not `/api/documents`, which is legacy)
+
+## Workflow Pattern
+
+1. Create doc → get `slug` and `shareUrl`
+2. Share the `shareUrl` with the human
+3. For later edits: `GET /api/agent/<slug>/state` to read, `POST /api/documents/<slug>/ops` to write
+4. Always attribute with `"by": "ai:<your-name>"`