X Bookmarks Archiver

Fetch your X bookmarks, auto-categorize by URL, generate AI summaries, and save organized markdown archives in your OpenClaw workspace.

Security Scan

The skill's code and instructions match its stated purpose (archiving X bookmarks), request only an optional OpenAI key, and perform local file writes and network requests that are consistent with that purpose, though there are a few small implementation inconsistencies you should be aware of before installing.

Purpose & Capability

Name/behavior align: scripts fetch X bookmarks via the bird CLI, categorize them, optionally call OpenAI to generate summaries, and write markdown files into an OpenClaw workspace. The required binaries and optional OPENAI_API_KEY are appropriate for this functionality.

Instruction Scope

Runtime instructions and scripts stay within the stated purpose (fetch → process → write markdown). The code performs network HEAD requests to bookmarked URLs (expandUrl) and POSTs to api.openai.com when OPENAI_API_KEY is present; these network calls are expected here but mean the tool will contact arbitrary bookmarked hosts and OpenAI. The scripts read and write files in the user's home directories (workspace and state).

Install Mechanism

No install spec — skill is instruction-plus-source included in the bundle. There are no downloads or external installers invoked by the skill itself. All code is included in the package.

Credentials

The skill only requires an optional OPENAI_API_KEY for AI summaries and allows overriding workspace via OPENCLAW_WORKSPACE and OPENCLAW_PROFILE. However, the state code accepts X_BOOKMARK_STATE_DIR (used to set where pending/processed JSON live) but this env var is not documented in SKILL.md. Also SKILL.md and code disagree on legacy vs dot-prefixed state/workspace paths (e.g., ~/clawd vs ~/.clawd), which is an implementation inconsistency but not a secret-exfiltration risk.

Persistence & Privilege

The skill does not request always:true or other elevated platform privileges. It writes its own state/markdown files under user-owned directories and does not attempt to modify other skills or system-wide configs.

Assessment

This appears to be a genuine X bookmarks archiver. Before installing or running: 1) Inspect and (optionally) run the tests in an isolated/temp directory to verify behavior. 2) Be aware the tool will: run the local bird CLI (so bird must be installed and authenticated), perform HEAD requests to each bookmarked URL (which will contact arbitrary hosts and could reach internal resources if such URLs exist), and call api.openai.com when OPENAI_API_KEY is set. 3) If you prefer output and state in safe locations, set OPENCLAW_WORKSPACE and X_BOOKMARK_STATE_DIR to directories you control (the latter is supported by the code but not documented in SKILL.md). 4) Note the small path inconsistencies (SKILL.md mentions ~/clawd while state.cjs uses ~/.clawd); verify the actual directories used on your machine. 5) Only provide an OPENAI_API_KEY if you want AI summaries; otherwise the tool will fall back to simple metadata. If you plan to allow autonomous agent invocation, remember this skill will perform network requests and write files — grant only if you trust it to act on your behalf.

X Bookmark Archiver

Archive your X (Twitter) bookmarks into categorized markdown files with AI-generated summaries.

Overview

This skill fetches your X bookmarks using the bird CLI, categorizes them by URL patterns, generates AI summaries using OpenAI, and saves them as organized markdown files.

Prerequisites

1. bird CLI - Install from steipete/bird
2. OpenAI API Key (optional) - Set OPENAI_API_KEY for AI-generated summaries
3. Node.js 18+

Installation

# Ensure bird CLI is installed and authenticated
bird --version

# Set OpenAI API key (optional, for AI summaries)
export OPENAI_API_KEY="sk-..."

Commands

run - Full Pipeline

Fetches new bookmarks and processes them:

node skills/x-bookmark-archiver/scripts/run.cjs

run --force - Process Existing

Skip fetch, process only pending bookmarks:

node skills/x-bookmark-archiver/scripts/run.cjs --force

fetch - Download Bookmarks Only

node skills/x-bookmark-archiver/scripts/fetch.cjs

process - Archive Pending Only

node skills/x-bookmark-archiver/scripts/process.cjs

Category Mapping

Bookmarks are automatically categorized based on URL patterns:

Category	Domains
tools	github.com, gitlab.com, github.io, huggingface.co, replicate.com, vercel.com, npmjs.com, pypi.org
articles	medium.com, substack.com, dev.to, hashnode.dev, x.com/i/article, blog.*, towardsdatascience.com
videos	youtube.com, youtu.be, vimeo.com, twitch.tv
research	arxiv.org, paperswithcode.com, semanticscholar.org, researchgate.net, dl.acm.org, ieee.org
news	techcrunch.com, theverge.com, hn.algolia.com, news.ycombinator.com, wired.com, arstechnica.com
bookmarks	fallback for unmatched URLs

