paper-suggestions

name

paper-suggestions

description

Curate a daily (or date-range) personalized paper digest from arXiv + HuggingFace. Fetches new & cross-listed papers, reads their abstracts, matches them against the user's preference topics (Agent / World Model / post-training / ...), and writes a grouped-by-topic Markdown digest with per-paper summaries. Self-contained: needs only python3 + the optional `hf` CLI, no other skill or external script. TRIGGER ONLY on an explicit request to run/generate/update the digest, e.g. "跑一下 paper-suggestions", "生成今天的论文日报", or when invoked by a scheduled/automated task. DO NOT auto-trigger. This skill is meant to run on a schedule (a daily cron/loop set up separately) OR on explicit demand — never run it proactively just because papers, arXiv, or research topics are mentioned in conversation. When unsure, ask before running. DO NOT TRIGGER when: user wants a raw keyword search, to read one specific paper's full text, to read a local paper folder, or to import papers into Zotero (those are separate skills) — and never as a side effect of an unrelated request.

Paper Suggestions — 每日个性化论文推荐

Build a personalized daily paper digest. Data sources: arXiv (a category feed — default cs.CL, including NEW submissions and cross-listed papers) plus HuggingFace daily papers (trending signal + papers beyond the category). The skill fetches candidates with abstracts, you read the abstracts, match them against the user's preference topics, and emit a grouped Markdown digest.

The intelligent part — judging real relevance and writing summaries — is your job. The bundled script only gathers raw candidates reliably.

Execution policy — do not run proactively

