# x-likes-digest

Adopt this skill: https://proskills.md/skills/other/nmn-labs-x-likes-digest

Page: https://proskills.md/skills/other/nmn-labs-x-likes-digest
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8130
upstream: https://github.com/nmn-labs/x-likes-digest/blob/HEAD/SKILL.md

````text
---
name: x-likes-digest
description: >-
  Daily digest of X (Twitter) liked posts with AI-powered categorization, summarization, and personalized recommendations.
  Use when: (1) setting up automated daily X likes digests, (2) generating categorized summaries of liked tweets,
  (3) building interest-based tweet recommendations from like history, (4) delivering curated content digests to Telegram/Discord/Slack channels.
  Supports two modes: digest (collect→categorize→summarize→deliver) and recommend (feedback→search→score→deliver).
  Requires: twitterapi.io API key, a VPS/server running the x-likes-digest data collector, SSH access, and a Telegram bot.
---

# X Likes Digest

Automated daily digest of X (Twitter) liked posts with AI categorization and personalized recommendations.

## Architecture

```
X Official API → Collector (VPS, cron) → SQLite DB
                                            ↓
twitterapi.io (article/search) ←→ OpenClaw Agent (this skill)
                                            ↓
                                   Telegram / LINE delivery
```

- **Data collector**: Node.js app on an always-on machine (VPS, home server, or local), exports new likes via `export-data.ts`
- **This skill**: Agent-side processing — categorization, summarization, image handling, recommendation, delivery

## Prerequisites

1. **Always-on machine with x-likes-digest collector deployed** — VPS (recommended), home server, or a Mac/PC that stays powered on. See `references/setup-guide.md`
2. **twitterapi.io API key** — stored in env var `$TWITTERAPI_KEY` on the collector machine
3. **Telegram bot** — with access to target channel
4. **Access to collector DB** — either via SSH (remote) or direct file path (local)

### Deployment Options

| Setup | Collector runs on | Agent accesses DB via | `ssh_host` | `local_db_path` |
|-------|-------------------|----------------------|------------|-----------------|
| **Remote (VPS)** | VPS / cloud server | SSH | Required | — |
| **Local** | Same machine as OpenClaw | Direct file path | — | Required |

- **Remote (recommended)**: Collector runs 24/7 on a VPS. Agent uses SSH to read the DB and run export scripts. Set `ssh_host` and `vps_project_path`.
- **Local**: Collector runs on the same machine as OpenClaw. No SSH needed. Set `local_db_path` to the absolute path of your collector directory instead of `ssh_host`/`vps_project_path`.

> ⚠️ The collector needs to run daily (via system cron or similar). If your machine sleeps or shuts down, likes won't be collected for that day.

## Configuration

Set these in your cron job or pass as context:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `ssh_host` | SSH alias for remote server (remote mode) | `your-server` |
| `vps_project_path` | Path to collector on remote server (remote mode) | `/home/user/projects/x-likes-digest` |
| `local_db_path` | Absolute path to collector directory (local mode) | `/Users/you/x-likes-digest-collector` |
| `telegram_channel_id` | Telegram channel for delivery | `-100xxxxxxxxxx` |
| `twitterapi_key` | twitterapi.io API key (use env var) | `$TWITTERAPI_KEY` |
| `delivery_channels` | Target channels (optional) | `["telegram"]` or `["telegram", "discord", "slack"]` |
| `discord_channel_id` | Discord channel ID (if Discord enabled) | `1234567890` |
| `slack_channel_id` | Slack channel (if Slack enabled) | `#digest` |
| `line_user_id` | LINE User ID (⚠️ LINE delivery not yet stable) | `Uxxxx` |
| `recommend_count` | Number of recommendations | `12` |
| `categories` | Custom category list (optional, see below) | `[{emoji, name, criteria}]` |

### Category Modes

**Default: Auto-categorize (no `categories` set)**

