---

What is MedSci Skills?

MedSci Skills is an open-source Agent Skills collection for clinical research — the manuscript and the medical-AI model alike — designed to be driven directly by AI coding agents (Claude Code, Codex, Cursor, and GitHub Copilot). It helps physician-researchers and biomedical/medical-engineering investigators move from literature search, study design, statistics, and figures to reporting-guideline compliance, citation/reference auditing, numerical-consistency checks, and response-to-reviewer workflows — combining agentic writing with deterministic integrity gates for submission-grade biomedical research. As of v5.0 it adds a model-engineering lane: choose a paper-grounded architecture, scaffold a reproducible, leakage-safe PyTorch training repo, and validate, document, and evaluate a medical-imaging or LLM/MLLM model so the work reaches a paper — it ships a minimal runnable default model for a forward-pass smoke test and integrates MONAI / nnU-Net / timm / torchvision for production-grade models, rather than reimplementing the ecosystem. Clinical AI model research engineering is in scope; it is not a diagnostic tool, an autonomous author, or a general AI-scientist platform, and every output requires human-expert verification. New here? See the 3 workflows below, the FAQ, the research connectors it calls (keyless public APIs — nothing to set up in the common case), and the scope boundary.

---

Quick Start

No terminal? Use the classroom installer ZIP — download, unzip, double-click the installer, then restart your agent app (see Installation).

Have a terminal? Fastest path — one command, nothing to clone:

npx medsci-skills install        # copies every skill into your agent's folder

Recommended (especially for clinicians): add --enable-update-notify so Claude Code shows a one-line "update available" notice when a new version ships — otherwise you stay on the version you installed and are never told. (No terminal at all? The classroom installer below turns this on for you.)

npx medsci-skills install --enable-update-notify        # install + in-app update reminders

Have git? Install every skill in three commands:

