Deepxiv Cli

Search, inspect, and progressively read open-access academic papers with the deepxiv CLI. Use when the user wants arXiv / PMC / Semantic Scholar paper search...

Security Scan

The skill is internally consistent: it documents use of a CLI (deepxiv) for arXiv/PMC/Semantic Scholar workflows, does not request unexpected credentials, and does not instruct the agent to perform hidden or unrelated actions.

Purpose & Capability

Name/description (CLI for searching and progressively reading open-access papers) matches the instructions and referenced commands (search, paper, pmc, sc, trending, wsearch, agent). No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md stays on-topic: it tells the agent to check for deepxiv, run its help/health/debug, and to follow progressive-reading workflows. It explicitly forbids installing without user approval and documents LLM-agent caveats. There are no steps that read unrelated files or exfiltrate data.

Install Mechanism

There is no automatic install spec in the skill bundle (instruction-only). references/install.md directs users to install via pipx or pip --user and to use system package managers (apt/dnf/brew/pacman) for pipx. This is expected for a Python CLI but does involve installing packages and (in some cases) sudo; user consent is required before running those commands.

Credentials

The skill declares no required environment variables or credentials. It does require the user's LLM backend to be configured if using the `agent query` feature, and SKILL.md notes that LLM usage will consume the user's account — this is documented and proportional to the feature.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide modifications. It does not attempt to change other skills' configs or require elevated persistent privileges.

Assessment

This skill is an instruction-only helper for an external Python CLI (deepxiv). Before installing: (1) confirm you want the deepxiv-sdk Python package from PyPI and be prepared to run pipx or pip install commands (some platforms use sudo); the skill explicitly says the agent must ask you before installing anything — do not let the agent install without approval. (2) If you plan to use the `agent query` LLM feature, understand it will use your LLM account and incur usage/costs; configure the LLM backend yourself. (3) Consider verifying the deepxiv-sdk package source (PyPI page, project homepage or repo) and check reviews or repository before installing. (4) If you prefer not to install system packages or grant sudo, decline installation and ask the agent to proceed only with commands that do not require installing deepxiv. Overall the skill is coherent, but exercise the usual caution when running package installs and when enabling LLM-backed autonomous features.

deepxiv is a progressive-reading paper tool for open-access literature (arXiv, PMC, Semantic Scholar) with optional web search and an LLM-powered research agent.

The single most important rule: read the smallest amount of text that answers the question. Climb the ladder only as far as needed.

Progressive reading ladder

For any paper, prefer the cheapest rung that still answers the question:

Rung	Command	What you get	When to use
1	paper <id> --brief	Title, TLDR, keywords, citations, GitHub URL	First triage of any paper
2	paper <id> --head	Metadata + section list (JSON)	Decide which sections matter
3	paper <id> --preview	First ~10k chars (intro + early method)	Need more than TLDR but not full sections
4	paper <id> --section <Name>	One named section	Targeted answer (Method / Results / etc.)
5	paper <id> or --raw	Full markdown	Only when explicitly required

Never jump to rung 5 unless the user asked for a full read or the task truly needs it.

Setup

Before using deepxiv, verify it is available:

deepxiv --help

If missing, stop and tell the user — do not install it on your own. If the user asks you to install it, follow references/install.md, which has per-OS instructions, and only run install commands after the user explicitly approves them. deepxiv requires Python 3.10+.

Health and diagnostics (safe to run any time):

deepxiv health     # API + token reachability check
deepxiv debug      # environment diagnostics

Decision: which command do I want?

User wants…	Start with
"Find papers about X"	search (with filters if narrow)
"What's hot recently in X?"	trending
"Explain this paper" (has ID)	paper --brief → --head → section
"Compare these N papers"	paper --brief for each, then targeted sections
Biomedical / PubMed paper	pmc <PMC_ID>
Has only Semantic Scholar ID	sc <id>
"Who is this author / what's this project?"	wsearch
"Is this paper actually getting traction?"	paper --popularity
Open-ended multi-step research question	agent query (see caveats)

Core commands

search — arXiv search with filters

deepxiv search "agent memory" --limit 5
deepxiv search "multimodal reasoning" --limit 10 --format json

Filters (combine freely):

# Category filter (arXiv categories)
deepxiv search "retrieval" --categories cs.IR,cs.CL --limit 5

# Date window
deepxiv search "diffusion" --date-from 2025-01-01 --date-to 2025-06-30

# Citation floor — useful to skip obscure preprints
deepxiv search "world model" --min-citations 50 --limit 5

# Search mode: hybrid (default), bm25 (literal), vector (semantic)
deepxiv search "chain of thought" --mode bm25 --limit 5
deepxiv search "models that can think before answering" --mode vector

Defaults:

• --limit 3 to 5 for triage; raise only when explicitly needed
• --format json whenever you intend to post-process (pipe to jq)
• Use bm25 for exact phrasing, vector for fuzzy concepts, hybrid otherwise

paper — get an arXiv paper

