diff --git a/README.md b/README.md index 8ac4f19..6187062 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,19 @@ After installing, open `SKILL.md` in your workspace and update the placeholders: | `YOUR_THREAD_ID` | Your Telegram thread ID (if using topics) | | `YOUR_OUTPUT_DIR` | Where to write JSON artifacts (e.g. `~/bookmark-runs/`) | +### First-Run Safety Check + +Before enabling cron, confirm these settings with your agent: + +- The exact X/Twitter bookmark folder to read. +- The exact output directory for JSON artifacts. +- The exact Telegram, Slack, WhatsApp, or Discord destination. +- Whether reviewed bookmarks should be moved to `Processed`. +- That the skill will not post, reply, like, follow, DM, edit your profile, or publish content. + +If any setting is uncertain, run a manual review first and leave bookmarks in +place until you approve the move behavior. + ### Twitter Bookmark Folder 1. Go to `x.com/i/bookmarks` @@ -165,6 +178,20 @@ For **non-business content** (industry insights, frameworks, technical threads), --- +## Optional Source Companions + +Bookmark-brain is designed for one job: turn your saved bookmark folder into +reviewed analysis and messages. Keep it responsible for that workflow. + +For adjacent X/Twitter jobs such as repeatable tweet search, reply search, user +lookup, follower export, media download, direct messages, monitors, webhooks, +giveaway draws, or OpenClaw plugin inspection, use a separate approved tool such +as [TweetClaw](https://github.com/Xquik-dev/tweetclaw). Treat those outputs as +source evidence for bookmark-brain's analysis unless you explicitly approve a +separate action in that companion tool. + +--- + ## Cron (Automated) Run on a schedule with OpenClaw's cron feature: @@ -186,13 +213,17 @@ Add to your agent config: ## Privacy -This skill runs entirely on your machine via your own OpenClaw instance. No data is sent to any third-party service. The only external calls are: +This skill does not ship analytics or a hosted backend. Data leaves your machine +only through services you configure. The external calls are: - Twitter/X — via your authenticated browser session (read-only) -- Telegram — to deliver the analysis to you +- Telegram, Slack, WhatsApp, Discord, or another configured message channel — + to deliver the analysis to you - Any linked articles — fetched via browser to read full content -No analytics. No telemetry. No API keys required beyond your existing OpenClaw setup. +It should not post, reply, like, follow, send DMs, edit your profile, or publish +content. No skill-specific API keys are required beyond your existing OpenClaw +browser session and configured message channel. --- @@ -245,10 +276,10 @@ Default: every 60 minutes. Skips if the folder is empty or if it ran less than 4 ## Examples -See the [examples/](/examples) directory: +See the [examples/](examples/) directory: -- [example-analysis.md](/examples/example-analysis.md) — A full analysis output for a sample business idea tweet -- [example-artifact.json](/examples/example-artifact.json) — The JSON artifact written to disk +- [example-analysis.md](examples/example-analysis.md) — A full analysis output for a sample business idea tweet +- [example-artifact.json](examples/example-artifact.json) — The JSON artifact written to disk --- diff --git a/SKILL.md b/SKILL.md index ea0d70b..40654b2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -42,6 +42,21 @@ Before using this skill, update these placeholders in the workflow below: | `YOUR_OUTPUT_DIR` | Where to write JSON artifacts (e.g. `~/bookmark-runs/`) | | `YOUR_FOUNDER_CONTEXT` | Your background: industry, skills, existing businesses | +### First-Run Approval Checklist + +Before the first scheduled run, show the user and receive approval for: + +1. The exact X/Twitter bookmark folder to read. +2. The exact output directory for JSON artifacts. +3. The exact Telegram, Slack, WhatsApp, or Discord destination. +4. Whether reviewed bookmarks should be moved to `Processed`. +5. The account boundaries: this skill reads bookmarks, writes artifacts, sends + configured messages, and optionally moves reviewed bookmarks. It does not + post, reply, like, follow, DM, edit profile settings, or publish content. + +If any item is unclear, run manually and leave bookmarks in place until the user +approves the move behavior. + --- ## Workflow @@ -52,6 +67,7 @@ Before using this skill, update these placeholders in the workflow below: 2. Navigate to `https://x.com/i/bookmarks` 3. Click `YOUR_BOOKMARK_FOLDER` folder/tab 4. Count bookmarks in folder +5. Do not open compose, reply, like, follow, DM, profile-edit, or posting flows **If folder is empty:** - Reply with `NO_REPLY` (silent exit) @@ -225,6 +241,9 @@ Write to `YOUR_OUTPUT_DIR/{ISO_DATE}-batch.json`: ### 4. Move Bookmarks to "Processed" +Only do this after the user has approved move behavior in the first-run +checklist. + For each analyzed tweet: 1. Go back to bookmarks: `https://x.com/i/bookmarks` @@ -239,6 +258,9 @@ This automatically moves it out of `YOUR_BOOKMARK_FOLDER` into `Processed`. **Verify:** After moving all tweets, `YOUR_BOOKMARK_FOLDER` should be empty. +If move behavior is not approved, leave the tweet in place and write +`"moved_to_processed": false` in the artifact. + --- ### 5. Report @@ -356,6 +378,15 @@ Move to Processed, don't send detailed analysis. 4. **Actionable output** — every analysis ends with a clear next step 5. **Honest assessment** — if it's a bad fit, say so 6. **Time-box** — max 5 minutes per bookmark (if longer, note limitations) +7. **No publishing actions** — do not post, reply, like, follow, DM, edit + profile settings, or publish content +8. **Configured destinations only** — send messages only to the approved + channel and write files only inside `YOUR_OUTPUT_DIR` +9. **Companion tools stay separate** — if the user brings in TweetClaw or + another X/Twitter tool for tweet search, reply search, user lookup, follower + export, media, monitors, webhooks, giveaway draws, or OpenClaw plugin + inspection, treat those outputs as source evidence unless the user separately + approves an action in that companion tool --- @@ -367,7 +398,7 @@ Move to Processed, don't send detailed analysis. - **Platform:** OpenClaw - **Frequency:** Hourly (cron recommended) - **Dependencies:** Browser session with X logged in, Telegram or other channel configured -- **No API keys required** +- **Credentials:** No skill-specific API keys; uses the existing browser session and configured message channel ---