agentsclimarketplace

Research

Skill arsity/scholar-tools/skills/research

Academic research lifecycle for AI/ML papers — discover, deep-read, discuss/brainstorm, cite (BibTeX via DBLP→CrossRef→S2), write paper sections. Integrates Semantic Scholar / arXiv / AlphaXiv / OpenReview / DBLP, runs venue-quality gates (CCF, impact factor), and auto-injects expert knowledge from 85 bundled AI/ML domain skills across 21 categories (architectures, fine-tuning, RAG, inference serving, alignment, interpretability, evaluation, MoE, long-context, multimodal, etc.) — users do NOT invoke those directly; this skill routes to them. Trigger on "find papers on…", "what's new in…", "let's brainstorm research…", "is this paper any good?", "give me the bibtex", "help write related work", "reviews for <paper>", "citation graph of…". Not for product/framework how-tos, rewriting a doc into paper format, cleaning messy BibTeX, or vendor blogs / whitepapers / tutorials.From its SKILL.md

Install
npx -y skills add arsity/scholar-tools --skill research

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

34.3 KB, as published. Nobody here has run it

Research Skill

Full academic research lifecycle: discover, discuss, read, cite, write.

Preload

On every invocation, before doing anything else:

  1. Load skill router: Read phases/skill-router.md for domain skill mapping. Parse any --domain or --domain-only flags from user input.

Entry Point

Parse user intent from /research <args> and route to the appropriate phase module.

Input patternPhaseModule
/research discover "topic"discover (consolidated)phases/discover.md
/research discussdiscuss (current session)phases/discuss.md
/research discuss <paper>discuss (from specific paper)phases/discuss.md
/research read <paper>read (standalone)phases/read.md
/research cite <paper>citephases/cite.md
/research write <section>writephases/write.md
Ambiguous inputAsk user to clarify—

<paper> accepts: arXiv ID, DOI, or paper title (with clarify flow if ambiguous). See Unified Input Parsing section below.

All commands support optional --domain <categories> or --domain-only <categories> flags. See Unified Input Parsing section for details.

Workspace

On first invocation, create .research-workspace/ in the current working directory if it doesn't exist:

mkdir -p .research-workspace/sessions
echo '{"sessions": [], "current_session": null}' > .research-workspace/state.json

Each discover invocation creates a session: .research-workspace/sessions/{topic-slug}-{date}/ Contents:

  • discover.json — search results with verdicts + landscape summary
  • discuss/brief.json — research brief from discuss phase
  • read/{paper_id}.json — structured paper analyses
  • cite/{paper_id}.bib — verified BibTeX entries
  • cite/cite-log.json — citation metadata and sources
  • write/{section}.md — generated section text with metadata (output format, citations used, review gates applied)
  • cache/{paper_id}/ — raw paper content cache (see Paper Cache)
  • checkpoints/ — phase completion checkpoints (see State Persistence)

Paper Cache

Fetched paper content is expensive (network latency, rate limits, AlphaXiv/arXiv availability). After context compaction, all prior reads are lost. The cache stores raw content locally so it never needs to be re-fetched.

Cache directory structure

.research-workspace/sessions/{slug}/cache/{paper_id}/
├── overview.md          # AlphaXiv structured overview (if available)
├── fulltext.md          # AlphaXiv full text (if available)
├── paper.pdf            # arXiv or publisher PDF (if downloadable)
├── supplementary.pdf    # Supplementary/appendix PDF (if found)
├── openreview/
│   ├── reviews.json     # OpenReview official reviews (if venue uses OpenReview)
│   ├── rebuttal.json    # Author rebuttals (if available)
│   ├── meta_review.json # AC/SAC meta-review (if available)
│   ├── decision.json    # Accept/reject decision (if available)
│   └── discussion.json  # Threaded replies: author comments, reviewer follow-ups, ethics reviews
└── cache_meta.json      # What was cached, when, from where

cache_meta.json schema