deepxiv paper 2409.05591 --brief        # rung 1
deepxiv paper 2409.05591 --head         # rung 2
deepxiv paper 2409.05591 --preview      # rung 3
deepxiv paper 2409.05591 --section Method   # rung 4
deepxiv paper 2409.05591                # rung 5 — full
deepxiv paper 2409.05591 --popularity   # social impact / trending signal
deepxiv paper 2409.05591 --raw          # raw markdown (full)

Section names come from --head. Common names: Introduction, Related Work, Method, Experiments, Results, Discussion, Limitations, Conclusion. Names are paper-specific — do not guess; check --head first if unsure.

Use --popularity when the user asks "is this paper a big deal" or you need to rank by attention rather than citations.

pmc — PubMed Central / biomedical

deepxiv pmc PMC544940 --head
deepxiv pmc PMC544940

PMC currently returns JSON only. Use when the target is biomedical or a PMC ID is given.

sc — Semantic Scholar lookup

deepxiv sc 258001
deepxiv sc 258001 --json

Use when the user gives a Semantic Scholar ID, or when you need richer metadata (citation graph, author info) for an arXiv paper that you have already cross-referenced.

trending — hot papers

deepxiv trending --days 7 --limit 10 --json
deepxiv trending --days 30 --limit 5

--days accepts only 7, 14, or 30. Use for weekly digests and "what's hot" requests.

wsearch — web search

deepxiv wsearch "karpathy"
deepxiv wsearch "DeepSeek R1 release notes" --json

Use for non-paper context: author background, project home pages, blog posts, release announcements. Cheap and broad — good for grounding before a paper read.

agent query — LLM-powered research agent

deepxiv agent query "Compare RAG vs long-context for code QA"
deepxiv agent query "Latest agent memory papers" --max-turn 10 --verbose

This is a multi-turn research agent that can search and read papers on its own. Caveats:

• Requires the user to run deepxiv agent config once to set up their preferred LLM
• Consumes LLM usage on the user's account
• Slower and less predictable than manual search + paper flows
• Prefer manual progressive reading by default; reach for agent query only when the question is genuinely open-ended and the user has agreed to the cost

JSON post-processing

When you need to slice search/trending output, prefer JSON + jq over re-running text searches:

deepxiv search "agent memory" --limit 10 --format json \
  | jq -r '.[] | "\(.arxiv_id)\t\(.citations // 0)\t\(.title)"' \
  | sort -k2 -n -r

deepxiv trending --days 7 --limit 20 --json \
  | jq -r '.[] | select(.categories[]? | test("cs\\.(AI|CL|LG)")) | .arxiv_id'

Recommended workflows

Topic exploration

"帮我找最近关于 agent memory 的论文":

1. deepxiv search "agent memory" --limit 5 --format json (add --date-from if "最近")
2. paper <id> --brief for each promising hit
3. Pick 1–2 for deeper reading

Single paper explanation

"讲讲这篇论文 <id>":

1. paper <id> --brief
2. paper <id> --head
3. Read 1–2 sections most relevant to the question (or --preview if unsure)
4. Summarize, and say which rung you stopped at

Baseline / comparison table

"帮我整理这个方向的 baseline":

1. Narrow search with --categories and optionally --min-citations
2. --brief every candidate
3. Read only Method / Experiments / Results for top picks
4. Extract: paper, task, dataset, metric, score, key idea

Author / project background check

"这篇论文的作者还做过什么？" / "这个项目背景是什么？":

1. deepxiv wsearch "<author or project>" --json
2. If a related arXiv paper surfaces, climb the reading ladder on it
3. Optionally sc <id> for citation context

Citation-aware filtering

"找有影响力的相关工作":

1. deepxiv search "..." --min-citations 100 --format json
2. Sort by citations via jq
3. Triage with --brief

Hot digest

"本周热门论文":

1. deepxiv trending --days 7 --limit 10 --json
2. --brief the top picks
3. Optional --popularity to rank by attention
4. Compact digest: theme overview → one-line per paper → which to read deeper

See references/workflows.md for fuller versions of these.

Output rules

• Always say which rung of the ladder informed your conclusion (e.g. "based on --brief only" vs. "after reading the Method section")
• Do not make section-level claims you didn't actually read
• Prefer concise bullet summaries when comparing multiple papers
• Keep context use low: small --limit, climb the ladder only as needed
• For literature reviews, prefer iterative narrowing over one giant search

Common failure modes

Auth or rate-limit issues — run deepxiv health to check service reachability. If rate-limited or unauthorized, say so plainly and stop; do not silently retry.

Paper not found — verify ID format and source: arXiv (2409.05591), PMC (PMC544940), Semantic Scholar (258001). If unsure which, try wsearch first.

Section name mismatch — section names are paper-specific. Run --head to list real section names before --section.

Over-reading — do not jump to full text when --brief, --preview, or one section would do.

Python 3.9 install — deepxiv may install via pip but crash on first run. Switch to a Python 3.10+ environment.

Good defaults

• search --limit: 3–5 for triage, 10 max
• trending --limit: 5–10
• Section reads per paper: 1–2 unless asked otherwise
• Full paper reads: opt-in only
• agent query: only for genuinely open-ended multi-step research, with user consent