agentsociety-literature-search

name	agentsociety-literature-search
version	1.0.0
description	Use when academic literature needs to be gathered or refreshed for a research topic, especially at the beginning of a project.

Academic Literature Search

Search academic literature through the academic literature search gateway and save results to the workspace papers/ directory. Queries all configured data sources (local, arXiv, CrossRef, OpenAlex) by default.

The runtime connects via MCP using workspace .env only. You do not need Claude mcp.json for this skill.

When to Use

• User mentions "literature", "papers", "related work", "survey", or "background research"
• Starting a new research topic and TOPIC.md does not yet exist
• Existing TOPIC.md needs enrichment with more references
• User asks "what has been published on X?"
• User asks to refresh or expand papers/literature_index.json

Do NOT use when:

• User already has a well-defined hypothesis and wants to design experiments (use hypothesis skill)
• User needs to run a simulation (use experiment-config skill)
• User only wants to read a local PDF already in the workspace; open or summarize that file directly

Quick Reference

Use the Python interpreter from .env. See CLAUDE.md for setup. Run commands from the workspace root through .agentsociety/bin/ags.py.

Action	Command
Basic search	$PYTHON_PATH .agentsociety/bin/ags.py literature-search "query"
Year range	$PYTHON_PATH .agentsociety/bin/ags.py literature-search "query" --year-from 2020 --year-to 2024
Complex topic	$PYTHON_PATH .agentsociety/bin/ags.py literature-search "complex query" --multi-query
Custom workspace	$PYTHON_PATH .agentsociety/bin/ags.py literature-search "query" --workspace /path/to/dir
List PDF candidates	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text candidates
Download open PDF	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text download --entry 1
Register local PDF	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text register --entry 1 --file /path/to/paper.pdf
Mark no PDF found	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text mark --entry 1 --status no_candidate --reason "No open PDF URL available"
List enrichable entries	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text enrich --dry-run
Mark entry as enriched	$PYTHON_PATH .agentsociety/bin/ags.py literature-full-text enrich --entry 1

Configuration (required)

Set in the workspace .env:

LITERATURE_SEARCH_MCP_URL=https://llmapi.fiblab.net/mcp/
LITERATURE_SEARCH_API_KEY=sk-your-litellm-virtual-key

Use an MCP gateway URL ending in /mcp/ (trailing slash required on fiblab). The API key must be a LiteLLM virtual key (sk-...) with academic literature search permission on that gateway.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query (positional)
--year-from	integer	No	Start year filter
--year-to	integer	No	End year filter
--workspace	string	No	Workspace path (default: cwd)
--multi-query	flag	No	Split complex queries into subtopics

Full-text helper parameters:

Command	Important Parameters	Description
literature-full-text candidates	--entry N optional	Show candidate URLs inferred from literature_index.json
literature-full-text download	--entry N, --url URL optional	Try open PDF URLs and update extra_fields.full_text
literature-full-text register	--entry N, --file PATH	Copy/register a local PDF and update the index
literature-full-text mark	--entry N, --status no_candidate|failed, --reason TEXT	Record why a PDF is unavailable
literature-full-text enrich	--entry N or --dry-run	List or mark entries whose Markdown notes have been enriched via web research

Recommended Workflow

1. Confirm .env has LITERATURE_SEARCH_MCP_URL and LITERATURE_SEARCH_API_KEY.
2. Read TOPIC.md if it exists. Use the research question, scope, target population, and key constructs to form the query.
3. Run one focused search with the default command (returns 10 papers). Only add --limit when the user explicitly asks for a different count.
4. Use --year-from / --year-to when the user wants recent work or a defined historical window.
5. Use --multi-query for topics with multiple constructs, methods, or domains.
6. Inspect papers/literature_index.json and papers/full_texts/ after the command completes.
7. Summarize findings in research terms, not just as a list of titles.
8. For paywalled or failed PDFs, follow "Optional Full-Text Retrieval" below.

Output

papers/
  literature_index.json    # Auto-created/updated catalog
  article_title.md         # Per-article markdown summaries
  full_texts/              # Open-access PDFs (auto-downloaded when available)

Each article contains: title, authors, abstract, year, journal, doi, url, score, source.

Index Contract

papers/literature_index.json follows this shape:

{
  "version": "1.0",
  "created_at": "...",
  "updated_at": "...",
  "entries": [
    {
      "title": "Article title",
      "journal": "Journal or venue",
      "doi": "10.xxxx/xxxx",
      "abstract": "...",
      "file_path": "papers/article_title.md",
      "file_type": "markdown",
      "source": "literature_search",
      "query": "original query",
      "avg_similarity": 0.84,
      "saved_at": "...",
       
         
         
         
      
    
  

Keep file_path pointed at the Markdown note. PDF paths belong in extra_fields.full_text.file_path.

Optional Full-Text Retrieval

The search command automatically tries open-access PDF downloads. Publisher paywalls are not bypassed. See references/full-text-retrieval.md for manual follow-up.

Enriching Notes When PDF Is Unavailable

When a PDF cannot be downloaded, enrich the Markdown note via web search. See references/full-text-retrieval.md (section Enriching Notes via Web Research).

Common Mistakes

Mistake	Fix
Missing trailing slash on fiblab MCP	Use https://llmapi.fiblab.net/mcp/
Only configuring Claude mcp.json	Add LITERATURE_SEARCH_MCP_* to workspace .env
Key works for LLM but not literature	Use sk- key with literature permission on the gateway
Non-MCP URL in LITERATURE_SEARCH_MCP_URL	Use gateway MCP URL https://llmapi.fiblab.net/mcp/

References

• references/data-sources.md — data sources and response fields
• references/full-text-retrieval.md — PDF workflow

Pipeline Position

Predecessors: None (entry point) Successors: hypothesis Required Sub-Skills: None

Progress Tracking

After search completes successfully:

$PYTHON .agentsociety/bin/ags.py research-pipeline update-stage literature_search completed --metadata '{"paper_count": N}'