topconf-daily

Track CCF-A conference papers, score by user research interests, deliver as Markdown / email.

When to activate this skill

Activate when the user mentions any of:

• "Track top-conference papers" / "What are the latest CVPR/NeurIPS/ACL papers?"
• "Daily paper digest" / "weekly paper digest" / "research alert"
• "Recommend papers based on my research interests"
• "Email me a top-conference paper digest"
• "schedule a daily paper report"

Do not activate for: arXiv-only preprints (different skill), single-paper Q&A, citation lookup of a known paper.

Inputs the agent needs

Read these from topconf-daily.yaml first; only ask the user conversationally for what is missing:

1. Research keywords — 3–10 phrases that describe the user's research (e.g. multimodal, vision language model, CLIP).
2. Target conferences — subset of the default 19 venues, or accept the default.
3. Output preference — Markdown only, or Markdown + email. For email, SMTP credentials must be present in YAML.
4. Schedule — one-off run, or recurring (use the agent's native scheduler if available; OS schedulers only as a fallback).

If any of the above is missing, ask the user — do not invent defaults silently.

YAML configuration reference

All config lives in topconf-daily.yaml. Beyond the required inputs above, these items are also configurable:

All defaults are reasonable and only need changing on user request.

Standard procedure

Recommended: agent-driven workflow

The script is a data fetcher, not the brain. The agent does the real filtering and ranking.

1. Build the candidate pool — latest proceedings of each configured conference, enriched with abstracts + citations from Semantic Scholar:

Unix:
bash .venv/bin/python -m topconf fetch

Windows:
powershell .venv\Scripts\python.exe -m topconf fetch

This writes candidates.json at the skill root: the full pool, before any relevance cut. The fetcher's built-in keyword filter is only a loose pre-net to limit network calls; it is not the final judgment.

For the routine daily digest you can add --fast to skip the slow Semantic Scholar step and rely on arXiv abstracts + title matching — much quicker when DBLP is healthy.

2. Read candidates.json. For every candidate, read its title and abstract. Each candidate also carries the four-dimensional scores (relevance_score, recency_score, popularity_score, quality_score, final_score) — use these as a signal, not as the verdict; your own judgment of relevance and impact still decides the ranking.

3. Intelligent relevance filtering — judge semantic fit to the user's research, not substring presence (see below).

4. Rank survivors by genuine relevance to the user, using your own understanding — not the script's heuristic final_score. Among relevant papers, prioritize impact and influence: prefer papers that are well-known, practically valuable, and have real-world / academic influence (high Semantic Scholar citation counts, landmark methods, widely-adopted frameworks or toolkits, best-paper-level contributions). Use the citation_count field in candidates.json as one signal, and your own knowledge of which methods are influential. Do not let a high script score substitute for this judgment.

5. Write the brief (in Chinese): create reports/topconf-YYYY-MM-DD.md. For each paper, do not paste the raw English abstract — instead, paraphrase it into plain, easy-to-read Chinese (3–5 sentences) that explains what problem it solves, the key method, and why a practitioner would care. Include the metadata from candidates.json (scores, citations, keyword matches, all available links) — these give the reader quantitative context alongside your qualitative analysis. Then add a one-line insight on how it connects to the user's research and its practical value. Keep the original English title and technical terms (model names, datasets) as-is.

Report format template (the brief defaults to Chinese — language: "zh" in topconf-daily.yaml; the template below is the Chinese-output format. When language: "en", produce the equivalent in English):
```markdown
# {date} 顶会论文简报

数据源：DBLP / arXiv (fallback)
候选池：{n} 篇 | 筛选后：{n} 篇 | 推荐：{n} 篇
研究方向: {keywords summary}

## {i}. {Paper Title} ({Conference, Year})
链接：arXiv | DOI | S2 | DBLP
匹配关键词：{keywords}
引用：{citationCount}（有影响力 {influentialCitationCount}）
综合评分：{final_score}/10

{中文摘要改写，3-5句话：解决的问题 → 核心方法 → 为什么值得关注 → 实验结果/贡献}

洞察：{一句话说明与用户研究方向的关联及实际价值}
```

6. Summarize the top 3–5 picks to the user in chat (title, venue, why it matters).

Scheduled / email delivery

The agent sets these up — the user never runs anything by hand.

> ⚠️ run subcommand positioning: run is a fully automated fetch + report + email pipeline that skips the agent's intelligent filtering, so it is only suitable for unattended scheduled jobs (e.g. cron). In the agent-driven workflow, stick to fetch → the agent writes its own brief → email --report, so human judgment stays in the filtering and ranking.

• For email delivery, once the email: block is filled in topconf-daily.yaml, the agent sends the brief it just wrote — without re-generating one:

Unix:
bash .venv/bin/python -m topconf email --report reports/topconf-YYYY-MM-DD.md

Windows:
powershell .venv\Scripts\python.exe -m topconf email --report reports/topconf-YYYY-MM-DD.md

The email command sends a pre-written Markdown file as HTML (converted from the Markdown brief), so headings/bold/links render correctly in email clients. It never overwrites or re-generates your curated brief — it just delivers the file you point it at. If attach_papers: true is set in email:, it also downloads and attaches PDFs for the papers it can reach (arXiv → S2 OA → DOI). For PDF attachment it reads the paper list from candidates.json (or a file you pass via --papers <json>). If the total PDF size exceeds email.max_per_email_mb (default 20 MB), the system automatically splits into multiple emails with (1/N) subject suffixes — each email contains the full report body plus a subset of PDFs.

Prefer writing the brief yourself first (steps 1–5) so it reflects your judgment, then let the script only handle delivery via email --report. The script-level run subcommand is a convenience for fully automated/scheduled runs: it fetches, writes its own script-ranked brief, and emails that. Use run only when no agent curation is desired; for the agent-driven workflow, use fetch + your own brief + email --report.

• For standalone PDF downloads (the user wants the PDFs without an email), use the download subcommand:

Unix:
bash .venv/bin/python -m topconf download

Windows:
powershell .venv\Scripts\python.exe -m topconf download

By default it reads candidates.json and downloads all PDFs to reports/pdfs/. Options: --papers <json> to read from a different source, --output-dir <dir> for a custom output directory, --top-n 5 to download only the top N papers.

• For recurring delivery, register the schedule inside the agent's own scheduler (a built-in recurring task that re-invokes this skill). Do not ask the user to maintain a hand-written crontab / systemd timer — those are only a fallback the agent may create itself when no native scheduler exists.

Reset / refresh

Unix:

.venv/bin/python -m topconf reset-cache

Windows:

.venv\Scripts\python.exe -m topconf reset-cache

• To re-recommend papers seen before, run the reset-cache command.
• To force a fresh Semantic Scholar fetch, run fetch --no-cache.

Recommendation memory

The skill avoids re-recommending the same paper across runs via a lightweight on-disk memory (recommended_papers.json at the skill root). You should understand it so you can report skips accurately and reset when asked:

• Keys — each recommended paper is recorded by three dimensions: arXiv ID (with version, e.g. 2607.18958v1), DOI, and a normalized title. A paper is skipped if it matches any of the three, so minor title/case differences still dedupe. A brand-new arXiv version (v2) will not be skipped (by design — it's a different artifact).
• TTL — entries expire after cache.memory_ttl_days (default 90). Expired entries stop being filtered and are pruned from disk on the next run. Set TTL to 0 to never expire.
• Effect — on each fetch/run, filter_already_recommended drops already-recommended papers (logged as skipped N already-recommended papers); survivors are then added to the memory and persisted.
• CLI — --memory-ttl-days N overrides the YAML value for a single run; reset-cache wipes the memory (and the S2 cache) to allow re-recommendation.
• Separate from S2 cache — this is not the Semantic Scholar disk cache (s2_cache.json, 14-day TTL), which only caches API responses to save network calls.

When you report results to the user, the "skipped (memory)" count in the output contract reflects papers dropped by this mechanism.

Intelligent filtering (the agent's job)

The script's filter_by_keywords is a dumb substring match — it cannot tell a paper that is about your topic from one that merely mentions it. You must re-judge:

• Read the abstract; understand the contribution, method, and setting.
• Keep papers whose core contribution relates to the user's research; drop papers where the keyword appears only incidentally (e.g., in related work, a dataset name, or a comparison baseline).
• Drop surveys / meta-reviews / benchmarks-as-papers unless the user explicitly wants them (excluded_keywords already drops the obvious ones at the script level, but catch the rest).
• Do not keep a paper just because it has a high script score — the score rewards citation counts and buzzwords, not fit.

• Favor signal over noise. The user wants papers with real value and influence, not everything that matches a keyword. Prefer work that is well-known, practically useful, or has shaped the field; drop marginal, incremental, or niche-only papers even if they match. When torn between two relevant papers, lean toward the one with higher citation impact or broader adoption.

• arXiv-fallback skepticism. When search_info.source is arxiv (DBLP was down or returned nothing), the brief is built from arXiv keyword matches, not guaranteed CCF-A acceptances. Each paper carries a venue_affiliated flag — true only when its abstract/comment explicitly states acceptance at a named venue. Prefer venue_affiliated: true papers and clearly tell the user these are arXiv matches, not confirmed conference papers.

Conference recency rule

The script returns the latest proceedings DBLP indexes for each venue. DBLP lists accepted papers for upcoming conferences before the event happens (e.g., in July 2026, EMNLP 2026 papers may already be indexed even though the conference hasn't been held). Therefore:

• By default, exclude papers from a conference whose event date is still in the future. Use your knowledge of the venue's typical schedule to decide (e.g., EMNLP is usually Nov/Dec).
• Mark such papers forthcoming / accepted and only include them when the user explicitly asks for upcoming or forthcoming work.
• For the routine digest, prefer the most recent completed cycle of each venue.

Output language

The brief defaults to Chinese (language: "zh" in topconf-daily.yaml). All prose in the Markdown report — titles' explanations, insights, summaries — should be in the configured language; original English paper titles and technical terms are kept as-is. Chat replies follow the user's language and default to Chinese. If the user asks for an English brief, switch language to "en".

Output contract

When the run completes, always report back to the user:

• Number of candidates fetched / how many you kept after intelligent filtering / skipped (memory) / recommended.
• Data source used: DBLP or arXiv (fallback).
• Path to the Markdown report.
• For email runs, whether SMTP send succeeded; if not, the specific SMTP error class.

Never truncate the brief without asking. The Markdown file is the deliverable; the chat reply is a summary.

Error handling

S2 Rate Limit Handling

If the user encounters frequent 429 errors from Semantic Scholar:

1. Wait 5 minutes (S2's rate limit window resets)
2. Use --no-cache only if cache entries are stale (it makes rate limit worse in the short term)
3. As a last resort, run --fast mode to skip S2 enrichment entirely and rely on arXiv abstracts

Note: The current implementation does not support S2 API keys. The free tier allows ~100 requests per 5 minutes, which is respected by the built-in request throttling (3.5s delay between requests).

Reference material

Load these only when the relevant topic comes up:

• references/cli-reference.md — full CLI flags, YAML config fields, cache mechanics (read when the user asks about a specific flag or cache behavior).
• references/scheduling.md — cron / systemd / Windows Task Scheduler templates (read when scheduling).
• references/network-fallback.md — DBLP → arXiv fallback details and Chinese-network workarounds (read when DBLP is unreachable).

File layout

topconf-daily/
├── SKILL.md                       # this file (agent-facing)
├── README.md                      # GitHub landing page (human-facing)
├── LICENSE                        # MIT
├── topconf/                       # the package (modular, subcommand CLI)
│   ├── __main__.py                #   `python -m topconf <command>`
│   ├── cli.py                     #   subcommand dispatch: fetch/detect/report/email/run/cron/reset-cache
│   ├── fetch.py                   #   main pipeline: DBLP/arXiv → filter → S2 → score
│   ├── dblp.py / arxiv.py / s2.py #   per-source clients + caches
│   ├── scoring.py / memory.py     #   four-dimensional scoring + recommendation memory
│   ├── report.py / emailer.py     #   Markdown/HTML report + SMTP/PDF delivery
│   └── config.py / utils.py / venv_check.py
├── scripts/topconf.py             # thin launcher (same as `python -m topconf`)
├── topconf-daily.yaml             # config the agent reads / edits
├── setup.sh / setup.ps1           # one-shot venv installers (run by the agent)
├── references/                    # on-demand docs (see above)
├── reports/                       # generated briefs (gitignored)
├── .claude/skills/topconf-daily/ # Claude Code discovery
└── .agents/skills/topconf-daily/ # Generic agents / Cursor & Codex shared discovery

> Discovery copies: the two */skills/topconf-daily/SKILL.md files (.claude/ for Claude Code, .agents/ shared by Cursor / Codex / generic agents) are byte-for-byte copies of this root SKILL.md, so the skill is auto-discovered by every supported runtime. They are synced by scripts/sync_skills.py (run by setup.sh/setup.ps1) — always edit this root file, never a copy. If your runtime scans more than one of these folders, delete the extras to avoid an Ambiguous skill name conflict.

Hard rules

• Never run with global Python. The script's _check_venv() enforces this; do not bypass it.
• Never silently install dependencies. If pyyaml is missing, run the setup script yourself (bash setup.sh / setup.ps1).
• Never write secrets to chat logs. Email passwords stay in topconf-daily.yaml (gitignored in spirit if the user is careful).
• Never recommend a paper without a source link. DBLP / arXiv / DOI must be present.