Skip to content

skill.md

Latest commit

 

History

History
224 lines (154 loc) · 8.49 KB

skill.md

File metadata and controls

224 lines (154 loc) · 8.49 KB

Elicit Research — Claude Code Skill

Search 125M+ academic papers and generate comprehensive research reports, directly from your terminal.

Triggers

  • "search papers", "find papers", "find research", "literature search", "paper search"
  • "create report", "research report", "generate report", "literature review"
  • "find studies", "search studies", "academic search"
  • "what does the research say", "what does the evidence say", "what does the literature say"

Prerequisites

The ELICIT_API_KEY environment variable must be set. The user can get an API key in their account settings at https://elicit.com/settings.

If ELICIT_API_KEY is not set, tell the user:

You need an Elicit API key. Get one at https://elicit.com/settings, then set it:

export ELICIT_API_KEY="your-key-here"

API Reference

Base URL: https://elicit.com/api/v1

All requests require:

  • Authorization: Bearer $ELICIT_API_KEY header
  • Content-Type: application/json header (for POST requests)

1. Search Papers

POST /api/v1/search

Search across 125M+ academic papers.

curl -s "https://elicit.com/api/v1/search" \
  -H "Authorization: Bearer ${ELICIT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "effects of sleep deprivation on cognitive performance",
    "maxResults": 10
  }'

Request body:

Field Type Required Description
query string Yes Natural-language research question or topic
maxResults integer No Number of results (1-5000). Default: 10
filters object No Optional filters (see below)

Common filters:

Field Type Description
minYear integer Minimum publication year
maxYear integer Maximum publication year
typeTags string[] Study types: "Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"
pubmedOnly boolean Only return PubMed-indexed papers
maxQuartile integer Journal quartile (1 = top 25%)

Response: { "papers": [{ "title", "authors", "year", "abstract", "doi", "venue", "citedByCount", "urls" }] }

2. Create a Research Report

POST /api/v1/reports

Start an asynchronous report (5-15 minutes to complete).

curl -s "https://elicit.com/api/v1/reports" \
  -H "Authorization: Bearer ${ELICIT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "researchQuestion": "What is the evidence for melatonin improving sleep quality?",
    "maxSearchPapers": 50,
    "maxExtractPapers": 10
  }'

Response: { "reportId": "...", "status": "processing", "url": "https://elicit.com/review/..." }

3. Get Report Status

GET /api/v1/reports/{reportId}

Poll until status is completed or failed. Add ?include=reportBody for full markdown content.

Response when completed: { "status": "completed", "result": { "title", "summary" }, "url", "pdfUrl", "docxUrl" }

4. List Reports

GET /api/v1/reports

Query params: limit, cursor, source (api/user), status (processing/completed/failed).

Full API details

For complete filter options, response schemas, and all fields, fetch the OpenAPI spec:

curl -s https://docs.elicit.com/openapi.json

This does not require authentication.

Instructions for Claude

When to use Search vs. Reports

Use Search (POST /search) when the user wants to:

  • Find specific papers on a topic
  • Get a quick list of references
  • Check if research exists on something
  • Look up a particular study or author's work
  • Get paper metadata (DOI, citation count, venue)
  • Do a quick literature check while working on code or documentation

Use Reports (POST /reports) when the user wants to:

  • A thorough analysis or literature review
  • A synthesized summary of evidence on a question
  • A deep dive into a research area
  • Something they could cite or share with colleagues
  • An answer to a nuanced research question that requires reading multiple papers

When in doubt, start with Search. It is instant and gives the user something to work with. Offer to create a full report if they need deeper analysis.

How to Execute Requests

Use the Bash tool with curl to call the Elicit API. Always use -s (silent) to suppress progress output, and pipe through jq for readable formatting.

Before making any authenticated API request, check that ELICIT_API_KEY is set:

[ -z "$ELICIT_API_KEY" ] && echo "ERROR: ELICIT_API_KEY is not set" && exit 1

Formatting Search Results

When presenting search results to the user, format them as a clean, scannable list. For each paper include:

  1. Title (bold)
  2. Authors (first author et al. if more than two)
  3. Year, venue, and citation count on one line
  4. A one-sentence summary from the abstract (not the full abstract, unless the user asks)
  5. DOI link if available

Example format:

Found 5 papers on "effects of CRISPR on gene therapy":

1. **CRISPR-Cas9 Gene Therapy for Sickle Cell Disease**
   Frangoul et al. (2021) - New England Journal of Medicine - Cited by 847
   First clinical trial showing CRISPR-based therapy can eliminate vaso-occlusive crises in sickle cell patients.
   DOI: https://doi.org/10.1056/NEJMoa2031054

2. **In vivo CRISPR editing with no detectable genome-wide off-target mutations**
   Akcakaya et al. (2018) - Nature - Cited by 623
   Demonstrates a method for verifying CRISPR edits have no unintended off-target effects in vivo.
   DOI: https://doi.org/10.1038/s41586-018-0500-9

If the user asked a specific question (not just "find papers on X"), synthesize a brief 2-4 sentence answer from the abstracts before listing the papers.

Formatting Report Results

When a report completes, present:

  1. The report title and a link to view it on Elicit
  2. The summary
  3. Links to PDF and DOCX downloads if available
  4. Offer to fetch the full report body if the user wants to read it inline

Example:

Your report is ready:

**What is the evidence for melatonin improving sleep quality?**
https://elicit.com/reports/abc123

Summary: Melatonin supplementation shows moderate evidence for improving sleep onset
latency and overall sleep quality, particularly in populations with delayed sleep phase
disorder. Effect sizes are generally small to moderate across meta-analyses...

Download: [PDF](https://...) | [DOCX](https://...)

I can fetch the full report text if you'd like to read it here.

Handling Report Polling

Reports take 5-15 minutes. Use this polling approach:

  1. Create the report and immediately show the user the report URL so they can watch progress on Elicit.
  2. Poll every 30 seconds using a background bash loop.
  3. When complete, present the results.
  4. If polling exceeds 20 minutes, stop and tell the user the report is still processing with a link to check it on Elicit.

Use the GET /api/v1/reports/{reportId} endpoint to poll. Check the response status field — loop until it is completed or failed, sleeping 30 seconds between polls. Time out after 20 minutes.

Rate Limits and Best Practices

  • Do not make concurrent requests. Send one request at a time.
  • For search, start with maxResults: 10 unless the user asks for more.
  • For reports, use the default paper limits unless the user asks for a broader or narrower search.
  • If you receive a 429 (rate limit) response, wait 60 seconds before retrying.
  • If you receive a 401 response, the API key is invalid or expired. Ask the user to check their key.
  • If you receive a 402 response, the user's plan quota is exhausted. Let them know.
  • Report creation counts against the user's workflow quota (varies by plan). Do not create reports speculatively; only create them when the user explicitly asks.

Workflow Integration Tips

When the user is working in a codebase and asks a research question:

  • Researching while coding: If someone asks "are there papers on [algorithm/technique]?", use Search to find relevant papers and present them concisely so they can get back to coding.
  • Finding papers to cite: If someone is writing documentation or a paper and needs references, search for relevant papers and format the results with DOIs ready to cite.
  • Exploring a domain: If someone is starting work in an unfamiliar area, suggest starting with a Search to get oriented, then offer a Report for a deeper dive.
  • Evidence-based decisions: If someone is choosing between approaches (e.g., "should I use method A or method B?"), search for comparative studies or create a report framing the question as a comparison.