{
  "paper_id": "s2_id or arxiv_id",
  "arxiv_id": "2401.12345",
  "doi": "10.xxxx/...",
  "cached_at": "ISO 8601",
  "contents": {
    "overview": { "source": "alphaxiv", "status": "cached|404|not_attempted" },
    "fulltext": { "source": "alphaxiv", "status": "cached|404|not_attempted" },
    "pdf": { "source": "arxiv|publisher|s2_open_access", "status": "cached|404|not_attempted" },
    "supplementary": { "source": "publisher|arxiv", "status": "cached|404|not_attempted" },
    "openreview": { "source": "openreview_api", "status": "cached|not_found|private|auth_failed|no_credentials|error|not_attempted", "venue": "ICLR 2024" }
  }
}

Cache protocol

On any paper content fetch (read, discover quick-read, discuss knowledge gap):

  1. Check cache first: Look for .research-workspace/sessions/{slug}/cache/{paper_id}/. If cache_meta.json exists, read it to determine what's available.
  2. Use cached content: If the needed content type has status: "cached", read from the local file. Do not re-fetch.
  3. Fetch and cache on miss: If status is "not_attempted" or the cache directory doesn't exist, fetch from the network and save to cache.
  4. Respect 404s: If a previous fetch returned 404 (status: "404"), do not retry — the content genuinely doesn't exist. Exception: retry after 7 days (AlphaXiv may add new papers).
  5. Cross-session sharing: The cache is per-session. If the same paper appears in a different session, it will be re-fetched (sessions represent different research topics and may need different timeframes of content).

OpenReview integration

For papers published at venues that use OpenReview, attempt to fetch review records. This is a best-effort enhancement — all other features work without it.

