literature-screening
Skill2 starsChanged 35 days agoMITView on GitHub
Locks inclusion and exclusion criteria, then screens titles and abstracts and full texts with reasons, optional Cohen's kappa, and a PRISMA 2020 flow that reconciles to the deduplicated library. Narrative reviews instead rank the library and keep the cap in project.yaml, logging the rest as not read. Trigger on "screen the papers", "inclusion criteria", "PRISMA flow", "kappa", or "narrative core". Do not use it to deduplicate, to fetch PDFs from shadow libraries, or to write the review.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/literature-review.mdcCursor rule
- exemplar-review-analysisSkill
- figure-permissionsSkill
- journal-selectionSkill
- manuscript-polishingSkill
- paper-deep-readingSkill
- reviewer-responseSkill
- review-figures-and-tablesSkill
- review-orchestratorSkill
- review-outline-builderSkill
- review-project-setupSkill
- review-scoping-and-gapsSkill
- review-section-drafterSkill
- review-writingSkill
- search-export-and-dedupSkill
- search-strategy-builderSkill
- submission-packageSkill
- zotero-library-syncSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
Ask: "Pass inclusion lock on 03-screening/criteria.md?
- Very specific: line 53
If review_type is narrative, stop this numbered procedure here and follow references/narrative_core.md.
- Very specific: line 62
Import asreview_input.csv (a CSV/TSV spreadsheet file) into an ASReview LAB browser window.
- Very specific: line 72
Write 03-screening/prisma_flow.md from references/prisma_flow_template.md.
- Very specific: line 112
Every exclude has a reason code defined in criteria.md.
- Distinctive: line 120
Do not exclude a record for "low quality" unless a reason code says so and was locked.
- Very specific: line 121
Do not drop duplicates again here.
- Distinctive: line 122
Do not download a PDF from an unauthorized site to decide full text.
- Very specific: line 124
Do not change narrative_core_cap, and do not describe that core as a systematic review.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Literature screening
Opening
On first use in a project, say this verbatim:
I am literature screening. I lock the criteria before any final decision, and a narrative review keeps the cap written in project.yaml.
When to use
02-records/library.csv and 02-records/prisma_counts.json exist. Criteria are drafted and locked here before any final exclude decision. Read review_type before choosing a path.
Narrative reviews do not claim a complete systematic flow. They lock criteria, then follow references/narrative_core.md: rank every record and keep narrative_core_cap from project.yaml (default 500). Ties at the cutoff stay in the core. The rest are not_read with reason below-cap. The agent does not change the cap. Systematic, scoping, and umbrella reviews use the numbered steps below and do not write a narrative core.
Inputs (paths) / Preconditions
<project>/02-records/library.csvandprisma_counts.json.<project>/00-scope/scope_report.md— locked question and framework.references/criteria_template.mdandreferences/prisma_flow_template.md.- Optional second screener. If there is only one, do not invent kappa. Log
single_screener. scripts/kappa.pyfor a pilot CSV with two decision columns.
PRISMA 2020 flow labels: https://www.prisma-statement.org/
Procedure (numbered steps)
- Copy
references/criteria_template.mdto03-screening/criteria.md. Fill include and exclude rules from the locked framework. Each rule gets areason_codefrom the template. Add a rule only when the user wants it. A language or date rule must repeat the justification already used in the search file. - Optional pilot, before the lock: take the first 20 to 30 rows of
library.csv(or a user-specified random subset; record the seed if you sample). Two people decideincludeorexcludeindependently. Write03-screening/pilot.csvwithrecord_id,screener_a,screener_b. Run:
python3 <suite>/skills/literature-screening/scripts/kappa.py \
--csv <project>/03-screening/pilot.csv \
--a screener_a --b screener_b \
--out <project>/03-screening/kappa.json<suite> is the directory that contains skills/. Bands in the JSON interpretation field follow Landis and Koch (Biometrics, 1977): poor, slight, fair, moderate, substantial, almost_perfect. If kappa is below 0.60, or the JSON says undefined because expected agreement is 1, revise the criteria wording and repeat the pilot. Pilot decisions are provisional. They are not copied into screening.csv.
- Ask: "Pass inclusion lock on 03-screening/criteria.md? Reply with: I confirm the inclusion lock." On that exact sentence, set
gates.inclusion_locktotrueand appendYYYY-MM-DD | literature-screening | inclusion lock passed | human. Check the sentence withskills/review-orchestrator/scripts/check_gate_phrase.py --gate inclusion_lock. Do not write final screening rows before it matches.
If review_type is narrative, stop this numbered procedure here and follow references/narrative_core.md. Do not run steps 4–9. Systematic, scoping, and umbrella reviews continue at step 4. They do not write narrative_rank.tsv, core_decision.tsv, or not_read.tsv, and they do not call scripts/narrative_core.py.
- Title and abstract: one row per record per screener in
03-screening/screening.csv. Columns:record_id,stage,screener,decision,reason_code,reason_note,date,consensus.stageistitle_abstract.decisionisinclude,exclude, ormaybe.excluderequires areason_code. Single screener:consensusequalsdecision. Two screeners:consensusstays empty until they resolve disagreements; then it isincludeorexclude. - (Optional) To use ASReview LAB (an active learning screening tool) for title and abstract screening, open macOS Terminal or Windows PowerShell and run this from the suite root (the folder that contains
skills/) to export the library:
python3 skills/literature-screening/scripts/asreview_io.py export <project>/02-records/library.csv -o <project>/03-screening/asreview_input.csvImport asreview_input.csv (a CSV/TSV spreadsheet file) into an ASReview LAB browser window. When finished, download the exported results and convert them back to a staging file (a temporary file before final screening):
python3 skills/literature-screening/scripts/asreview_io.py import <asreview_export.csv> -o <project>/03-screening/asreview_decisions.csvManually add a reason_code for excludes, set consensus, and copy the rows into screening.csv. The asreview_io.py script counts unlabelled records as not_seen and writes no rows for them in screening.csv. They are still unscreened, not excluded, so the PRISMA numbers will not balance until they are screened. The stopping rule used in ASReview must be reported.
- Full text: for every record with title/abstract
consensusofincludeormaybe, addstagefull_text. Retrieval failure is not an eligibility exclusion. Those records are "reports not retrieved" in the flow, withreason_codeFT_NOT_RETRIEVED, and they do not go in the excluded-by-reason list. - Build
03-screening/included.tsvfor records whose full-textconsensusisinclude. Header:record_id,doi,pmid,title,year,first_author,n_authors,venue,citation_key. Copy identifiers fromlibrary.csv. Put thejournalvalue invenue.citation_keyis the first author's family name (ASCII letters) plus the four-digit year (Lovelace2020). Collisions get a trailinga,b, orc.n_authorsis the count of authors joined by;(semicolon then space), or empty if the author field is empty. RIS and NBIB rows already use that separator. If a CSV cell uses another separator, rewrite that cell to;before counting. Do not invent a missing author. - Write
03-screening/prisma_flow.mdfromreferences/prisma_flow_template.md. These equalities are the databases-and-registers arm. Userecords_after_deduplicationas the screened denominator unless you list extra removals (automation or other) with counts:
screened = title_abstract_excluded + reports_sought
reports_sought = not_retrieved + full_text_assessed
full_text_assessed = full_text_excluded + included_reports
sum of full-text reason counts = full_text_excludedfull_text_excluded does not include FT_NOT_RETRIEVED. If the sums fail, fix the CSV. Do not edit the flow numbers alone.
Optional diagram: write 03-screening/prisma_counts_flow.json (keys in references/prisma_flow_examples/counts_example.json) and run:
python3 <suite>/skills/literature-screening/scripts/prisma_flow.py \
<project>/03-screening/prisma_counts_flow.json \
--out <project>/03-screening/prisma_flowThis optional diagram step is for systematic, scoping, or umbrella reviews that need figure files. Run it after the 03-screening/prisma_flow.md numbers reconcile. The keys in 03-screening/prisma_counts_flow.json match the example file, and the script checks that the screened, sought, assessed, and included numbers follow the same math rules as 03-screening/prisma_flow.md. The script creates 03-screening/prisma_flow.svg and 03-screening/prisma_flow.pdf, but it does not replace the 03-screening/prisma_flow.md text document.
- Append
YYYY-MM-DD | literature-screening | screening complete, included <N> | agentwith N equal to the included-report count.
Human gate(s)
inclusion_lock before any final row in screening.csv or core_decision.tsv. A kappa number does not lock the criteria. The user does. An optional decision card may come first (shared/decision_cards.md): four labeled options, one preferred, and a custom option rewritten as a plan with its risks. The card is not the lock. Only the exact sentence is.
Outputs (exact paths + formats)
03-screening/criteria.md03-screening/pilot.csvandkappa.jsonwhen a dual pilot was run03-screening/screening.csv— columns in step 4, or the narrative columns inreferences/narrative_core.md03-screening/included.tsv— columns in step 703-screening/prisma_flow.svgandprisma_flow.pdfwhen the optional diagram was drawn03-screening/prisma_flow.md— PRISMA 2020 boxes for a full eligibility screen, or the narrative core note- Narrative only:
03-screening/narrative_rank.tsv,core_decision.tsv,not_read.tsv, andcap_overflow.tsv
Quality checklist
- No
screening.csvrow has a date earlier than the inclusion-lock log line. - Every
excludehas a reason code defined incriteria.md. - Flow arithmetic matches
prisma_counts.jsonand the CSV. - Included DOIs and PMIDs match
library.csvfor thatrecord_id. - Single-screener reviews have a
single_screenerlog line and no fabricated kappa file. - A narrative project prints
OK narrative core, says it is not a complete systematic review, and logs every non-core record as not read.
Guardrails
- Do not exclude a record for "low quality" unless a reason code says so and was locked.
- Do not drop duplicates again here. Duplicates were removed in
02-records/. - Do not download a PDF from an unauthorized site to decide full text. If you cannot retrieve it legally, count it as not retrieved.
- Maybe at title/abstract goes to full text. It is not a silent exclude.
- Do not change
narrative_core_cap, and do not describe that core as a systematic review. Do not use the cap for a systematic, scoping, or umbrella review.
Next step
zotero-library-sync using included.tsv.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

