From 9497ffcc5050d5a636c83c57a183598f12076d9d Mon Sep 17 00:00:00 2001
From: Vignesh Natarajan <vigneshnatarajan92@gmail.com>
Date: Sun, 18 Jan 2026 12:11:25 -0800
Subject: [PATCH] Add SKILL.md to teach Clawdbot when/how to use Lobster

---
 extensions/lobster/SKILL.md | 90 +++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 extensions/lobster/SKILL.md

diff --git a/extensions/lobster/SKILL.md b/extensions/lobster/SKILL.md
new file mode 100644
index 000000000..12c4f77ec
--- /dev/null
+++ b/extensions/lobster/SKILL.md
@@ -0,0 +1,90 @@
+# Lobster
+
+Lobster executes multi-step workflows with approval checkpoints. Use it when:
+
+- User wants a repeatable automation (triage, monitor, sync)
+- Actions need human approval before executing (send, post, delete)
+- Multiple tool calls should run as one deterministic operation
+
+## When to use Lobster
+
+| User intent | Use Lobster? |
+|-------------|--------------|
+| "Triage my email" | Yes — multi-step, may send replies |
+| "Send a message" | No — single action, use message tool directly |
+| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval |
+| "What's the weather?" | No — simple query |
+| "Monitor this PR and notify me of changes" | Yes — stateful, recurring |
+
+## Basic usage
+
+### Run a pipeline
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
+}
+```
+
+Returns structured result:
+```json
+{
+  "protocolVersion": 1,
+  "ok": true,
+  "status": "ok",
+  "output": [{ "summary": {...}, "items": [...] }],
+  "requiresApproval": null
+}
+```
+
+### Handle approval
+
+If the workflow needs approval:
+```json
+{
+  "status": "needs_approval",
+  "output": [],
+  "requiresApproval": {
+    "prompt": "Send 3 draft replies?",
+    "items": [...],
+    "resumeToken": "..."
+  }
+}
+```
+
+Present the prompt to the user. If they approve:
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Example workflows
+
+### Email triage
+```
+gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
+```
+Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
+
+### Email triage with approval gate
+```
+gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
+```
+Same as above, but halts for approval before returning.
+
+## Key behaviors
+
+- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
+- **Approval gates**: `approve` command halts execution, returns token
+- **Resumable**: Use `resume` action with token to continue
+- **Structured output**: Always returns JSON envelope with `protocolVersion`
+
+## Don't use Lobster for
+
+- Simple single-action requests (just use the tool directly)
+- Queries that need LLM interpretation mid-flow
+- One-off tasks that won't be repeated