This skill is designed for scheduled, unattended daily runs (a cron//loop job set up separately). Therefore:

• Run it only when the user explicitly asks, or when a scheduled task invokes it.
• Do not trigger it just because the conversation mentions papers/arXiv/a research area.
• It is fully non-interactive: it reads preferences.yaml, fetches, matches, writes the file. A scheduled run must complete end-to-end without asking questions.

Prerequisites

• python3 (stdlib only) — for scripts/fetch_papers.py. No third-party packages.
• hf CLI (optional but recommended) — HuggingFace papers signal. Degrades gracefully if absent.
• The core (fetch → match → write) is self-contained: no other skill or external script.
• Optional only: the step-6 Feishu push depends on the sibling feishu-doc skill (used solely when feishu.enabled is true). If you never enable it, this skill has no dependencies.

Files

File	Purpose
preferences.yaml	User's topics (name/keywords/desc) + output settings. Read this first.
scripts/fetch_papers.py	Fetch + merge + dedup arXiv & HF candidates → JSON

---

Workflow

1. Read preferences

Read preferences.yaml (in this skill's directory) to get the user's topics and output settings. If the user named specific topics for this run only, use those instead (or in addition) — the config is the default, an explicit request overrides it.

2. Fetch candidates

Run the fetch script with --out-dir so the output is auto-named by the resolved batch date — candidates-<batch-date>.json — and never collides with past runs:

python3 scripts/fetch_papers.py --out-dir /tmp/paper-suggestions

The script prints the final file path on its own first line — read candidates.json from that exact path (don't assume a fixed name). Pick the time scope from the user's request:

User asks	Command
today / latest (default)	python3 scripts/fetch_papers.py --out-dir /tmp/paper-suggestions
a specific past date	... --date 2026-07-13 --out-dir /tmp/paper-suggestions
last N days	... --days 3 --out-dir /tmp/paper-suggestions
a different field	... --category cs.LG ...
also include updated papers	add --include-replaced
skip HuggingFace	add --no-hf

(--out-dir names the file candidates-<date>.json; --date mode → that date, --days mode → <start>_<end>, latest/RSS mode → the RSS batch date. Use -o FILE instead only if you need an exact filename.)

Note on "today": arXiv's latest RSS batch is built overnight and usually reflects the previous business day (weekends skipped). The script reports the actual batch date in date_token (also in range.build_date / range.date) — always state that date in the output and reuse it for the digest filename; don't assume it's the wall-clock date.

The JSON has:

• date_token — the resolved batch/range date; use it for the digest filename so the digest and its candidates file share the same date.
• arxiv[] — {id, title, abstract, authors, categories, primary_category, announce_type (new|cross), url, hf_upvotes?} — the main candidate pool, with abstracts.
• hf_only[] — {id, title, upvotes, url, abstract?, categories?, primary_category?} — HF trending papers NOT in the arXiv pool. The script back-fills their abstracts in one batched arXiv API call, so they usually already have abstract (unless --no-hf-abstracts or the API was unavailable — see notes).
• counts, range, notes.

3. Read abstracts & match to topics

Read candidates.json. For each paper in arxiv[] and hf_only[], read its abstract and decide which topic(s) it belongs to — use each topic's desc for the semantic bar, keywords only as a hint. A paper may match multiple topics (list it under the best fit, or note the overlap). List all matched papers (no cap), ordered within each topic by relevance (break ties by hf_upvotes). Skip papers that clearly match no topic.

If some hf_only[] entries lack an abstract (see notes — e.g. the arXiv API was rate-limited), judge them by title; if a title looks strongly relevant you may fetch its abstract yourself (e.g. hf papers info <id>), but never block a scheduled run on it — degrade gracefully and note the omission.

其他推荐 (serendipity). If other.enabled is true, after the defined topics, curate up to other.max papers that match no defined topic but are still worth reading per other.desc (novelty / standout HF traction / likely future interest / broad impact). This is a curated pick, not a dump — quality over quantity; if nothing clears the bar, leave it out entirely. Each such paper must state why it's recommended despite being off-topic. Never put a paper here if it already fits a defined topic.

4. Write the digest

Write Markdown to <output.dir>/<batch-date>.md (expand ~; create the dir). Group by topic, one ## section per topic (skip topics with zero matches, but note them at the end). Follow output.style:

rich (default) — per paper:

# 论文推荐 · <batch-date>

> 源: arXiv <category> (<N_new> new + <N_cross> cross) + HF Papers · 命中 <T> 领域 / <P> 篇

## 🤖 Agent
- **<title>** `<id>`
  - 摘要: <2-3 句中文,基于 abstract,说清做了什么>
  - 亮点: <一句话,为什么值得读 / 和该领域的关系>
  - 链接: https://arxiv.org/abs/<id> <if hf_upvotes: · HF ⬆️<n>>

## 🌍 Agent World Model
- ...

## ✨ 其他推荐
- **<title>** `<id>`
  - 摘要: <2-3 句>
  - 为什么推荐: <为何值得读,且为何破格——不属于已有领域却仍推荐的理由>
  - 链接: https://arxiv.org/abs/<id> <if hf_upvotes: · HF ⬆️<n>>

The 其他推荐 section comes last (after all defined topics) and is omitted entirely if nothing qualifies. Use other.title / other.emoji from the config for its heading.

oneline — per paper: - **<title>** \` — <一句话概括>。 https://arxiv.org/abs/`

End with a one-line footer noting anything skipped (topics with no hits, HF-only titles not enriched, whether replace updates were excluded) — never silently drop coverage.

5. Report back

Print the digest path, then a compact in-chat summary (topic → count, and the single most notable paper). Offer follow-ups: read a paper's full text, import to Zotero, or adjust preferences.yaml. (When run by a scheduled task, just write the file and print the path/summary — no interactive follow-ups.)

6. (Optional) Push to Feishu — via the feishu-doc skill

Only if feishu.enabled is true in preferences.yaml. This step is not internalized — it delegates to the sibling feishu-doc skill. Run one line on the digest just written:

python ../feishu-doc/scripts/push_doc.py "<digest-path>" \
    --title "论文推荐 · <batch-date>" --folder-name "<feishu.folder_name>" <feishu.extra_args>

• Recipient, App ID/Secret, and other setup live in feishu-doc's own .env; recipient/folder/ permission flags are documented in its SKILL.md — refer there, don't duplicate here.
• Omit --folder-name if feishu.folder_name is empty. Append feishu.extra_args verbatim.
• On failure (missing creds, scope, network), do not fail the whole run — the digest file is the primary artifact; report that the Feishu push failed and continue.

---

Recurring / automation

This skill is built to be scheduled. Each run is self-contained, non-interactive, and idempotent (overwrites that date's file). The skill itself never creates schedules — a system-level scheduler invokes it. Bundled assets live in automation/:

File	Purpose
automation/run_daily.sh	Launcher — calls the CLI headless (tclaude -p … --dangerously-skip-permissions) and asks it to run this skill. Logs to ~/Local/CACHE/paper-suggestions/logs/.
automation/com.x1a.paper-suggestions.plist	macOS launchd LaunchAgent — fires daily at 12:00 local.

Set up the daily 12:00 trigger (macOS, launchd — recommended)

Use launchd, not the in-session /loop or CronCreate: those only fire while a Claude REPL is open, so they can't do true unattended daily runs. launchd fires even with no session.

SKILL_DIR="$HOME/.claude/skills/paper-suggestions"          # deployed symlink location
chmod +x "$SKILL_DIR/automation/run_daily.sh"
cp "$SKILL_DIR/automation/com.x1a.paper-suggestions.plist" ~/Library/LaunchAgents/
launchctl unload ~/Library/LaunchAgents/com.x1a.paper-suggestions.plist 2>/dev/null || true
launchctl load  ~/Library/LaunchAgents/com.x1a.paper-suggestions.plist
launchctl list | grep paper-suggestions                     # confirm it's registered

• Change the time: edit StartCalendarInterval (Hour/Minute) in the plist, then launchctl unload + load again. Omit Minute to run hourly; add multiple dicts for several times a day.
• Run once now (test): launchctl start com.x1a.paper-suggestions, then watch ~/Local/CACHE/paper-suggestions/logs/run-<today>.log.
• Uninstall: launchctl unload ~/Library/LaunchAgents/com.x1a.paper-suggestions.plist && rm ~/Library/LaunchAgents/com.x1a.paper-suggestions.plist.
• Paths: the plist hardcodes the repo path to run_daily.sh and the Label com.x1a.paper-suggestions; adjust both if the repo moves or you want a different label (Label must match the filename).

Alternative: crontab

# every day at 12:00
0 12 * * * /bin/bash "$HOME/.claude/skills/paper-suggestions/automation/run_daily.sh"

Auth caveat (important)

The launcher runs the CLI headless, so the CLI must already be logged in and its stored credentials readable from a non-interactive launchd context (e.g. tclaude login done once; claude OAuth token or ANTHROPIC_API_KEY present). If a scheduled run produces an auth error in the log, that's the cause — re-login, or export the key inside run_daily.sh. Also verify feishu-doc/.env is configured if feishu.enabled is true, or the push step will log a failure (the digest still generates).

When to Use This Skill

Run only on an explicit request or a scheduled invocation — never proactively. Explicit requests look like:

• "跑一下 paper-suggestions"
• "生成今天的论文日报"

If the user merely mentions papers, arXiv, or a research topic without asking to generate the digest, do not run this skill — use a search/read skill or just answer, or ask first.