The agent analyzes post content and automatically assigns categories based on the actual topics found.
Rules for auto-categorization:
- Analyze all posts first, then identify 5–10 natural groupings
- Each category gets an appropriate emoji and short label
- X Articles (`x.com/i/article/` format) are always a separate 📝 category
- NSFW detection (from Step 4) always creates a 🈲 category if applicable
- Avoid "Other" — every post should fit a meaningful category
- Keep category names concise (2–3 words max)

**Custom: Fixed categories (`categories` set)**

When `categories` is provided in config, use the specified categories instead of auto-detection.

Format:
```json
[
  {"emoji": "💰", "name": "Crypto / Web3", "criteria": "Cryptocurrency, blockchain, DeFi, trading"},
  {"emoji": "🤖", "name": "AI / Tech", "criteria": "AI, programming, tools, automation"},
  {"emoji": "📦", "name": "Other", "criteria": "Everything else"}
]
```

Posts that don't match any custom category go to the last entry (typically "Other").

## ⚠️ API Cost Safety

twitterapi.io is a **paid API** (~$0.015/request). To avoid accidental overspending:

1. **Always check unique count first** — After fetching page 1, verify the number of unique tweet IDs. If duplicates exceed 50%, stop pagination immediately.
2. **Set max pages** — Never paginate beyond 5 pages in a single run. If more data is needed, process across multiple days.
3. **Prefer `last_tweets` over `advanced_search`** — `last_tweets` is cheaper and sufficient for like collection.
4. **Monitor cursor values** — If the same `next_cursor` is returned twice, stop immediately (infinite loop).
5. **Test with small batches** — When modifying search queries, always test with 1 page first and verify results before running full collection.

Lesson learned: A pagination bug once consumed $9 in API credits by fetching the same data 6,500+ times. Always validate before scaling.

## Cron Setup

Two cron jobs, one skill. Example OpenClaw cron commands:

```bash
# Digest — daily at 8:30 JST
openclaw cron add --name x-likes-digest \
  --schedule "30 8 * * *" --tz Asia/Tokyo \
  --message "Run x-likes-digest skill in digest mode. Config: ssh_host=your-server, vps_project_path=/home/user/projects/x-likes-digest, telegram_channel_id=-100xxx, delivery_channels=[telegram]" \
  --channel telegram --timeout 900

# Recommend — daily at 8:45 JST
openclaw cron add --name x-likes-digest-recommend \
  --schedule "45 8 * * *" --tz Asia/Tokyo \
  --message "Run x-likes-digest skill in recommend mode. Config: ssh_host=your-server, vps_project_path=/home/user/projects/x-likes-digest, telegram_channel_id=-100xxx, recommend_count=12, delivery_channels=[telegram]" \
  --channel telegram --timeout 600
```

> 💡 **Tip:** If the cron agent can't locate SKILL.md, replace the `--message` with the full step-by-step procedure. See "Cron Message Best Practice" below.

### Cron Message Best Practice

⚠️ **Cron sessions may not find SKILL.md** — OpenClaw cron sessions run in isolated contexts and may fail to locate skill files on disk. If your cron session repeatedly fails to follow the skill steps or falls back to running VPS scripts directly:

**Recommended: Embed the full procedure in the cron message itself.**

Instead of "Run x-likes-digest skill in digest mode", write the complete step-by-step instructions directly in the `--message` field. This ensures the agent follows the correct procedure regardless of skill file discovery.

