| 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
- Confirm
.env has LITERATURE_SEARCH_MCP_URL and LITERATURE_SEARCH_API_KEY.
- Read
TOPIC.md if it exists. Use the research question, scope, target population, and key constructs to form the query.
- Run one focused search with the default command (returns 10 papers). Only add
--limit when the user explicitly asks for a different count.
- Use
--year-from / --year-to when the user wants recent work or a defined historical window.
- Use
--multi-query for topics with multiple constructs, methods, or domains.
- Inspect
papers/literature_index.json and papers/full_texts/ after the command completes.
- Summarize findings in research terms, not just as a list of titles.
- 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 fieldsreferences/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}'