Authentication required: The OpenReview API v2 (https://api2.openreview.net) requires a Bearer token. Obtain via POST /login with username/password. If no credentials are configured, skip entirely (log warning, set status: "no_credentials"). If /login returns mfaPending, log warning and skip (MFA accounts are not supported — they need an interactive challenge).

Credentials config: Set OPENREVIEW_USER and OPENREVIEW_PASS in .claude/settings.json under "env".

Fetch flow (when credentials are available — run every step with a short Python one-liner via python3 -c "...", using urllib.request and json.loads; no external deps):

  1. Detect OpenReview venue: Check if the paper's venue (from S2 metadata) is known to use OpenReview. Known venues: ICLR, NeurIPS, ICML, AAAI, CVPR, ICCV, ECCV, COLM, EMNLP, ACL, NAACL, AISTATS, UAI, KDD, The Web Conference, TMLR, and ARR (review-only, not a publication venue). This list is not exhaustive — if a venue is not listed but the paper has an OpenReview URL in S2 metadata, attempt fetch anyway.
  2. Authenticate: POST https://api2.openreview.net/login with Content-Type: application/json and body {"id": "<OPENREVIEW_USER>", "password": "<OPENREVIEW_PASS>"}. Parse response JSON — if mfaPending is truthy, set status: "auth_failed" and stop (MFA not supported). Otherwise extract token (valid 24h). Keep the token in memory for subsequent requests; if it must be persisted, use a tempfile.NamedTemporaryFile(mode='w', delete=False) with os.chmod(path, 0o600) and clean up on exit.
  3. Search OpenReview: GET https://api2.openreview.net/notes/search?term=<url_encoded_title>&source=forum&limit=3 with Authorization: Bearer <token>. Match by normalized title equality (lowercase, strip whitespace). If the venue ID is known, add &content.venueid=<venue_id> to narrow results.
  4. Fetch reviews: If a forum is found, GET https://api2.openreview.net/notes?forum=<forum_id>&limit=1000 with the same Bearer header. Classify notes using a dual-signal approach — check invitations[] first (strongest signal when present), then fall back to signatures + content keys (needed because invitation is often null for published papers):
    • Official reviews: invitation ending in Official_Review OR (signatures contains Reviewer_* AND content has review-like keys: summary, strengths, weaknesses, rating, confidence, soundness — field names vary by venue, e.g., review, main_review, recommendation)
    • Meta-reviews: invitation ending in Meta_Review OR (signatures contains Area_Chair_*/Senior_Area_Chair_* AND content has metareview key)
    • Decisions: invitation ending in Decision OR (signatures contains Program_Chairs AND content has decision key)
    • Author rebuttals: signatures contains Authors AND replyto points to a note already classified as a review
    • Discussion: all remaining threaded replies (author comments on forum root, reviewer follow-ups, ethics reviews, official comments)
    • Notes with replyto equal to the forum ID are direct replies. Notes with replyto pointing to another note are threaded discussion.
  5. Parse v2 content shape: In API v2, note content fields are nested: note.content.{field}.value (not note.content.{field} directly). For example, rating at note.content.rating.value (e.g., "8: accept, good paper"), decision at note.content.decision.value (e.g., "Accept (poster)"). Review text may span multiple fields depending on venue — common keys include summary, strengths, weaknesses, review, main_review, comment, recommendation. Extract all content keys, don't hardcode a single field. Some fields may also have note.content.{field}.readers controlling visibility. Caution: API responses may contain raw control characters (tabs, newlines in review text). Parse with json.loads(text, strict=False); never strip control chars from stored artifacts (only do so for disposable human-readable inspection).
  6. Save: Write reviews.json, rebuttal.json, meta_review.json, decision.json, discussion.json to cache/{paper_id}/openreview/.
  7. Graceful degradation: Handle failures with appropriate status:
    • Auth failure (401) → status: "auth_failed", log warning
    • Restricted data (403 or notes returned with redacted/missing fields) → status: "private". Do NOT freeze as permanent — reviews may become public after camera-ready
    • Not found (empty results) → status: "not_found"
    • Network/server error (500/502/503/504) → retry once, then status: "error"
    • OpenReview data is valuable but never blocking

How cache integrates with phases

PhaseCache interaction
read Step 2Check cache before AlphaXiv/arXiv/publisher fetch. Save all fetched content to cache. Also attempt OpenReview fetch for the paper.
discover Step 6 (quick-read)Check cache for overview.md. Save if fetched. Skip full OpenReview fetch (too heavy for batch quick-read).
discuss Phase 3 (knowledge gap)Check cache before quick-read fetch. Save if fetched.
discuss Phase 5 (reviewer simulation)If openreview/reviews.json exists in cache for any analyzed paper, incorporate real reviewer concerns into the simulation — real objections take priority over simulated ones.
write (related-work, intro)Read cached content for positioning accuracy instead of relying on summaries alone.

State Persistence

Long research sessions (especially discover → discuss → write chains) risk losing progress to context compaction. Each phase writes a checkpoint on completion so work can be resumed.

Checkpoint format

Save to .research-workspace/sessions/{slug}/checkpoints/{phase}_{timestamp}.json:

{
  "phase": "discover|discuss|read|cite|write",
  "status": "completed|in_progress|failed",
  "timestamp": "ISO 8601",
  "completed_steps": ["step1", "step2"],
  "pending_steps": ["step3"],
  "key_artifacts": {
    "discover_json": "relative path if exists",
    "brief_json": "relative path if exists",
    "read_analyses": ["paper_id1", "paper_id2"],
    "cite_log": "relative path if exists"
  },
  "context_summary": "1-2 sentence summary of what was accomplished and what remains",
  "skills_loaded": ["clip"],
  "user_decisions": ["chose direction A over B", "skipped experiment design"]
}

Write checkpoint

Each phase writes its checkpoint after saving its primary artifact (discover.json, brief.json, etc.). The checkpoint is a lightweight pointer — the real data lives in the phase artifacts.

Recovery on context compaction

If a session resumes after context compaction (detected by: user continues a /research command but prior conversation context is unavailable):

  1. Read .research-workspace/state.json → identify current session
  2. Read the latest checkpoint in checkpoints/ → reconstruct phase state
  3. Read referenced artifacts (discover.json, brief.json, etc.) as needed
  4. Reload domain skills from the checkpoint's skills_loaded list
  5. Resume from pending_steps — do not re-run completed steps
  6. Inform the user: "Resuming from checkpoint: {context_summary}"

Discuss phase mid-conversation checkpoints

The discuss phase is uniquely long-running (multi-turn). It writes incremental checkpoints at two points:

  • After Phase 2 (Assumption Surfacing) completes
  • After Phase 4 (Adversarial Novelty Check) completes

These capture the evolving research brief so that even if compaction occurs mid-discussion, the accumulated findings, open problems, and proposed directions are preserved.

Unified Input Parsing

Phases that accept a paper identifier (discuss, read, cite) share this logic. Discover takes a topic description, not a paper identifier.

Input Types

  • arXiv ID (e.g., 2401.12345): Direct lookup via s2_match.py or S2 API
  • DOI (e.g., 10.1109/...): Direct CrossRef/S2 lookup
  • Free text (paper title or keywords):
    1. Try s2_match.py "<text>" for exact title match
    2. If no exact match: s2_search.py "<text>" 5 + dblp_search.py "<text>" 5

Clarify Flow

When free-text search returns multiple candidates, present each with:

  • Title + authors (first 3) + year + venue
  • One-sentence core contribution (from abstract)
  • Quality marker (CCF/JCR tier via venue_info.py, citation count from S2 metadata)

User selects one → proceed to the requested phase.

Domain Override Flags

All commands support:

  • --domain <cat1,cat2>: Additive — merge with auto-detected categories
  • --domain-only <cat1,cat2>: Exclusive — use only these categories

Category names match the skill-router mapping table (semantic match OK).

Timeout Policy

Each parallel search agent has a 60-second timeout. If an agent times out or errors, proceed with results from the remaining agents. Log the failure but do not block.

Iron Rules

  1. Zero hallucination citations — every citation from an API call, never from model memory
  2. BibTeX priority — DBLP > CrossRef > S2 (AlphaXiv is content-only, not a citation source)
  3. Exhaustive search escalation — when a retrieval task has no directly relevant results after the applicable primary searches, follow the Search Escalation Protocol before accepting "not found"
  4. Quality gate — no paper presented to user without quality evaluation
  5. Source tracing — every citation tagged with data source ("via DBLP", "via CrossRef", etc.)
  6. Own model for analysis — never rely on AlphaXiv's AI-generated answers; use their content extraction, analyze with own Claude
  7. Domain skill grounding — domain skills provide expert context, but all factual claims must still trace to paper content or API responses, never to skill-generated assertions alone
  8. Adversarial before commitment — no research direction is finalized without adversarial novelty check against existing literature
  9. Multi-perspective review for framing — abstract and introduction must pass reviewer, AC/SAC, and senior researcher perspectives + cross-model gate before finalization; related-work must pass coverage & fairness check (Claude + Codex)
  10. Simplicity preference — between two approaches of similar merit, prefer the simpler one
  11. Verify before completion — invoke superpowers:verification-before-completion before presenting final output in cite, write, and discover phases (see each phase for details)
  12. Root cause before retry — when any script or API call fails, diagnose the root cause (API key expired? rate limit? malformed query? network error?) before retrying or switching strategy. Never retry blindly. (Borrowed from superpowers:systematic-debugging)

Search Escalation Protocol

When a retrieval task has no directly relevant results after the applicable primary searches, classify the failure before escalating:

Failure classification

Failure typeMeaningAction
Zero resultsQuery returned nothing from primary sourcesEscalate through strategy ladder
Exact-match missTitle/DOI/arXiv ID lookup failedCheck alternate titles (preprint vs. published), arXiv ID variants, DOI redirects
Metadata mismatchFound paper but required fields missingTry alternate source in priority order: DBLP → CrossRef → S2 (per Iron Rule #2)
Indexing lagPaper too new for databaseCheck arXiv directly, AlphaXiv MCP retrieval, or accept "not yet indexed"
Query driftResults returned but none directly relevantTighten query specificity, add field-specific keywords, filter by year
Version driftPreprint title/content differs from published versionSearch both titles, check DOI and arXiv ID separately
Timeout or rate limitOperational failureRetry once after delay, then proceed with remaining sources
Source outageAPI downSkip source, log warning, proceed with remaining sources

Strategy ladder

Work through these strategies in order. Stop when directly relevant results are found and verified enough for the current phase. Earlier strategies are cheaper; later strategies cast a wider net.

  1. Normalize query: expand acronyms, try alternate spellings/aliases, singular↔plural
  2. Exact-match probe: s2_match.py for precise titles; DOI/arXiv ID direct lookup
  3. Adjust year window: narrow for recent work, widen for foundational terminology (cheap parameter tweak)
  4. Decompose: split compound queries into task + method + dataset + metric, search each separately
  5. Switch retrieval mode: s2_search.py → s2_bulk_search.py → DBLP → CrossRef title search
  6. Pivot to graph search: if any seed paper exists, use s2_citations.py, s2_references.py, s2_recommend.py
  7. Body search: s2_snippet.py for method names or claims not in titles/abstracts
  8. Abstract to adjacent fields: generalize the problem and search neighboring domains (label results as analogical evidence, not direct prior art)

Trigger conditions

Trigger conditionTypical phase
All applicable primary searches return 0 results for a non-trivial query (S2 + AlphaXiv in discover; DBLP + CrossRef + S2 in cite)discover Step 3-4, cite Step 2
2+ consecutive API timeouts or HTTP errors across any scriptsany phase
Knowledge-gap search in discuss cannot find the referenced method/baselinediscuss Phase 3
>30% of \cite{} references fail verification during writewrite Step 4

Stop condition and attempt ledger

After exhausting the ladder, or when a strategy succeeds, produce an attempt ledger:

{
  "query_original": "...",
  "failure_type": "zero_results|exact_match_miss|metadata_mismatch|indexing_lag|query_drift|version_drift|timeout_or_rate_limit|source_outage",
  "attempts": [
    {
      "strategy": "normalize|exact_match|adjust_year|decompose|switch_mode|graph_search|body_search|adjacent_fields",
      "query": "expanded query text",
      "source": "s2_search|s2_bulk|s2_match|s2_citations|s2_references|s2_recommend|s2_snippet|dblp_search|dblp_bibtex|arxiv_bibtex|crossref_search|doi2bibtex|alphaxiv_agentic|alphaxiv_full_text|alphaxiv_embedding",
      "result_count": 0,
      "status": "matched|zero_results|irrelevant|timeout|rate_limited|source_down|error",
      "notes": "optional: error details, HTTP status, why results were irrelevant"
    }
  ],
  "final_outcome": "found|not_found_after_exhaustive_search|genuine_null|blocked_by_operational_failure",
  "resolved_by": "normalize|exact_match|adjust_year|decompose|switch_mode|graph_search|body_search|adjacent_fields|null"
}

"Not found after exhaustive search" is a valid, honest outcome. Some papers are not indexed, some methods have no prior work, and some queries target genuinely unexplored territory. Never fabricate papers or cite from model memory to avoid a null result.

Cross-Model Collaboration

Use a second LLM (via Codex MCP: mcp__codex__codex) throughout the lifecycle. The purpose is to surface blind spots that a single model misses and to create a three-way discussion (user + Claude + Codex) for richer exploration.

Roles

Codex participates in three modes:

  • Co-thinker: Divergent phases (brainstorming, discussion) — Codex contributes independent perspectives alongside Claude. The user gets two models' views to synthesize.
  • Adversarial reviewer: Convergent phases (novelty check, reviewer simulation, final commit) — Codex challenges the direction, looking for weaknesses.
  • Cold reader: Simplicity test — Codex receives minimal context to test whether the idea is self-explanatory.

When to invoke

#ModePhaseWhat to sendWhat to ask
1Co-thinkerdiscuss Phase 2 (Assumption Surfacing)Papers analyzed + field context from discover"What assumptions does this field take for granted? What would break if each assumption were violated?"
2Co-thinkerdiscuss Phase 3 (Discussion Loop)Current discussion state (latest findings, open questions, proposed angles)Phase 3-specific: varies per turn. See discuss.md for integration details.
3Adversarialdiscuss Phase 4 (Adversarial Novelty Check)Proposed direction + closest existing work"As a skeptical reviewer at {target venue}: (1) Is the claimed novelty real or superficial? (2) What existing work was missed? (3) What's the strongest argument against this direction?"
4Adversarialdiscuss Phase 5 (Reviewer Simulation)Proposed direction + research brief so far"Generate 3-4 specific reviewer objections. For each: the weakest claim, the missing baseline, the essential ablation, and severity (High/Medium/Low)."
5Adversarialdiscuss Phase 6 (Significance Test)Proposed direction + significance analysis from Claude"Evaluate this direction on three tiers: (1) real-world impact with concrete failure modes, (2) would the community think differently if this succeeds, (3) expected improvement magnitude vs. SOTA. Flag any tier that is weak."
6Cold readerdiscuss Phase 7 (Simplicity Test)User's 2-sentence explanation ONLY — no research brief, no context"Based only on these 2 sentences, explain back what the research idea is and what makes it novel. What is unclear or ambiguous?"
7Adversarialdiscuss Phase 8 (Experiment Design)Completed experiment plan draft + research brief"What baselines are missing? What essential ablation is not listed? Are there better-suited datasets? Is the expected results table realistic?"
8Adversarialdiscuss Phase 9 (Convergence Decision)Complete research brief"Given everything in this brief, would you recommend this direction for {target venue}? What is the single biggest risk? What would make you abandon this direction?"
9Adversarialwrite Step 5.5 (abstract + intro only)Draft text + research brief"As an AC at {target venue}: (1) Does the motivation hold up? (2) Is the contribution clearly distinguished from prior work? (3) What would make you desk-reject this?"
10Adversarialwrite related-workDraft related-work section + discover results + read analyses"As a reviewer: (1) What important related work is missing? (2) Is any prior work mischaracterized or unfairly compared? (3) Is the positioning of our contribution honest and precise?"

Protocol

  1. Compose the prompt following the Task Brief (see below) — every Codex call must have GOAL/DELIVERABLE/EVIDENCE/CONSTRAINTS/DONE WHEN/EXCLUSIONS. Do NOT pass the entire conversation history — send only the artifacts listed in the "What to send" column.
  2. Call mcp__codex__codex with the prompt.
  3. For co-thinker mode: present Codex's ideas alongside Claude's, clearly labeled [Codex]. The user synthesizes both.
  4. For adversarial mode: parse the response for actionable concerns (not stylistic preferences). Present labeled [Cross-model review].
  5. The user decides which concerns/ideas to act on.

Phase 3 integration details

In the Discussion Loop, Codex participates as an ongoing third voice. The interaction model:

  1. User raises a question or proposes a direction
  2. Claude responds with analysis (infused with domain skill expertise)
  3. Codex is consulted on the same question — but phrased to elicit a different angle (e.g., if Claude analyzed from a methodology perspective, ask Codex to consider from a practical/application perspective, or vice versa)
  4. User sees both responses, picks what resonates, steers the next turn

Not every turn requires Codex. Use judgment:

  • Invoke Codex when: the discussion hits a fork (multiple possible directions), a novel claim is made, the user questions a conclusion, or Claude is uncertain
  • Skip Codex when: the turn is clarificational, the user is providing context, or the question is about a specific paper's content (domain skills + read phase handle this)

What this is NOT

  • Not a score-chasing loop: No "iterate until score ≥ N." That optimizes for LLM preferences, not research quality.
  • Not a rubber stamp: If Codex finds nothing, that's a valid signal.
  • Not blocking: If Codex MCP is unavailable, all phases proceed with Claude-only analysis (log warning). No phase is gated on Codex availability.

Task Brief

Every delegated task — spawned agent, Codex review call, or subsearch dispatch — must follow a 6-element brief. This prevents vague tasking, bloated context, inconsistent outputs, and scope drift.

Schema

GOAL        — What decision this task informs; why it matters to the current phase
DELIVERABLE — Exact artifact to produce (format, fields, structure)
EVIDENCE    — Allowed evidence sources (which papers, which APIs, what context to send)
CONSTRAINTS — Result caps, token budget, timeout
DONE WHEN   — Acceptance criteria (how to verify the output is correct and complete)
EXCLUSIONS  — Forbidden behavior (what to exclude, what NOT to do)

Application by delegation type

Spawned search subagents (discover Step 3, dispatched via superpowers:dispatching-parallel-agents):

GOAL:       Find papers relevant to "{topic}" for landscape analysis
DELIVERABLE: JSON objects, each with: paper_id, title, year, venue, citations, doi, arxiv_id, authors, source
EVIDENCE:   Agent 1 (S2 subagent) — S2 API only (s2_search.py, s2_bulk_search.py)
            Agent 2 (AlphaXiv subagent) — three claude.ai-bound AlphaXiv MCP tools (agentic_paper_retrieval, full_text_papers_search, embedding_similarity_search), issued as three parallel tool calls in a single subagent message. Subagents inherit the top-level session's MCP bindings (empirically verified).
CONSTRAINTS: Top 20 results for S2; ~10 per AlphaXiv tool; 60-second timeout per subagent
DONE WHEN:  ≥1 result returned with all required fields populated; exit 0
EXCLUSIONS: Don't analyze, rank, or summarize papers — just retrieve and return raw results. Don't cross sources.

Codex review calls (all 10 integration points):

GOAL:       {varies — e.g., "Surface assumptions this field takes for granted" or "Find weaknesses in this research direction for {venue}"}
DELIVERABLE: Structured response: numbered findings, each with a concrete claim and evidence
EVIDENCE:   Only the artifacts listed in the "What to send" column of the invocation table — never the full conversation history
CONSTRAINTS: 3-5 actionable findings; no filler
DONE WHEN:  Each finding is specific enough to act on (names a paper, identifies a gap, flags a weakness)
EXCLUSIONS: Don't restate what was sent; don't make stylistic suggestions; don't hedge with "this could be strengthened" — say what's wrong and why

Knowledge-gap subsearches (discuss Phase 3):

GOAL:       Fill knowledge gap identified during discussion: "{specific method/baseline/claim}"
DELIVERABLE: 1-3 relevant papers with title, year, venue, and one-sentence summary of relevance
EVIDENCE:   S2 search + DBLP search; use the exact method/baseline name as query
CONSTRAINTS: Top 3 results; 30-second timeout per source
DONE WHEN:  At least one paper found that addresses the gap, or explicit "not found after exhaustive search"
EXCLUSIONS: Don't fabricate papers; don't use model memory; don't return tangentially related work

Write-phase review gates (Triple Review Gate + Codex):

GOAL:       {varies — e.g., "As an AC at {venue}, evaluate whether this abstract/intro would survive desk review"}
DELIVERABLE: 2-3 specific revision suggestions, each with: the problematic text, what's wrong, and a concrete fix direction
EVIDENCE:   Only the draft section text + research brief — not the full paper or conversation
CONSTRAINTS: Focus on substance (motivation, contribution clarity, positioning) not prose style
DONE WHEN:  Each suggestion identifies a specific passage and explains why it's a problem
EXCLUSIONS: Don't praise what works; don't suggest word-level edits; don't repeat the Iron Rules back

When to skip

Not every delegation needs full formality. Skip the brief for:

  • Single-script calls (venue_info.py, ccf_lookup.py) — these have fixed I/O
  • Clarificational Codex turns in discuss Phase 3 where the user is providing context

Language

All output in English. For uncommon vocabulary (GRE-level), add Chinese translation in parentheses.

Scripts

All scripts are in skills/research/scripts/. Key scripts:

Search

ScriptPurpose
s2_search.pyS2 relevance-ranked semantic search
s2_bulk_search.pyS2 boolean bulk search with year filtering
s2_batch.pyS2 batch metadata by paper IDs (NOT a search)
s2_citations.pyPapers that cited a given paper
s2_references.pyPapers cited by a given paper
s2_recommend.pyPaper recommendations from positive/negative examples
s2_snippet.pySearch within paper bodies for specific passages
s2_match.pyExact title match (single result)
dblp_search.pyDBLP publication search
dblp_bibtex.pyFetch condensed BibTeX via DBLP search API (title + author + year)
arxiv_bibtex.pyFetch @misc BibTeX from arxiv.org (arXiv ID)
crossref_search.pyCrossRef search (fallback)
doi2bibtex.pyDOI → BibTeX via content negotiation

Quality Evaluation

ScriptPurpose
venue_info.pyVenue quality summary (CCF + IF + quartile)
ccf_lookup.pyCCF ranking lookup
if_lookup.pyImpact factor lookup
author_info.pyAuthor h-index and stats

Config

ScriptPurpose
init.pyRate limit helpers, DBLP host fallback

Dependencies

Required skills/plugins

  • 85 domain skills from Orchestra-Research/AI-Research-SKILLs — bundled in vendor/ai-research-skills/ and not registered as standalone skills (only /research is exposed). The skill router loads them via Read on demand. Includes ml-paper-writing, brainstorming-research-ideas, creative-thinking-for-research, and all 21 domain categories. See phases/skill-router.md § "Loading Vendor Skills" for the load mechanism.
  • humanizer skill — style review for write phase
  • superpowers:dispatching-parallel-agents — parallel search in discover phase
  • superpowers:verification-before-completion — output verification in cite/write/discover phases

Optional MCP servers

  • Codex MCP (mcp__codex__codex) — cross-model collaboration throughout the lifecycle (discuss Phases 2-9, write Step 5.5 + 5.6). See Cross-Model Collaboration section for all 10 invocation points. If unavailable, all phases proceed with Claude-only analysis (log warning). Recommended but not blocking.
  • AlphaXiv MCP (mcp__claude_ai_alphaXiv__*, via the claude.ai connection) — powers the second parallel search source in discover Step 3. The three tools (agentic_paper_retrieval, full_text_papers_search, embedding_similarity_search) are issued as three parallel tool calls inside the AlphaXiv subagent (dispatched alongside the S2 subagent via superpowers:dispatching-parallel-agents). If the MCP server is unavailable, discover falls back to S2 results only (log warning). Recommended for broader coverage but not blocking.

Required API keys

Optional API credentials

  • OpenReview: set OPENREVIEW_USER and OPENREVIEW_PASS in .claude/settings.json under "env". Register at: https://openreview.net/profile. Without these, OpenReview review/rebuttal data will not be fetched (all other features work normally).

Installation prompt

If dependencies are missing on first use:

Before using /research, please ensure:

1. Install required skills/plugins:
   - Orchestra-Research AI-Research-SKILLs (provides ml-paper-writing, brainstorming-research-ideas, creative-thinking-for-research, and 21 domain skill categories)
   - humanizer skill

2. Set up API keys in your .claude/settings.json:
   { "env": { "S2_API_KEY": "your-key-here", "OPENREVIEW_USER": "optional", "OPENREVIEW_PASS": "optional" } }
   Claude Code automatically exports env entries as environment variables.
   - Semantic Scholar: https://www.semanticscholar.org/product/api/api-key
   - OpenReview (optional): https://openreview.net/profile

Rate Limits

ServiceLimitStrategy
S21 req/sec (with key)Sequential within agent, use batch/bulk
DBLP~1 req/secSequential, 1s delay
CrossRefNo strict limitPolite usage
AlphaXiv MCPNo strict limitThree retrieval tools run in parallel inside Agent 2
AlphaXiv fetch (raw markdown)No strict limitRespect 404s, no retry loop

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.