litreviewskill

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:

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:

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:

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:

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

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:

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:

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:

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:

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:

python skills/write-literature-review/scripts/build_knowledge_graph.py \
  --workspace review_workspace

Render the editable review markdown into the root PDF:

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:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/write-literature-review

Check script syntax without writing bytecode:

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.