# LitReview Skill
LitReview Skill is an installable agent skill for end-to-end literature review generation. It helps agents conduct literature reviews with a well-designed and widely used review framework so the search process is broad, iterative, and less likely to miss relevant articles.
The workflow combines keyword search, backward citation expansion, forward citation expansion, iterative screening, structured ranking, full-text reading, knowledge graph construction, and final review writing. This design makes the process more reliable, stable, and consistent than ad hoc paper collection, while keeping a clear audit trail of what was searched, screened, included, and synthesized.
## Workflow
The workflow is iterative: start from a topic, build a seed set, expand by citations, screen repeatedly until saturation, then synthesize the final outputs.
## What It Produces
Root-level deliverables:
- `literature_review.pdf`
- `references.md`
- `knowledge_graph.png`
Supporting editable and machine-readable files are organized into shallow folders such as `plan/`, `logs/`, `search/`, `screening/`, `expansion/`, `fulltext/`, `review/`, `graph/`, and `references/`.
## Install
Clone the repository first:
```bash
git clone https://github.com/Zsun79/LitReviewAI.git
cd LitReviewAI
```
Then install the skill using one of these examples.
### Codex
Copy the skill folder into your local Codex skills directory:
```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/write-literature-review "${CODEX_HOME:-$HOME/.codex}/skills/"
```
Restart Codex after installation so the skill is discovered.
### Claude
Claude currently documents custom skill installation through the app UI as a ZIP upload. Package the skill folder:
```bash
cd skills
zip -r write-literature-review.zip write-literature-review
```
Then in Claude:
1. Open `Customize > Skills`.
2. Click `+`.
3. Choose `Upload a skill`.
4. Upload `write-literature-review.zip`.
## Use
Invoke the skill explicitly:
```text
Use $write-literature-review to write a literature review on retrieval-augmented generation for scientific discovery.
```
For best results, provide:
- Research topic and nearby synonyms
- Target field or venue
- Time window
- Inclusion and exclusion criteria
- Desired review style, such as narrative review, systematic review, survey, or related work section
- Desired citation format, such as APA or IEEE
- Whether CORE full-text lookup should use an API key
If no supported citation format is chosen, the skill defaults to `APA`.
## Citation Formats
The skill currently includes templates for these citation formats:
- `APA`
- `MLA`
- `Chicago Author-Date`
- `Harvard`
- `IEEE`
- `Vancouver`
The agent uses these templates to format both in-text citations and the final references section.
You can add a new citation format by creating a new Markdown template in `skills/write-literature-review/references/citation format/`. Each template should include:
- a pseudo paragraph showing the in-text citation style
- a separate references section in the same format
After adding a new template file, update the workflow or writing guidance if you want the new format to be treated as an explicitly supported option by default.
## Skill Layout
```text
skills/write-literature-review/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── references/
│ ├── citation format/
│ │ ├── APA.md
│ │ ├── Chicago Author-Date.md
│ │ ├── Harvard.md
│ │ ├── IEEE.md
│ │ ├── MLA.md
│ │ └── Vancouver.md
│ ├── review_writing.md
│ ├── workflow.md
│ └── workflow_logging.md
└── scripts/
├── build_knowledge_graph.py
└── lit_review_pipeline.py
```
`SKILL.md` is the agent-facing entry point. `references/` contains the detailed workflow, logging, writing guidance, and citation-format templates. `scripts/` contains the local utilities for search, expansion, ranking, graph generation, and PDF rendering.
## Script Examples
Seed search from keywords:
```bash
python skills/write-literature-review/scripts/lit_review_pipeline.py search \
--out review_workspace \
--keyword "retrieval augmented generation" \
--keyword "scientific discovery" \
--email you@example.com \
--openalex-api-key "$OPENALEX_API_KEY"
```
Expand from the screened frontier:
```bash
python skills/write-literature-review/scripts/lit_review_pipeline.py expand \
--workspace review_workspace \
--input screening/filtered_candidates.jsonl \
--email you@example.com \
--openalex-api-key "$OPENALEX_API_KEY"
```
Rank the final filtered set:
```bash
python skills/write-literature-review/scripts/lit_review_pipeline.py rank \
--workspace review_workspace \
--input screening/filtered_candidates.jsonl
```
Retrieve up to 30 full-text candidates:
```bash
python skills/write-literature-review/scripts/lit_review_pipeline.py fulltext \
--workspace review_workspace \
--input references/ranked_references.jsonl \
--core-api-key "$CORE_API_KEY" \
--limit 30
```
Build the knowledge graph and render the root PNG:
```bash
python skills/write-literature-review/scripts/build_knowledge_graph.py \
--workspace review_workspace
```
Render the editable review markdown into the root PDF:
```bash
python skills/write-literature-review/scripts/lit_review_pipeline.py render-review \
--workspace review_workspace
```
## APIs
OpenAlex is used for scholarly metadata, citation links, abstracts, venues, authors, DOIs, open-access links, and concept metadata.
CORE is used as a full-text discovery layer after candidate metadata exists. Respect API limits and paper licenses when retrieving or storing article content.
## Validation
Validate the skill structure with the Codex skill validator:
```bash
python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
skills/write-literature-review
```
Check script syntax without writing bytecode:
```bash
python -c 'import ast, pathlib; [ast.parse(pathlib.Path(p).read_text()) for p in ["skills/write-literature-review/scripts/lit_review_pipeline.py", "skills/write-literature-review/scripts/build_knowledge_graph.py"]]; print("syntax ok")'
```
## Notes
Use the final filtered reference set as the citation boundary for final writing. The review should not cite papers that are absent from the final included list.