Agentsociety Literature Search

About this prompt

Use when academic literature needs to be gathered or refreshed for a research topic, especially at the beginning of a project.

Prompt body

# 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`:

```bash
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:

```json
{
  "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": "...",
      "extra_fields": {
        "authors": ["..."],
        "year": 2024,
        "url": "https://..."
      }
    }
  ]
}
```

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:

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

Variables

Best for

• •First-use as-is; the defaults work.
• •Fork if your audience or voice is significantly different from the author's.
• •Chain into a workflow when one prompt isn't enough — multi-step flows are the usual next move.