See the [OpenClaw cron docs](https://docs.openclaw.ai/cli/cron) for message formatting tips.

---

## Mode: Digest

Execute steps 1–6 in order. No skipping.

### Step 1: Data Export

**Remote mode** (when `ssh_host` is set):
```bash
ssh {ssh_host} "cd {vps_project_path} && npx tsx src/export-data.ts 2>/dev/null"
```

**Local mode** (when `local_db_path` is set):
```bash
cd {local_db_path} && npx tsx src/export-data.ts 2>/dev/null
```

Check `new_likes_count`:
- **0**: Send "本日の新しいいいねはありません" and stop
- **1–30**: Normal mode (full processing)
- **31–60**: Split mode (oldest 30 only, remainder tomorrow)
- **61+**: Light mode (skip web_fetch/image analysis, text-only summaries)

### Step 2: Article Retrieval (skip in light mode)

For posts where text is only `https://t.co/...` or under 50 chars with URL 
````

## File: README.md
upstream: https://github.com/nmn-labs/x-likes-digest/blob/HEAD/README.md

````text
# X Likes Digest

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node 20+](https://img.shields.io/badge/Node-20%2B-brightgreen.svg)](https://nodejs.org/)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-skill-blue.svg)](https://github.com/openclaw/openclaw)

**AI-powered daily digest and personalized recommendations for your X (Twitter) likes.**

Automatically collects your liked tweets, categorizes and summarizes them with an LLM, and delivers a curated digest plus smart recommendations to Telegram, Discord, or Slack — every day.

---

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                        Architecture                         │
│                                                             │
│   X Official API                                            │
│        │                                                    │
│        ▼                                                    │
│   Collector (VPS/local, cron)                               │
│        │  npm run collect                                   │
│        ▼                                                    │
│   SQLite DB  ←──────────── npm run export                  │
│        │                                                    │
│        ▼                                                    │
│   OpenClaw Agent  (SKILL.md)                                │
│        │  categorize · summarize · score · recommend        │
│        ▼                                                    │
│   Telegram / Discord / Slack                                │
└─────────────────────────────────────────────────────────────┘
```

**Two components:**

| Component | What it does | Where it runs |
|-----------|-------------|---------------|
| **Collector** (`src/`) | Fetches liked tweets from X API, stores in SQLite | VPS or local server (always-on) |
| **OpenClaw Skill** (`SKILL.md`) | LLM categorization, summarization, recommendations, delivery | OpenClaw agent |

---

## Key Features

- **🗂 Auto-categorization** — LLM groups posts into natural topic clusters (AI, Crypto, Dev Tools, etc.). Custom categories supported.
- **📝 Smart summarization** — Full article extraction for X Articles and external links. Detailed summaries, not just titles.
- **🧠 LLM interest profiling** — Builds a natural-language profile of your interests from like history. Refreshed weekly.
- **🎯 Scored recommendations** — Candidates scored 0–10 against your profile. Filters out anti-patterns learned from feedback.
- **🌀 Serendipity picks** — At least 2 recommendations from adjacent topics for unexpected discovery.
- **🔁 Feedback loop** — Checks which recommended posts you actually liked. Accumulates negative signals to improve future scoring.
- **📡 Multi-platform delivery** — Telegram, Discord, Slack via OpenClaw's channel system. Identical content, format-adapted per platform.

---

## Two Modes

### Digest Mode
Collects all new likes since the last run → categorizes → summarizes → delivers a structured digest.

```
📊 X Likes Digest — 2025/4/1
━━━━━━━━━━━━━━━━━━
📌 新規いいね: 24件

📂 カテゴリ内訳:
  🤖 AI / Dev: 9件
  💰 Crypto: 7件
  📝 Articles: 5件
  ...
```

### Recommend Mode
Analyzes your interest profile → searches twitterapi.io → scores candidates → delivers top picks with reasoning.

```
💡 おすすめポスト（12件）
━━━━━━━━━━━━━━━━━━

🤖 AI / Dev
1. @author — Post title
   100–200 char summary of what's interesting
   📌 Why: matches "AI agent infra" interest pattern
   🎯 スコア: 8.5/10
```

---

## Setup

### 1. VPS Collector

The collector runs on an always-on machine (VPS recommended) and fetches your likes daily.

```bash
# Clone and install
git clone https://github.com/nmn-labs/x-likes-digest.git
cd x-likes-digest
npm install

# Set up OAuth (one-time, requires browser)
npm run oauth:setup
# Follow the flow, then:
npm run oauth:exchange

# Test data collection
npm run collect

# Test export (what the OpenClaw agent reads)
npm run export
```

Copy `.env.example` to `.env`:

```env
# X OAuth 2.0 (from X Developer Portal)
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret
TWITTER_USERNAME=your_x_username

# twitterapi.io (for recommend mode and article fetch)
TWITTERAPI_KEY=your_twitterapiio_key
```

> See [`references/setup-guide.md`](./references/setup-guide.md) for full database init and OAuth details.

### 2. OpenClaw Skill

Install the skill into your OpenClaw instance:

```bash
openclaw skill add nmn-labs/x-likes-digest
```

Or clone locally and add by path:

```bash
openclaw skill add /path/to/x-likes-digest
```

### 3. Configure Cron

Add two cron jobs — one for digest, one for recommendations:

```bash
# Digest — daily at 8:30 JST
openclaw cron add --name x-likes-digest \
  --schedule "30 8 * * *" --tz Asia/Tokyo \
  --message "Run x-likes-digest skill in digest mode. Config: ssh_host=your-server, vps_project_path=/home/user/x-likes-digest, telegram_channel_id=-100xxx, delivery_channels=[telegram]" \
  --channel telegram --timeout 900

# Recommend — daily at 8:45 JST
openclaw cron add --name x-likes-digest-recommend \
  --schedule "45 8 * * *" --tz Asia/Tokyo \
  --message "Run x-likes-digest skill in recommend mode. Config: ssh_host=your-server, vps_project_path=/home/user/x-likes-digest, telegram_channel_id=-100xxx, recommend_count=12, delivery_channels=[telegram]" \
  --channel telegram --timeout 600
```

For **local mode** (collector on same machine as OpenClaw), use `local_db_path=/absolute/path/to/x-likes-digest` instead of `ssh_host`.

---

## Configuration Reference

Pass these in the cron `--message` or as context to the skill:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `ssh_host` | SSH alias for VPS (remote mode) | `my-vps` |
| `vps_project_path` | Collector path on VPS | `/home/user/x-likes-digest` |
| `local_db_path` | Collector path (local mode, no SSH) | `/Users/you/x-likes-digest` |
| `telegram_channel_id` | Telegram channel for delivery | `-100xxxxxxxxxx` |
| `delivery_channels` | Target platforms | `["telegram"]` or `["telegram","discord"]` |
| `discord_channel_id` | Discord channel ID | `1234567890` |
| `slack_channel_id` | Slack channel | `#digest` |
| `recommend_count` | Number of recommendations | `12` |
| `categories` | Fixed category list (optional) | `[{"emoji":"💰","name":"Crypto","criteria":"..."}]` |

**Multi-platform delivery** is powered by OpenClaw's channel system. Each enabled channel receives identical content formatted for its platform (Markdown for Telegram/Discord, mrkdwn for Slack).

---

## Available Scripts

| Script | Description |
|--------|-------------|
| `npm run collect` | Fetch and enrich new likes from X API |
| `npm run export` | Export undigested likes for the OpenClaw agent |
| `npm run recommend` | Run standalone recommender (debug) |
| `npm run oauth:setup` | Start OAuth 2.0 authorization flow |
| `npm run oauth:exchange` | Complete OAuth token exchange |
| `npm run build` | Compile TypeScript → `dist/` |
| `npm run dev` | Run collector in dev mode (tsx, no build) |
| `npm start` | Run compiled collector |

---

## ⚠️ API Cost Safety

twitterapi.io is a **paid API** (~$0.015/request). The skill enforces guards:

- Max 7 search queries per recommend run, 1 page each
- Deduplication check before paginating
- Stops immediately on repeated cursors (loop detection)

> Always test with a single page before running full collection.

---

## Contributing

Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

Quick start:
1. Fork and create a feature branch: `git checkout -b feature/your-feature`
2. Test by installing your fork: `openclaw skill add <your-fork>/x-likes-digest`
3. Submit a PR with a CHANGELOG entry

---

## License

[MIT](./LICENSE) — © nmn-labs

---

---

# X Likes Digest（日本語）

**AIによるX（Twitter）いいね日次ダイジェスト & パーソナライズされたおすすめポスト配信ツール。**

いいねしたツイートを自動収集し、LLMでカテゴリ分類・要約したうえで、毎日Telegram/Discord/Slackへ配信。さらにあなたの興味プロ
````
