X Bookmarks

Fetch, summarize, and manage X/Twitter bookmarks via bird CLI or X API v2. Use when: (1) user says "check my bookmarks", "what did I bookmark", "bookmark dig...

Security Scan

The skill's code and runtime instructions match its stated purpose (fetching and summarizing X/Twitter bookmarks via bird CLI or the X API); it requires local credentials (browser cookies or OAuth tokens) which are plausible for this function — but note metadata mismatches and review token handling before installing.

Purpose & Capability

The skill's name/description (X Bookmarks) aligns with the included scripts and workflows: a bird CLI wrapper, an X API v2 fetcher, and an OAuth helper. However, the registry metadata at the top of the package claims no required env vars, binaries, or config paths while SKILL.md and the scripts explicitly document AUTH_TOKEN/CT0, optional X_API_BEARER_TOKEN, the bird binary, and ~/.config/x-bookmarks/tokens.json — an internal inconsistency the user should be aware of.

Instruction Scope

SKILL.md and the scripts confine actions to fetching bookmarks (via bird or X API), categorizing them, and storing local state/tokens. The OAuth helper runs a local HTTP callback and opens the browser (normal for PKCE). There are no instructions to read unrelated system files or transmit credentials to unexpected third parties; network calls go to X endpoints (api.x.com / x.com) as expected.

Install Mechanism

There is no automated install spec in the package (instruction-only with scripts included), so nothing is automatically downloaded or executed during install. The only external install suggested is installing bird-cli from npm, which is a normal third-party dependency. No unusual download URLs or archive extraction are present.

Credentials

The package reasonably needs authentication credentials to read private bookmarks: either browser cookie values (AUTH_TOKEN and CT0) for bird CLI or OAuth tokens / bearer token for the X API. These credentials are sensitive but proportionate to the stated functionality. Again note the registry metadata incorrectly lists no required env vars while SKILL.md requires them. Tokens are saved locally to ~/.config/x-bookmarks/tokens.json (file is created with mode 0o600 in the code).

Persistence & Privilege

The skill stores its own config and tokens under ~/.config/x-bookmarks and runs a short-lived local HTTP server during OAuth authorization; it does not request persistent platform-wide privileges nor set always:true. Storing tokens locally (with restrictive file perms) is normal for this workflow.

Assessment

This package appears to do what it says, but take these precautions before installing: - Source verification: the skill's source/homepage is unknown and the registry metadata contradicts SKILL.md. Only install if you trust the publisher or have reviewed the scripts. - Prefer OAuth over manual cookie copying: use the provided x_api_auth.py flow (OAuth PKCE) rather than manually extracting/pasting auth_token and ct0 — copying cookies is sensitive and error-prone. - Review local storage: tokens are written to ~/.config/x-bookmarks/tokens.json (the code sets 0o600). Make sure you’re comfortable storing tokens on this machine and check file ownership/permissions. - Inspect scripts: the included scripts are small and call only bird or X API endpoints; if unsure, read them yourself or run in an isolated environment (VM/container) first. - Validate bird-cli source: if you use the bird path, ensure you install bird-cli from its official repo/npm package and understand that it accesses browser cookie stores. - Cron/automation: scheduled digests imply storing last-processed IDs in workspace/state — confirm where that state will be stored and secure it if it contains tokens or identifiers. If you want higher assurance, ask the publisher for a verified homepage or run the tools locally (inspect source and run only the Python scripts you reviewed).

X Bookmarks v2

Turn X/Twitter bookmarks from a graveyard of good intentions into actionable work.

Core philosophy: Don't just summarize — propose actions the agent can execute.

Data Source Selection

This skill supports two backends. Pick the first one that works:

1. bird CLI (preferred if available)

• Fast, no API key needed, uses browser cookies
• Install: npm install -g bird-cli
• Test: bird whoami — if this prints a username, you're good

2. X API v2 (fallback)

• Works without bird CLI
• Requires an X Developer account + OAuth 2.0 app
• Setup: see references/auth-setup.md → "X API Setup"

Auto-detection logic

1. Check if `bird` command exists → try `bird whoami`
2. If bird works → use bird CLI path
3. If not → check for X API tokens (~/.config/x-bookmarks/tokens.json)
4. If tokens exist → use X API path (auto-refresh)
5. If neither → guide user through setup (offer both options)

Fetching Bookmarks

Via bird CLI

# Latest 20 bookmarks (default)
bird bookmarks --json

# Specific count
bird bookmarks -n 50 --json

# All bookmarks (paginated)
bird bookmarks --all --json

# With thread context
bird bookmarks --include-parent --thread-meta --json

# With Chrome cookie auth
bird --chrome-profile "Default" bookmarks --json

# With manual tokens
bird --auth-token "$AUTH_TOKEN" --ct0 "$CT0" bookmarks --json

