Skip to content

docs: clarify bookmark review safety boundaries #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kriptoburak wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify bookmark review safety boundaries #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 37 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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:
Expand All @@ -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.

---

Expand Down Expand Up @@ -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

---

Expand Down
33 changes: 32 additions & 1 deletion SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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`
Expand All @@ -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
Expand Down Expand Up @@ -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

---

Expand All @@ -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

---

Expand Down