git clone https://github.com/Aperivue/medsci-skills.git
mkdir -p ~/.claude/skills
cp -r medsci-skills/skills/* ~/.claude/skills/

Restart Claude Code, then start with /orchestrate — it classifies your request and routes you to the right skill. Full install options (Codex, Cursor, individual skills) are in Installation.

Install with gh skill

MedSci Skills follows the Agent Skills standard, so GitHub CLI ≥ 2.90 can search, preview, and install any skill straight from this repo — no clone (a gh preview feature):

gh skill search medsci                                   # list the whole collection
gh skill preview Aperivue/medsci-skills check-reporting  # read a skill before installing
gh skill install Aperivue/medsci-skills check-reporting  # install just that one
gh skill install --all Aperivue/medsci-skills            # or install every skill

Search by a skill's own name (check-reporting, verify-refs, meta-analysis) or by medsci to list them all — both return this repo directly. A broad topic word like systematic review is shared by hundreds of skills across GitHub, so add --owner Aperivue to see only ours.

Install as a Claude Code plugin

Prefer plugins? One line adds the marketplace; /plugin then lets you browse nine category plugins and enable the ones you want:

/plugin marketplace add Aperivue/medsci-skills
/plugin            # browse nine category plugins; enable the ones you want

Plugin	Covers
medsci-literature	Literature search, full-text retrieval, Zotero sync, reference-integrity audits
medsci-data	Study design, variable operationalization, sample size, data cleaning, de-identification, codebooks, dataset versioning
medsci-modeling	Architecture selection, reproducible model-scaffold repos, model-validation audits, Model Card/Datasheet, model & LLM/MLLM evaluation
medsci-analysis	Statistics, figures, batch/cross-national/replication analysis, meta-analysis
medsci-writing	IMRAD & protocol drafting, AI-pattern removal, AI-search optimization, reviewer responses
medsci-review	Self-review, peer review, reporting-guideline compliance
medsci-submission	Submission packaging, journal selection, ICMJE/IRB form filling, grant proposals
medsci-project	Orchestration, project intake/management, gap & topic discovery, author strategy
medsci-presentation	Presentations/PPTX, PDF/document rendering, environment setup, skill publishing

Install a single category and invoke its skills under that namespace:

/plugin install medsci-analysis@medsci-skills
/medsci-analysis:analyze-stats

All nine plugins share the same repository source, so this groups and enables skills by category — it is not a partial download. The marketplace tracks main, so a plugin's version is its git commit.

Note the name. A skill installed as a plugin is invoked under its plugin's namespace (/medsci-analysis:analyze-stats); the same skill installed into the skills folder by the npx, gh skill, classroom, or manual paths is invoked bare (/analyze-stats). Both run the same skill — press / and use Tab completion rather than typing the long form.

Want just one capability? Two skills are also published as focused standalone repos (generated mirrors; this repo stays the source of truth), each installable on its own with /plugin marketplace add Aperivue/<repo>:

• Aperivue/verify-refs — catch fabricated/mismatched citations (PubMed + CrossRef).
• Aperivue/check-reporting — audit a manuscript against the bundled EQUATOR reporting guidelines and risk-of-bias tools.

---

Start here: 3 workflows

New users don't need all the skills at once. Most work starts as one of three workflows. Each runs through /orchestrate or by invoking the named skills in order; all outputs require human-expert review.

Workflow A — Manuscript pre-submission audit. Use when a manuscript is nearly ready and you want it checked before a reviewer sees it. Skills: /self-review → /check-reporting → /verify-refs → /sync-submission. In: your manuscript (+ refs.bib, tables/figures). Out: anticipated reviewer comments, an item-by-item reporting-guideline audit, a citation-integrity report, and a submission-package drift check. Safety: it flags issues; you fix and verify them.

Workflow B — Data to manuscript package. Use when you have a cleaned dataset and need a full draft. Skills: /clean-data → /analyze-stats → /make-figures → /write-paper → /check-reporting → /find-journal. In: a cleaned CSV/parquet

• a research question. Out: reproducible analysis code, publication-ready figures, an IMRaD draft, a reporting checklist, and a journal shortlist. Safety: statistics and claims must be verified against your data; the toolkit never fabricates numbers or references.

Workflow C — Systematic review / meta-analysis. Use when you are running an SR/MA. Skills: /meta-analysis (with /search-lit, /make-figures, /check-reporting). In: a research question + search strategy. Out: PROSPERO-style protocol scaffolding, screening/extraction structure, PRISMA-consistent counts and diagram, pooled-estimate figures, and a manuscript draft. Safety: screening and extraction decisions stay with the human review team.

Live Demos: Five Study Types, Five Full Pipelines

Five public datasets. Five study types. Demos 1–3 each produce a complete manuscript, publication-ready figures, and a reporting-compliance audit; Demo 4 runs the medical-AI model-engineering lane end to end (scaffold → gates → training → evaluation → interpretability); Demo 5 takes that lane onto a GPU cluster and out to a genuinely external cohort, then reports where it broke.

Demo	Dataset	Study Type	Compliance
Demo 1: Wisconsin BC	sklearn built-in	Diagnostic accuracy	STARD 2015
Demo 2: BCG Vaccine	metafor::dat.bcg (13 RCTs)	Meta-analysis	PRISMA 2020
Demo 3: NHANES Obesity	CDC NHANES 2017-18	Epidemiology (survey)	STROBE
Demo 4: PneumoniaMNIST CNN	medmnist (CC BY 4.0)	Medical-AI model engineering (CNN)	CLAIM / TRIPOD+AI
Demo 5: MSD → AMOS spleen	MSD Task09 + AMOS22 (CC BY 4.0)	3-D segmentation, external validation + modality shift	CLAIM / Metrics Reloaded

Demo 1: Diagnostic Accuracy — Wisconsin Breast Cancer

from sklearn.datasets import load_breast_cancer
data = load_breast_cancer()  # 569 samples, zero download

Output from orchestrate --e2e (see full demo):

Full output list — manuscript, figures, STARD flow, checklist (click to expand)

Output	Description
Manuscript	IMRAD draft, ~1,800 words
Title Page	STARD title page with key points
DOCX	Submission-ready Word document
ROC Curve	3-model comparison with DeLong 95% CIs
Confusion Matrices	Per-model confusion matrices at threshold 0.5
STARD Flow	D2-generated STARD 2015 flow diagram
Reporting Checklist	STARD 2015 — 60.9% compliance (14/23 applicable)
Self-Review	Initial 82 (REVISE) → 88 (PASS) after 1 fix iteration; final 0 major / 1 minor
Pipeline Log	7-step E2E execution trace

Pipeline: analyze-stats → make-figures → write-paper → AI pattern scan → check-reporting (STARD) → self-review → DOCX build → present-paper

Demo 2: Meta-Analysis — BCG Vaccine Efficacy

library(metafor)
data(dat.bcg)  # 13 RCTs, 357,347 participants (Colditz et al. 1994)

Output from orchestrate --e2e (see full demo):

Full output list — manuscript, forest/funnel plots, PRISMA flow, checklist (click to expand)

Output	Description
Manuscript	Pooled RR = 0.489 (95% CI: 0.344–0.696), ~2,200 words
Title Page	PRISMA title page with key points
DOCX	Submission-ready Word document
Forest Plot	13 studies, RE model (REML), 300 dpi
Funnel Plot	Small-study / publication-bias visual
PRISMA Flow	D2-generated PRISMA 2020 flow diagram
Reporting Checklist	PRISMA 2020 — 57.1% (24/42) at check-reporting → 61.9% (26/42) after self-review fix
Self-Review	Initial 78 → 82 (REVISE) after 1 fix iteration; 3 major / 4 minor (majors are out-of-scope RoB/GRADE/references)
Pipeline Log	7-step E2E execution trace

Pipeline: analyze-stats (R metafor) → make-figures → write-paper → AI pattern scan → check-reporting (PRISMA 2020) → self-review → DOCX build → present-paper

Demo 3: Epidemiology — NHANES Obesity & Diabetes

# Pre-processed NHANES 2017-2018 CSV included
# 5,010 US adults after exclusions

Output from orchestrate --e2e (see full demo):

Full output list — manuscript, OR forest plot, STROBE flow, checklist (click to expand)

Output	Description
Manuscript	Adjusted OR = 3.03 (95% CI: 2.29–4.02), ~1,850 words
Title Page	STROBE title page with key points
DOCX	Submission-ready Word document
OR Forest Plot	Adjusted odds ratios for 7 variables
Study Flow	D2-generated participant flow diagram
Reporting Checklist	STROBE — 83.3% compliance (25/30 applicable)
Self-Review	ACCEPT-WITH-NOTES after 1 fix iteration; 0 genuine majors remaining
Pipeline Log	7-step E2E execution trace

Pipeline: analyze-stats → make-figures → write-paper → AI pattern scan → check-reporting (STROBE) → self-review → DOCX build → present-paper

Demo 5: External Validation — MSD → AMOS spleen segmentation

The only demo that leaves the laptop, and the only one that reports a failure. It asks whether a clinician can carry a deep-learning study to a defensible result without an engineer, then answers by running a three-rung external-validation ladder on a GPU cluster and logging every point where the answer was no.

Rung	Cohort	n scored	Dice median [95% CI]
1 internal	MSD held-out	9	0.9595 [0.9367–0.9734]
2 genuine external	AMOS CT	298 / 300	0.8932 [0.8633–0.9108]
3 modality shift	AMOS MRI	59 / 60	0.0152 [0.0000–0.0626]
3b counterfactual	AMOS MRI, rescaled	59 / 60	0.3016 [0.1744–0.4048]

Rung 3 is a constructed test, and the demo says so: the evaluation plan named the normalisation contract and predicted the collapse before inference ran. The trained plan carries CTNormalization into inference and there is no flag that says "this is MRI", so a Hounsfield-unit clip is applied to arbitrary-unit images: 0 of 60 MRI cases contain a negative voxel (against 300 of 300 on CT), and a median 23.2 % of voxels are flattened at the clip ceiling (against 2.7 %). The run exits 0 and returns a file for all 60 cases, 20 of them empty. Only ground truth made it loud.

A fourth arm changes only the input intensity scale — same checkpoint, no retraining — and recovers median Dice to 0.3016 (+0.2864 [+0.1204, +0.4048]) while staying −0.5916 below the CT arm. So both mechanisms are real and differently sized: roughly 0.29 Dice is the preprocessing contract, 0.59 a representation that does not transfer. The arm and its prediction were written down before it ran.

And /profile-imaging had already flagged the mixed intensity scale before training — as a Minor, where it sat in qc/ for nine days. So the gap this demo found is not detection; it is routing and severity. A gate that fires correctly into a directory no later step reads is, operationally, a gate that did not fire. See the full demo — including FRICTION.md, which lists every point that needed engineering knowledge, because the headline question is not answerable honestly without it.

Pipeline: profile-imaging → model-sourcing → preprocess-imaging (leakage gate, plus the counterfactual that must fail) → model-validation (split gate) → nnU-Net training → model-evaluation → make-figures → write-up. bash reproduce.sh re-runs the gates and the whole across-cohort analysis on a laptop; training needs ~50 GPU-hours and says so.

Project Folder Structure

Each demo (and real project) follows this role-based folder layout:

project/
├── data/                          # Input data
│   └── raw_data.csv
├── analysis/                      # /analyze-stats + /make-figures outputs
│   ├── tables/
│   ├── figures/
│   │   └── _figure_manifest.md
│   ├── _analysis_outputs.md
│   └── analyze.py
├── manuscript/                    # /write-paper outputs
│   ├── manuscript.md
│   ├── manuscript_final.docx
│   └── title_page.md
├── qc/                            # Quality verification
│   ├── reporting_checklist.md     # /check-reporting
│   ├── self_review.md             # /self-review
│   └── _pipeline_log.md
├── submission/                    # Post-journal-selection (manual trigger)
│   └── {journal_short}/
│       ├── cover_letter.md
│       ├── checklist.md
│       └── peer_review.md
└── presentation/
    └── presentation.pptx

The E2E pipeline (orchestrate --e2e) produces everything up to qc/. The submission/ directory is created after journal selection via /find-journal.

---

What's New

v5.24.0 — a precision release: the gates were wrong about correct work. Fourteen shipped detectors were telling users something false, and the pattern behind most of them is one thing — a checker that accepts only its own generator's output and rejects the notation the world actually uses. check_xref did not recognise "Figures 1 and 2", so a float cited the ordinary way scored UNCITED and the submission blocker turned itself off (submission_safe: true on a package missing a figure). verify_refs read BibTeX's own and others — the et-al. every reference manager writes — as AUTHOR MISMATCH, the render-aborting verdict, on correct consortium references; and an entry whose last field was the DOI parsed as having none, silently disabling the CrossRef and author cross-checks that skill exists to perform. check_table_percentages invented a denominator for the most common table in clinical research and printed specific wrong replacement percentages at MAJOR. lint_consistency advised writing "type two diabetes". check_asset_anonymization passed a double-blind institution leak because it sat in a .yaml. check_slide_tells flagged the page numbers this repository's own template generator writes. fill_journal_abbrev.py had never run — it raised on its first entry, for every input, while another gate named it to the user as the remedy. And refinement_stop called a leftover TODO an optional Minor and told the loop to stop. Also: the release job's own failure had left v5.23.0 with zero assets and npm a version behind, with no way to retry a pushed tag — now create-or-update, outcome-asserted, and dispatchable; two of the four documented install paths were broken, and the worse one succeeded while making ~/.claude/skills itself the skill; and the front page said 36 detectors while the catalog, the audit document and the paper said 84. Every fix ships a regression test that goes red against the previous behaviour. No new skill or detector; 58 skills / 47 guidelines / 84 integrity detectors / 23 domain-probe modules. (See the CHANGELOG for v5.0–v5.23.)

v5.21 — verification-layer batch, mostly promoted from real submission failures. A marked (tracked-changes) manuscript is now built by driving Word's Compare from the command line and proved by a round trip — accepting every revision must reproduce