If user has a .env.bird file or env vars AUTH_TOKEN/CT0, source them first: source .env.bird

Via X API v2

# First-time setup (opens browser for OAuth)
python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_SECRET"

# Fetch bookmarks (auto-refreshes token)
python3 scripts/fetch_bookmarks_api.py -n 20

# All bookmarks
python3 scripts/fetch_bookmarks_api.py --all

# Since a specific tweet
python3 scripts/fetch_bookmarks_api.py --since-id "1234567890"

# Pretty print
python3 scripts/fetch_bookmarks_api.py -n 50 --pretty

The API script outputs the same JSON format as bird CLI, so all downstream workflows work identically.

Token management is automatic: tokens are stored in ~/.config/x-bookmarks/tokens.json and refreshed via the saved refresh_token. If refresh fails, the agent should guide the user to re-run x_api_auth.py.

Environment variable override

If the user already has a Bearer token (e.g., from another tool), they can skip the OAuth dance:

X_API_BEARER_TOKEN="your_token" python3 scripts/fetch_bookmarks_api.py -n 20

JSON Output Format (both backends)

Each bookmark returns:

{
  "id": "tweet_id",
  "text": "tweet content",
  "createdAt": "2026-02-11T01:00:06.000Z",
  "replyCount": 46,
  "retweetCount": 60,
  "likeCount": 801,
  "bookmarkCount": 12,
  "viewCount": 50000,
  "author": { "username": "handle", "name": "Display Name" },
  "media": [{ "type": "photo|video", "url": "..." }],
  "quotedTweet": { "id": "..." }
}

Core Workflows

1. Action-First Digest (Primary Use Case)

The key differentiator: don't just summarize, propose actions the agent can execute.

1. Fetch bookmarks (bird or API, auto-detected)
2. Parse and categorize by topic (auto-detect: crypto, AI, marketing, tools, personal, etc.)
3. For EACH category, propose specific actions:
   • Tool/repo bookmarks → "I can test this, set it up, or analyze the code"
   • Strategy/advice bookmarks → "Here are the actionable steps extracted — want me to implement any?"
   • News/trends → "This connects to [user's work]. Here's the angle for content"
   • Content ideas → "This would make a great tweet/video in your voice. Here's a draft"
   • Questions/discussions → "I can research this deeper and give you a summary"
4. Flag stale bookmarks (>2 weeks old) — "Use it or lose it"
5. Deliver categorized digest with actions

Format output as:

📂 CATEGORY (count)
• Bookmark summary (@author)
→ 🤖 I CAN: [specific action the agent can take]

2. Scheduled Digest (Cron)

Set up a recurring bookmark check. Suggest this cron config to the user:

Schedule: daily or weekly
Payload: "Check my X bookmarks for new saves since last check.
  Fetch bookmarks, compare against last digest, summarize only NEW ones.
  Categorize and propose actions. Deliver to me."

Track state by saving the most recent bookmark ID processed. Store in workspace: memory/bookmark-state.json → { "lastSeenId": "...", "lastDigestAt": "..." }

3. Content Recycling

When user asks for content ideas from bookmarks:

1. Fetch recent bookmarks
2. Identify high-engagement tweets (>500 likes) with frameworks, tips, or insights
3. Rewrite key ideas in the user's voice (if voice data available)
4. Suggest posting times based on the bookmark's original engagement

4. Pattern Detection

When user has enough bookmark history:

1. Fetch all bookmarks (--all)
2. Cluster by topic/keywords
3. Report: "You've bookmarked N tweets about [topic]. Want me to go deeper?"
4. Suggest: research reports, content series, or tools based on patterns

5. Bookmark Cleanup

For stale bookmarks:

1. Identify bookmarks older than a threshold (default: 30 days)
2. For each: extract the TL;DR and one actionable takeaway
3. Present: "Apply it today or clear it"
4. User can unbookmark via: bird unbookmark <tweet-id> (bird only)

Error Handling

Error	Cause	Fix
bird: command not found	bird CLI not installed	Use X API path instead, or npm i -g bird-cli
"No Twitter cookies found"	Not logged into X in browser	Log into x.com in Chrome/Firefox, or use X API
EPERM on Safari cookies	macOS permissions	Use Chrome/Firefox or X API instead
Empty results	Cookies/token expired	Re-login or re-run x_api_auth.py
Rate limit (429)	Too many API requests	Wait and retry, use --count to limit
"No X API token found"	Haven't run auth setup	Run x_api_auth.py --client-id YOUR_ID
Token refresh failed	Refresh token expired	Re-run x_api_auth.py to re-authorize

Tips

• Start with -n 20 for quick digests, --all for deep analysis
• bird: Use --include-parent for thread context on replies
• API: includes bookmarkCount and viewCount (bird may not)
• Bookmark folders supported via bird --folder-id <id>
• Both backends output identical JSON — workflows are backend-agnostic