Output Location

Markdown files are created in the OpenClaw workspace at:

Legacy installs (old name):

~/clawd/X-knowledge/

New installs:

~/.openclaw/workspace/X-knowledge/

With profile (OPENCLAW_PROFILE=prod):

~/.openclaw/workspace-prod/X-knowledge/

Override with environment variable:

export OPENCLAW_WORKSPACE=/custom/path
node skills/x-bookmark-archiver/scripts/run.cjs
# Creates: /custom/path/X-knowledge/

Output Structure

~/.openclaw/workspace/X-knowledge/
├── tools/
│   ├── awesome-ai-project.md
│   └── useful-cli-tool.md
├── articles/
│   ├── how-to-build-x.md
│   └── ml-best-practices.md
├── videos/
│   └── conference-talk.md
├── research/
│   └── attention-is-all-you-need.md
├── news/
│   └── latest-tech-announcement.md
└── bookmarks/
    └── misc-link.md

Markdown Template

Each archived bookmark gets a markdown file with frontmatter:

---
title: "Awesome AI Project"
type: tool
date_archived: 2026-01-31
source_tweet: https://x.com/i/web/status/1234567890
link: https://github.com/user/repo
tags: ["ai", "machine-learning", "github"]
---

This project implements a novel approach to... (AI-generated summary)

State Management

State files track processing progress:

/root/clawd/.state/
├── x-bookmark-pending.json     # Bookmarks waiting to be processed
└── x-bookmark-processed.json   # IDs of already-archived bookmarks

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	No	API key for AI-generated summaries

Workflow

1. Fetch: Downloads latest 50 bookmarks from X
2. Filter: Removes already-processed bookmarks
3. Expand: Resolves t.co shortened URLs
4. Categorize: Assigns category based on URL domain
5. Enrich: Generates title, summary, tags (AI or fallback)
6. Write: Saves as markdown in X-knowledge/{category}/
7. Track: Updates processed IDs, clears pending

Customization

Adding Categories

Edit scripts/lib/categorize.cjs:

const CATEGORIES = {
  tools: ['github.com', '...'],
  your_category: ['example.com', '...'],
  // ...
};

Changing Output Directory

Edit scripts/process.cjs:

const KNOWLEDGE_DIR = 'your-directory-name';

Using Different AI Provider

Modify the generateMetadata() function in scripts/process.cjs to use your preferred API.

Testing

Run the test suite:

# Run all tests
cd skills/x-bookmark-archiver/tests
node test-all.cjs

# Run individual test suites
node lib/categorize.test.cjs
node lib/state.test.cjs
node integration.test.cjs

Test Coverage

• Unit tests: categorize.js (21 tests) - URL pattern matching
• Unit tests: state.js (9 tests) - JSON read/write operations
• Integration tests (12 tests) - Full pipeline with mock data

Manual Testing

Without bird CLI, you can test with mock data:

# Create mock pending data
cat > /tmp/test-pending.json << 'EOF'
[
  {
    "id": "test123",
    "url": "https://github.com/test/repo",
    "text": "Test bookmark"
  }
]
EOF

# Copy to state directory and process
mkdir -p /root/clawd/.state
cp /tmp/test-pending.json /root/clawd/.state/x-bookmark-pending.json
node skills/x-bookmark-archiver/scripts/process.cjs

Troubleshooting

Issue	Solution
bird: command not found	Install bird CLI from GitHub releases
No bookmarks fetched	Ensure you're logged into X in bird
AI summaries not generating	Check OPENAI_API_KEY is set
t.co links not expanding	May be network/timeout issues; will use original URL

File Structure

skills/x-bookmark-archiver/
├── SKILL.md
├── scripts/
│   ├── fetch.cjs          # Download bookmarks from X (CommonJS)
│   ├── process.cjs        # Generate markdown files (CommonJS)
│   ├── run.cjs            # Orchestrate fetch → process (CommonJS)
│   └── lib/
│       ├── categorize.cjs # URL → category mapping (CommonJS)
│       └── state.cjs      # JSON state management (CommonJS)
└── tests/
    ├── test-all.cjs
    ├── lib/
    │   ├── categorize.test.cjs
│   │   └── state.test.cjs
    ├── integration.test.cjs
    └── fixtures/
        └── sample-bookmarks.json

License

MIT