Skip to content
Back to search

medsci-skills

MarketplaceWorks with Claude CodeGitHub

Physician-built Claude Code skills for clinical manuscript preparation, with deterministic integrity gates — reporting-guideline and risk-of-bias compliance, reference/citation verification, and numerical-consistency checks — plus literature search, study design, statistics, publication-ready figures, IMRAD drafting, journal selection, peer review, and revision. Submission-grade, not a generic skill catalog.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Aperivue/medsci-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Aperivue/medsci-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aperivue--medsci-skills/badge.svg)](/listings/aperivue--medsci-skills)

HTML

<a href="/listings/aperivue--medsci-skills"><img src="/api/listings/aperivue--medsci-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<a id="quick-start"></a><a id="install-with-gh-skill"></a><a id="install-as-a-claude-code-plugin"></a><a id="option-1-classroom-installer-recommended-for-non-programmers"></a><a id="option-2-install-all-skills-manually"></a><a id="option-3-install-individual-skills-manually"></a><a id="option-4-npm--npx-terminal-friendly-shortcut"></a><a id="option-5-github-cli-gh-skill"></a><a id="platform-notes"></a><a id="optional-let-plain-language-requests-find-the-skills"></a><a id="updating"></a><a id="setup"></a><a id="requirements"></a> **Without a terminal** (Windows or macOS): download the [classroom installer](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#classroom-installer-no-terminal), unzip it and double-click the installer inside. It also turns on update reminders and puts an **Update MedSci Skills** icon on your Desktop. If you have not installed Claude Code, Python or Node yet, the [setup guides](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/setup/README.md) for Mac and Windows go step by step.

**In a terminal**, with [Node 18+ and Python 3.9+](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/setup/README.md) installed:

npx medsci-skills install

This copies every skill into `~/.claude/skills/` (read by Claude Code, Cursor and Copilot in VS Code) and `~/.agents/skills/` (read by Codex, Cursor and GitHub Copilot). Restart your agent, type `/orchestrate`, and describe what you want to do; it routes the request to the right skill. To be told when a new version ships, add `--enable-update-notify`: a one-line notice at Claude Code session start, off by default, no telemetry.

Other ways to install, each described in [docs/install.md](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md):

- **Claude Code plugin:** [`/plugin marketplace add Aperivue/medsci-skills`](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#claude-code-plugin-marketplace), then enable the plugins you want; skills are then namespaced, e.g. `/medsci-analysis:analyze-stats`. - **GitHub CLI 2.90+:** [`gh skill install Aperivue/medsci-skills --all --agent claude-code --scope user`](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#github-cli-gh-skill), or name a single skill. The two flags put the skills where Claude Code looks; the linked section gives the values for other hosts. - **git:** [clone the repository](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#git-clone) and copy `skills/*` into `~/.claude/skills/`. - **A fixed version**, for a paper that cites the version it used: `npx medsci-skills@6.1.0 install`; the plugin and `gh` equivalents are in [docs/install.md](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#staying-on-one-version).

[Updating](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#updating), [what individual skills need](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#requirements) (pandoc, R, PyTorch), [where the files go](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#where-the-skills-go) and the [optional routing block](https://github.com/Aperivue/medsci-skills/blob/v6.1.0/docs/install.md#optional-let-plain-language-requests-find-the-skills) for plain-language requests are on the same page.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 273 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "medsci-skills",
  4. "description": "Physician-built Claude Code skills for clinical manuscript preparation, with deterministic integrity gates — reporting-guideline and risk-of-bias compliance, reference/citation verification, and numerical-consistency checks — plus literature search, study design, statistics, publication-ready figures, IMRAD drafting, journal selection, peer review, and revision. Submission-grade, not a generic skill catalog.",
  5. "owner": {
  6. "name": "Aperivue"
  7. },
  8. "plugins": [
  9. {
  10. "name": "medsci-literature",
  11. "displayName": "MedSci Literature & References",
  12. "description": "Literature search with anti-hallucination citation verification, full-text retrieval, Zotero/Obsidian sync, and reference-integrity audits.",
  13. "author": {
  14. "name": "Aperivue",
  15. "url": "https://github.com/Aperivue"
  16. },
  17. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  18. "repository": "https://github.com/Aperivue/medsci-skills",
  19. "keywords": [
  20. "medical-research",
  21. "clinical-research",
  22. "literature-search",
  23. "pubmed",
  24. "citation-verification",
  25. "zotero"
  26. ],
  27. "source": "./",
  28. "strict": false,
  29. "skills": [
  30. "./skills/fulltext-retrieval",
  31. "./skills/lit-sync",
  32. "./skills/manage-refs",
  33. "./skills/obsidian-paper-vault",
  34. "./skills/search-lit",
  35. "./skills/verify-refs"
  36. ]
  37. },
  38. {
  39. "name": "medsci-data",
  40. "displayName": "MedSci Data & Study Design",
  41. "description": "Study design and validity review, literature-grounded variable operationalization, sample-size planning, data cleaning, de-identification, codebook generation, and dataset versioning.",
  42. "author": {
  43. "name": "Aperivue",
  44. "url": "https://github.com/Aperivue"
  45. },
  46. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  47. "repository": "https://github.com/Aperivue/medsci-skills",
  48. "keywords": [
  49. "medical-research",
  50. "clinical-research",
  51. "study-design",
  52. "sample-size",
  53. "de-identification",
  54. "data-cleaning"
  55. ],
  56. "source": "./",
  57. "strict": false,
  58. "skills": [
  59. "./skills/calc-sample-size",
  60. "./skills/clean-data",
  61. "./skills/define-variables",
  62. "./skills/deidentify",
  63. "./skills/design-ai-benchmarking",
  64. "./skills/design-study",
  65. "./skills/generate-codebook",
  66. "./skills/version-dataset"
  67. ]
  68. },
  69. {
  70. "name": "medsci-modeling",
  71. "displayName": "MedSci Model Engineering & Validation",
  72. "description": "Clinical AI model research engineering: choose a paper-grounded architecture, scaffold a reproducible PyTorch training repo, validate the model's split and validation design, document it (Model Card / Datasheet), and evaluate models or LLMs/MLLMs on clinical tasks. Integrates MONAI / nnU-Net, never replaces them.",
  73. "author": {
  74. "name": "Aperivue",
  75. "url": "https://github.com/Aperivue"
  76. },
  77. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  78. "repository": "https://github.com/Aperivue/medsci-skills",
  79. "keywords": [
  80. "medical-research",
  81. "clinical-research",
  82. "medical-imaging-ai",
  83. "clinical-validation",
  84. "pytorch",
  85. "monai"
  86. ],
  87. "source": "./",
  88. "strict": false,
  89. "skills": [
  90. "./skills/architecture-zoo",
  91. "./skills/explainability",
  92. "./skills/imaging-data",
  93. "./skills/mllm-eval",
  94. "./skills/model-assessment",
  95. "./skills/model-card",
  96. "./skills/model-evaluation",
  97. "./skills/model-scaffold",
  98. "./skills/model-selection",
  99. "./skills/model-sourcing",
  100. "./skills/model-validation",
  101. "./skills/preprocess-imaging",
  102. "./skills/profile-imaging",
  103. "./skills/radiomics-ml",
  104. "./skills/uncertainty-imaging"
  105. ]
  106. },
  107. {
  108. "name": "medsci-analysis",
  109. "displayName": "MedSci Analysis & Figures",
  110. "description": "Reproducible statistical analysis, publication-ready figures, batch/cross-national/replication analysis, and meta-analysis synthesis.",
  111. "author": {
  112. "name": "Aperivue",
  113. "url": "https://github.com/Aperivue"
  114. },
  115. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  116. "repository": "https://github.com/Aperivue/medsci-skills",
  117. "keywords": [
  118. "medical-research",
  119. "clinical-research",
  120. "biostatistics",
  121. "meta-analysis",
  122. "figures"
  123. ],
  124. "source": "./",
  125. "strict": false,
  126. "skills": [
  127. "./skills/analyze-stats",
  128. "./skills/batch-cohort",
  129. "./skills/cross-national",
  130. "./skills/make-figures",
  131. "./skills/meta-analysis",
  132. "./skills/replicate-study"
  133. ]
  134. },
  135. {
  136. "name": "medsci-writing",
  137. "displayName": "MedSci Writing & Manuscript",
  138. "description": "IMRAD manuscript and IRB-protocol drafting, AI-pattern removal, AI-search optimization, and reviewer-response letters.",
  139. "author": {
  140. "name": "Aperivue",
  141. "url": "https://github.com/Aperivue"
  142. },
  143. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  144. "repository": "https://github.com/Aperivue/medsci-skills",
  145. "keywords": [
  146. "medical-research",
  147. "clinical-research",
  148. "manuscript-writing",
  149. "irb-protocol",
  150. "reviewer-response"
  151. ],
  152. "source": "./",
  153. "strict": false,
  154. "skills": [
  155. "./skills/academic-aio",
  156. "./skills/humanize",
  157. "./skills/polish-language",
  158. "./skills/review-paper",
  159. "./skills/revise",
  160. "./skills/write-paper",
  161. "./skills/write-protocol"
  162. ]
  163. },
  164. {
  165. "name": "medsci-review",
  166. "displayName": "MedSci Review & Compliance",
  167. "description": "Pre-submission self-review, peer-review drafting, and reporting-guideline compliance audits against EQUATOR checklists.",
  168. "author": {
  169. "name": "Aperivue",
  170. "url": "https://github.com/Aperivue"
  171. },
  172. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  173. "repository": "https://github.com/Aperivue/medsci-skills",
  174. "keywords": [
  175. "medical-research",
  176. "clinical-research",
  177. "reporting-guidelines",
  178. "peer-review",
  179. "risk-of-bias"
  180. ],
  181. "source": "./",
  182. "strict": false,
  183. "skills": [
  184. "./skills/check-reporting",
  185. "./skills/peer-review",
  186. "./skills/self-review"
  187. ]
  188. },
  189. {
  190. "name": "medsci-submission",
  191. "displayName": "MedSci Submission & Journals",
  192. "description": "Submission packaging, journal recommendation and profiling, institutional form filling (ICMJE COI, IRB), and grant proposals.",
  193. "author": {
  194. "name": "Aperivue",
  195. "url": "https://github.com/Aperivue"
  196. },
  197. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  198. "repository": "https://github.com/Aperivue/medsci-skills",
  199. "keywords": [
  200. "medical-research",
  201. "clinical-research",
  202. "journal-selection",
  203. "icmje",
  204. "grant-proposal"
  205. ],
  206. "source": "./",
  207. "strict": false,
  208. "skills": [
  209. "./skills/add-journal",
  210. "./skills/fill-icmje-coi",
  211. "./skills/fill-protocol",
  212. "./skills/find-journal",
  213. "./skills/grant-builder",
  214. "./skills/sync-submission"
  215. ]
  216. },
  217. {
  218. "name": "medsci-project",
  219. "displayName": "MedSci Project & Workflow",
  220. "description": "Research orchestration, project intake and management, research-gap and meta-analysis topic discovery, and author-strategy analysis.",
  221. "author": {
  222. "name": "Aperivue",
  223. "url": "https://github.com/Aperivue"
  224. },
  225. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  226. "repository": "https://github.com/Aperivue/medsci-skills",
  227. "keywords": [
  228. "medical-research",
  229. "clinical-research",
  230. "research-orchestration",
  231. "project-management",
  232. "research-gap"
  233. ],
  234. "source": "./",
  235. "strict": false,
  236. "skills": [
  237. "./skills/author-strategy",
  238. "./skills/find-cohort-gap",
  239. "./skills/intake-project",
  240. "./skills/ma-scout",
  241. "./skills/manage-project",
  242. "./skills/orchestrate"
  243. ]
  244. },
  245. {
  246. "name": "medsci-presentation",
  247. "displayName": "MedSci Presentation & Tooling",
  248. "description": "Academic presentation and PPTX building, PDF/document rendering, environment setup, skill publishing, and offering your changes back to the project.",
  249. "author": {
  250. "name": "Aperivue",
  251. "url": "https://github.com/Aperivue"
  252. },
  253. "homepage": "https://github.com/Aperivue/medsci-skills#skills",
  254. "repository": "https://github.com/Aperivue/medsci-skills",
  255. "keywords": [
  256. "medical-research",
  257. "clinical-research",
  258. "presentations",
  259. "pptx",
  260. "pdf"
  261. ],
  262. "source": "./",
  263. "strict": false,
  264. "skills": [
  265. "./skills/contribute",
  266. "./skills/present-paper",
  267. "./skills/publish-skill",
  268. "./skills/render-pdf-doc",
  269. "./skills/setup-medsci"
  270. ]
  271. }
  272. ]
  273. }
README.md · README · 181 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # MedSci Skills
  3. English | [简体中文](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/README.zh-CN.md) | [한국어](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/README.ko.md)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/LICENSE)
  5. [![Release](https://img.shields.io/github/v/release/Aperivue/medsci-skills?style=flat-square&color=blue)](https://github.com/Aperivue/medsci-skills/releases/latest)
  6. [![CI](https://img.shields.io/github/actions/workflow/status/Aperivue/medsci-skills/validate.yml?branch=main&style=flat-square&label=CI)](https://github.com/Aperivue/medsci-skills/actions/workflows/validate.yml)
  7. ![Skills](https://img.shields.io/badge/Skills-54-brightgreen?style=flat-square)
  8. [![npm](https://img.shields.io/npm/v/medsci-skills?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/medsci-skills)
  9. [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20155321-blue?style=flat-square)](https://doi.org/10.5281/zenodo.20155321)
  10. [![arXiv](https://img.shields.io/badge/arXiv-2606.09500-b31b1b?style=flat-square)](https://arxiv.org/abs/2606.09500)
  11. **Created & maintained by [Yoojin Nam, MD](https://orcid.org/0000-0001-8565-1360)**
  12. <br>
  13. <sub>Department of Radiology and Research Institute of Radiology, University of Ulsan College of Medicine, Asan Medical Center, Seoul, Republic of Korea</sub>
  14. </div>
  15. <a id="what-is-medsci-skills"></a>
  16. MedSci Skills is a set of [Agent Skills](https://agentskills.io) for clinical research: literature and references, study design, statistics, figures, manuscript drafting, reporting-guideline checks and journal submission, plus a lane for building and validating medical-imaging AI models.
  17. It is for physicians and biomedical or medical-engineering researchers who work in Claude Code, Codex, Cursor or GitHub Copilot.
  18. The skills draft and check, bundled scripts recompute what can be recomputed, and every output still needs review by a qualified researcher; it is not a diagnostic tool or an autonomous author.
  19. ## Installation
  20. <a id="quick-start"></a><a id="install-with-gh-skill"></a><a id="install-as-a-claude-code-plugin"></a><a id="option-1-classroom-installer-recommended-for-non-programmers"></a><a id="option-2-install-all-skills-manually"></a><a id="option-3-install-individual-skills-manually"></a><a id="option-4-npm--npx-terminal-friendly-shortcut"></a><a id="option-5-github-cli-gh-skill"></a><a id="platform-notes"></a><a id="optional-let-plain-language-requests-find-the-skills"></a><a id="updating"></a><a id="setup"></a><a id="requirements"></a>
  21. **Without a terminal** (Windows or macOS): download the [classroom installer](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#classroom-installer-no-terminal), unzip it and double-click the installer inside. It also turns on update reminders and puts an **Update MedSci Skills** icon on your Desktop. If you have not installed Claude Code, Python or Node yet, the [setup guides](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/setup/README.md) for Mac and Windows go step by step.
  22. **In a terminal**, with [Node 18+ and Python 3.9+](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/setup/README.md) installed:
  23. ```bash
  24. npx medsci-skills install
  25. ```
  26. This copies every skill into `~/.claude/skills/` (read by Claude Code, Cursor and Copilot in VS Code) and `~/.agents/skills/` (read by Codex, Cursor and GitHub Copilot).
  27. Restart your agent, type `/orchestrate`, and describe what you want to do; it routes the request to the right skill.
  28. To be told when a new version ships, add `--enable-update-notify`: a one-line notice at Claude Code session start, off by default, no telemetry.
  29. Other ways to install, each described in [docs/install.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md):
  30. - **Claude Code plugin:** [`/plugin marketplace add Aperivue/medsci-skills`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#claude-code-plugin-marketplace), then enable the plugins you want; skills are then namespaced, e.g. `/medsci-analysis:analyze-stats`.
  31. - **GitHub CLI 2.90+:** [`gh skill install Aperivue/medsci-skills --all --agent claude-code --scope user`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#github-cli-gh-skill), or name a single skill. The two flags put the skills where Claude Code looks; the linked section gives the values for other hosts.
  32. - **git:** [clone the repository](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#git-clone) and copy `skills/*` into `~/.claude/skills/`.
  33. - **A fixed version**, for a paper that cites the version it used: `npx medsci-skills@6.3.0 install`; the plugin and `gh` equivalents are in [docs/install.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#staying-on-one-version).
  34. [Updating](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#updating), [what individual skills need](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#requirements) (pandoc, R, PyTorch), [where the files go](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#where-the-skills-go) and the [optional routing block](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/install.md#optional-let-plain-language-requests-find-the-skills) for plain-language requests are on the same page.
  35. ## Three workflows to start with
  36. <a id="start-here-3-workflows"></a><a id="use-cases"></a>
  37. Call a skill by name, or describe the task to `/orchestrate`.
  38. **Check a manuscript against its reporting guideline — `/check-reporting`**
  39. - You give: your manuscript and, if you know it, the guideline — it covers 49 reporting guidelines and risk-of-bias tools, from STROBE, STARD and CONSORT to PRISMA 2020 and TRIPOD+AI.
  40. - You get: an item-by-item audit (PRESENT, PARTIAL, MISSING or N/A, with where each item was found), a list of fixes, and a JSON summary in `qc/`; it is a working audit, not the checklist you upload to the journal.
  41. **Analyse a dataset — `/analyze-stats`**
  42. - You give: a de-identified data file (CSV, Excel or TSV) and your research question.
  43. - You get: an analysis plan to approve, then Python (or R) code that it runs, tables as CSV and Markdown, figures as PDF and 300-dpi PNG, and a manifest that `/make-figures` and `/write-paper` read.
  44. **Verify references — `/verify-refs`**
  45. - You give: a manuscript or bibliography (`.md`, `.docx`, `.bib`, `.txt` or `.tsv`).
  46. - You get: `qc/reference_audit.json`, marking each reference OK, MISMATCH, UNVERIFIED or FABRICATED after lookup in PubMed, CrossRef and OpenAlex; it reports and never edits your references.
  47. Longer chains (pre-submission audit, data to manuscript, systematic review) and step-by-step command lists for common tasks are in [docs/workflows.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/workflows.md).
  48. ### Demos
  49. <a id="live-demos-five-study-types-five-full-pipelines"></a><a id="demo-1-diagnostic-accuracy--wisconsin-breast-cancer"></a><a id="demo-2-meta-analysis--bcg-vaccine-efficacy"></a><a id="demo-3-epidemiology--nhanes-obesity--diabetes"></a><a id="demo-5-external-validation--msd--amos-spleen-segmentation"></a><a id="project-folder-structure"></a>
  50. Five worked examples on public datasets, with their code, outputs and QC reports committed to the repository:
  51. | Demo | Data | What it shows |
  52. |------|------|---------------|
  53. | [Diagnostic accuracy](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/demo/01_wisconsin_bc) | Wisconsin breast cancer (`sklearn`) | Analysis to manuscript draft, STARD 2015 audit |
  54. | [Meta-analysis](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/demo/02_metafor_bcg) | BCG vaccine trials (`metafor::dat.bcg`) | Pooled analysis to manuscript draft, PRISMA 2020 audit |
  55. | [Survey epidemiology](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/demo/03_nhanes_obesity) | NHANES 2017–18 | Weighted survey analysis to manuscript draft, STROBE audit |
  56. | [Model engineering](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/demo/04_pneumoniamnist_cnn/README.md) | PneumoniaMNIST | CNN scaffold, leakage gates, training, evaluation, Grad-CAM |
  57. | [External validation](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/demo/05_msd_amos_spleen/README.md) | MSD spleen, then AMOS CT and MRI | 3-D segmentation tested on an external cohort, including where it failed |
  58. What each demo produced, and how to rerun it: [docs/demos.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/demos.md).
  59. ## Skills
  60. <a id="by-research-stage"></a><a id="available-now"></a>
  61. All 54 skills, by research stage. Each name links to its reference page (what it does, when to use it, its known limits). `npx medsci-skills list` prints the same groups, and with the plugin install each row is one plugin.
  62. | Stage | Plugin | Skills |
  63. |-------|--------|--------|
  64. | Project & Workflow | `medsci-project` | [`author-strategy`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/author-strategy.md) · [`find-cohort-gap`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/find-cohort-gap.md) · [`intake-project`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/intake-project.md) · [`ma-scout`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/ma-scout.md) · [`manage-project`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/manage-project.md) · [`orchestrate`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/orchestrate.md) |
  65. | Literature & References | `medsci-literature` | [`fulltext-retrieval`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/fulltext-retrieval.md) · [`lit-sync`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/lit-sync.md) · [`manage-refs`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/manage-refs.md) · [`obsidian-paper-vault`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/obsidian-paper-vault.md) · [`search-lit`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/search-lit.md) · [`verify-refs`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/verify-refs.md) |
  66. | Data & Study Design | `medsci-data` | [`calc-sample-size`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/calc-sample-size.md) · [`clean-data`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/clean-data.md) · [`define-variables`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/define-variables.md) · [`deidentify`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/deidentify.md) · [`design-ai-benchmarking`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/design-ai-benchmarking.md) · [`design-study`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/design-study.md) · [`generate-codebook`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/generate-codebook.md) · [`version-dataset`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/version-dataset.md) |
  67. | Analysis & Figures | `medsci-analysis` | [`analyze-stats`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/analyze-stats.md) · [`batch-cohort`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/batch-cohort.md) · [`cross-national`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/cross-national.md) · [`make-figures`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/make-figures.md) · [`meta-analysis`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/meta-analysis.md) · [`replicate-study`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/replicate-study.md) |
  68. | Model Engineering & Validation | `medsci-modeling` | [`imaging-data`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/imaging-data.md) · [`mllm-eval`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/mllm-eval.md) · [`model-assessment`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/model-assessment.md) · [`model-card`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/model-card.md) · [`model-scaffold`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/model-scaffold.md) · [`model-selection`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/model-selection.md) · [`radiomics-ml`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/radiomics-ml.md) |
  69. | Writing & Manuscript | `medsci-writing` | [`academic-aio`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/academic-aio.md) · [`humanize`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/humanize.md) · [`polish-language`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/polish-language.md) · [`review-paper`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/review-paper.md) · [`revise`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/revise.md) · [`write-paper`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/write-paper.md) · [`write-protocol`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/write-protocol.md) |
  70. | Review & Compliance | `medsci-review` | [`check-reporting`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/check-reporting.md) · [`peer-review`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/peer-review.md) · [`self-review`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/self-review.md) |
  71. | Submission & Journals | `medsci-submission` | [`add-journal`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/add-journal.md) · [`fill-icmje-coi`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/fill-icmje-coi.md) · [`fill-protocol`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/fill-protocol.md) · [`find-journal`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/find-journal.md) · [`grant-builder`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/grant-builder.md) · [`sync-submission`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/sync-submission.md) |
  72. | Presentation & Tooling | `medsci-presentation` | [`contribute`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/contribute.md) · [`present-paper`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/present-paper.md) · [`publish-skill`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/publish-skill.md) · [`render-pdf-doc`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/render-pdf-doc.md) · [`setup-medsci`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/setup-medsci.md) |
  73. Not sure which one fits? Start with `/orchestrate`.
  74. Renamed in v6 (the old names still work until v7): `imaging-data` ← `preprocess-imaging`, `profile-imaging`; `model-assessment` ← `explainability`, `model-evaluation`, `model-validation`, `uncertainty-imaging`; `model-selection` ← `architecture-zoo`, `model-sourcing`.
  75. ## Patient data and safety
  76. <a id="disclaimer"></a><a id="validation-status--available-vs-ci-gated-vs-evaluated"></a>
  77. Do not give an agent identifiable patient data. `/deidentify` runs locally with no network or AI calls: it detects protected health information with regex and heuristics (locale packs for twelve countries) and pseudonymises it after an interactive review, and `/analyze-stats` asks whether a raw data file contains patient identifiers before using it. These are research productivity tools, not clinical decision support: they are not clinically validated and do not replace expert review, so a qualified researcher must check every output before it is used in a publication or clinical context. The 93 deterministic detectors recompute or cross-check specific things (reference metadata, arithmetic, checklist items, data leakage); a clean run means those checks found nothing, not that the manuscript is correct. [MEDSCI_AUDIT.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/MEDSCI_AUDIT.md) lists each detector and which have been formally evaluated; reference lookups use the public, keyless APIs in [docs/connectors.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/connectors.md).
  78. ## Citation
  79. If MedSci Skills helped produce your manuscript, protocol, or analysis, please cite it —
  80. software citation is how a tool like this earns academic recognition, and it takes one line.
  81. **In your manuscript** (Methods or Acknowledgements — cite the version you actually used):
  82. > Reporting-guideline compliance, reference verification, and pre-submission integrity checks
  83. > were assisted by MedSci Skills (version X.Y.Z; https://github.com/Aperivue/medsci-skills;
  84. > archived at Zenodo, https://doi.org/10.5281/zenodo.20155321).
  85. **BibTeX** (the software, and the preprint describing its design):
  86. ```bibtex
  87. @software{nam_medsci_skills,
  88. author = {Nam, Yoojin},
  89. title = {{MedSci Skills: Claude Code Skills for the Medical Research Lifecycle}},
  90. year = {2026},
  91. publisher = {Zenodo},
  92. doi = {10.5281/zenodo.20155321},
  93. url = {https://github.com/Aperivue/medsci-skills}
  94. }
  95. @article{nam2026agentic,
  96. author = {Nam, Yoojin and Jeong, Jinhoon and Kim, Namkug},
  97. title = {{Deterministic Integrity Gates for LLM-Assisted Clinical Manuscript
  98. Preparation: An Auditable Biomedical Informatics Architecture}},
  99. year = {2026},
  100. journal = {arXiv preprint arXiv:2606.09500},
  101. url = {https://arxiv.org/abs/2606.09500}
  102. }
  103. ```
  104. The Zenodo **concept DOI** [10.5281/zenodo.20155321](https://doi.org/10.5281/zenodo.20155321)
  105. always resolves to the latest release; [`CITATION.cff`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/CITATION.cff) carries the machine-readable
  106. metadata (GitHub's "Cite this repository" button reads it).
  107. **Used it in published or in-review work?** Tell us via the
  108. ["Used in research" issue template](https://github.com/Aperivue/medsci-skills/issues/new?template=used-in-research.yml)
  109. — with your permission it is added to [`docs/citations.md`](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/citations.md).
  110. ## License
  111. MIT License. See [LICENSE](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/LICENSE) for details.
  112. Some bundled material is **not** ours and is not MIT: the official guideline templates, the CSL citation styles, and a few checklist summaries carry their own terms — including CC BY-NC, which restricts commercial use. Those are indexed in [THIRD-PARTY-NOTICES.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/THIRD-PARTY-NOTICES.md), which ships with every copy and is checked against the tree on every build.
  113. Reporting-guideline checklists keep their sources' terms, and several have no open licence, so those are included only as summaries in our own words; [check-reporting's LICENSES.md](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/skills/check-reporting/references/LICENSES.md) records each one.
  114. Optional dependency: `pdf_to_md.py` uses [pymupdf4llm](https://pymupdf.readthedocs.io) (AGPL-3.0). Not bundled -- installed separately by the user via `pip install pymupdf4llm`.
  115. ### Acknowledgements
  116. - `make-figures` Critic Loop is inspired by [PaperBanana](https://github.com/dwzhu-pku/PaperBanana) (Zhu et al., *Automating Academic Illustration for AI Scientists*, arXiv:2601.23265, 2025) and by prior self-refinement research — Self-Refine (Madaan et al., 2023), Reflexion (Shinn et al., 2023), and Constitutional AI (Anthropic, 2022). The implementation in this repository is a clean-room reconstruction specialized for medical publication figures; no code, prompts, or configurations are derived from PaperBanana's repository.
  117. - Reporting-guideline checklists bundled with `check-reporting` credit their original authors in each file's header.
  118. - Wong colorblind-safe palette: Wong B. *Points of view: Color blindness.* Nature Methods 8:441 (2011).
  119. ## More
  120. <a id="whats-new"></a><a id="key-features"></a><a id="autonomous-e2e-pipeline"></a><a id="anti-hallucination-citations"></a><a id="anti-hallucination-numerical-claims"></a><a id="reference-safety-phase-1"></a><a id="meta-analysis-failure-modes"></a><a id="49-reporting-guidelines--rob-tools-built-in"></a><a id="publication-ready-output"></a><a id="resultsdiscussion-boundary-enforcement"></a><a id="irb-protocol-to-submission-in-one-pipeline"></a><a id="skills-work-together"></a><a id="skill-boundaries--which-to-use-and-in-what-order"></a><a id="contributing"></a><a id="in-the-wild"></a><a id="cited-in-the-literature"></a><a id="adoption"></a><a id="star-history"></a><a id="why-this-repo"></a><a id="what-this-is-not"></a><a id="about"></a>
  121. - [Release notes](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/CHANGELOG.md) — what changed in each version.
  122. - [Upgrading from v5](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/MIGRATION-v6.md) — renamed skills, and how to update for each install channel.
  123. - [Workflows and skill boundaries](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/workflows.md) — skill chains, which skill to use when two look alike, and checks that span skills.
  124. - [Skill reference](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/skills/README.md) and [FAQ](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/faq.md).
  125. - [Host compatibility](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/host_compatibility.md) — verified install paths for Claude Code, Codex, Cursor and GitHub Copilot.
  126. - [How it differs from other skill collections](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/competitive_positioning.md) and the [scope boundary](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/ROADMAP.md#not-planned--explicitly-out-of-scope).
  127. - [Contributing](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/CONTRIBUTING.md) — most contributions are one file; `/contribute` sends a change from your installed copy after scanning it for patient data. [Good first issues](https://github.com/Aperivue/medsci-skills/contribute).
  128. - [Adoption](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/IMPACT.md) (stars, forks, downloads) and [citations](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/docs/citations.md).
  129. - Governance: [ROADMAP](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/ROADMAP.md), [MAINTAINERS](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/MAINTAINERS.md), [SECURITY](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/SECURITY.md), [CONTRIBUTORS](https://github.com/Aperivue/medsci-skills/blob/v6.3.0/CONTRIBUTORS.md).
  130. Built by [Aperivue](https://aperivue.com).
skills/peer-review/scripts/check_pdf_injection.py · Bundled script · 305 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """check_pdf_injection.py — flag hidden / injected prompt text in a manuscript PDF
  3. before an LLM-assisted peer review reads it.
  4. A reviewer who pastes an assigned PDF into an LLM can be steered by text that is
  5. invisible on the page but present in the text layer the model ingests: white-on-
  6. white runs, sub-visible fonts, off-page glyphs, invisible render mode, or an
  7. instruction smuggled into the document metadata. This detector audits the
  8. span manifest emitted by scan_pdf_layers.py (a separate PyMuPDF extractor) and
  9. decides, by deterministic rule + set arithmetic, whether the PDF carries hidden
  10. or injection-styled text. It is stdlib-only so it runs in CI without PyMuPDF; the
  11. extractor owns the one heavy dependency.
  12. Signals:
  13. LOW_CONTRAST span colour within CONTRAST_THRESH of its local background
  14. TINY_FONT span font size below MIN_FONT_PT
  15. OFF_PAGE span with less than OFF_PAGE_VISIBLE_FRAC of its box on-page
  16. INVISIBLE text drawn under PDF text render mode 3 (invisible): from the
  17. content-stream walk, or a span the extractor marked render_mode 3
  18. TRANSPARENT span the extractor found painted at opacity 0
  19. NOT_RENDERED span of which fewer than MIN_INKED_GLYPH_FRAC of the glyphs show,
  20. in the page render, any pixel closer to the span's colour than to
  21. the background under it: covered by a later shape, drawn on its own
  22. colour, or not painted. Only for a span that is on-page; OFF_PAGE
  23. already explains the rest.
  24. METADATA document-info / XMP value carrying an instruction-style phrase
  25. INJECTION an instruction-style phrase in the text layer (HIGH when it also
  26. sits inside a hidden run; LOW when only in visible prose)
  27. One benign case is carved out. Editorial Manager reviewer PDFs place figure-page
  28. labels off-page, so a span hidden ONLY by OFF_PAGE whose ENTIRE text is a
  29. figure/table label ("Figure 2", "Fig. 3", "Table 1", "Graphical Abstract",
  30. "Supplementary Figure S2") is reported as OFF_PAGE at severity INFO and does not
  31. count toward the verdict. A partial match ("Figure 2. Ignore previous instructions
    • Dismissed after review: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore previous instructions"
    • Line 34 on GitHub
  32. ...") or a label hidden any other way (colour, size, render mode) is flagged
  33. exactly as before, and the label text still takes part in the injection scan.
  34. Manifest schema (produced by scan_pdf_layers.py):
  35. {"source": str,
  36. "spans": [{"page": int, "text": str, "size": float,
  37. "color": [r,g,b], "bg": [r,g,b], "visible_frac": float,
  38. # optional, written by the current extractor; absent = not checked
  39. "glyphs": int, "glyphs_inked": int, "render_mode": 3, "opacity": float},
  40. ...],
  41. "invisible_strings": [{"page": int, "text": str}, ...],
  42. "metadata": {field: value, ...}}
  43. Usage:
  44. python3 check_pdf_injection.py paper.manifest.json # human report
  45. python3 check_pdf_injection.py - < paper.manifest.json # read stdin
  46. python3 check_pdf_injection.py m.json --strict --quiet # gate (exit code only)
  47. python3 check_pdf_injection.py m.json --sanitize safe.txt # visible-only text
  48. python3 check_pdf_injection.py m.json --json # machine-readable
  49. Exit: 0 CLEAN; under --strict, 1 when the verdict reaches --fail-on (default
  50. suspicious) — i.e. any hidden or injected text halts the gate.
  51. """
  52. from __future__ import annotations
  53. import argparse
  54. import json
  55. import re
  56. import sys
  57. from dataclasses import dataclass, field, asdict
  58. # --- tunables (the single home for every threshold) ---------------------------
  59. CONTRAST_THRESH = 40.0 # sRGB Euclidean distance; below this text ~ background
  60. MIN_FONT_PT = 4.0 # spans smaller than this are effectively invisible
  61. OFF_PAGE_VISIBLE_FRAC = 0.5 # a span with <50% of its box on-page is off-page
  62. MIN_INKED_GLYPH_FRAC = OFF_PAGE_VISIBLE_FRAC # same half-the-span rule, for glyphs the render shows
  63. # A figure/table label, matched against the WHOLE span (whitespace collapsed), never
  64. # a prefix. The label vocabulary plus at most three alphanumerics cannot spell an
  65. # instruction, so excusing an off-page span of this shape cannot hide one.
  66. FIGURE_LABEL_RE = re.compile(
  67. r"(figure|fig\.?|table|graphical abstract|supplementary (figure|table|material))"
  68. r"[ _]?[0-9a-z]{0,3}\.?", re.I)
  69. # Instruction-style phrases with no place in a manuscript body. Tuned to avoid
  70. # firing on ordinary scientific prose ("we recommend a larger cohort").
  71. INJECTION_PATTERNS = [
  72. r"ignore\s+(all\s+)?(the\s+)?(previous|prior|above|earlier)\s+(instructions?|prompts?|text)",
  73. r"disregard\s+(all\s+)?(previous|prior|the\s+above)",
  74. r"(give|write|provide|produce)\s+(a\s+|only\s+a\s+|an\s+)?(positive|favou?rable|glowing|strong)\s+(review|assessment|evaluation)",
  75. r"positive\s+review\s+only",
  76. r"recommend(\s+this\s+(paper|manuscript|submission))?\s+(for\s+)?accept",
  77. r"accept\s+this\s+(paper|manuscript|submission)",
  78. r"as\s+(a|an)\s+(ai|language\s+model|large\s+language\s+model|llm|reviewer)\b",
  79. r"do\s+not\s+(mention|disclose|reveal|highlight)\s+(any\s+)?(weakness|limitation|flaw|negativ)",
  80. r"(highlight|emphasi[sz]e)\s+(only\s+)?(the\s+)?(strengths?|positives?|novelty)",
  81. r"you\s+(must|should|need\s+to)\s+(recommend|accept|rate|give)\b",
  82. r"override\s+(your|the)\s+(instructions?|guidelines?|system)",
  83. ]
  84. INJECTION_RE = [re.compile(p, re.I) for p in INJECTION_PATTERNS]
  85. _HIDDEN_KINDS = ("LOW_CONTRAST", "TINY_FONT", "OFF_PAGE", "INVISIBLE", "TRANSPARENT",
  86. "NOT_RENDERED")
  87. _SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
  88. _VERDICT_RANK = {"CLEAN": 0, "SUSPICIOUS": 1, "INJECTION DETECTED": 2}
  89. @dataclass
  90. class Finding:
  91. page: int # 1-indexed; 0 = document-level (metadata / whole-text scan)
  92. kind: str
  93. severity: str # HIGH / MEDIUM / LOW, or INFO (reported, not counted in the verdict)
  94. text: str
  95. detail: str = ""
  96. @dataclass
  97. class Report:
  98. source: str
  99. findings: list[Finding] = field(default_factory=list)
  100. hidden_char_count: int = 0
  101. injection_hits: int = 0
  102. @property
  103. def verdict(self) -> str:
  104. if any(f.kind in ("INJECTION", "METADATA") and f.severity == "HIGH"
  105. for f in self.findings):
  106. return "INJECTION DETECTED"
  107. return "SUSPICIOUS" if self.blocking() else "CLEAN"
  108. def blocking(self) -> list[Finding]:
  109. """Findings that count toward the verdict (everything except INFO)."""
  110. return [f for f in self.findings if f.severity != "INFO"]
  111. def _dist(a: list[int], b: list[int]) -> float:
  112. return sum((x - y) ** 2 for x, y in zip(a, b)) ** 0.5
  113. def _is_figure_label(txt: str) -> bool:
  114. return FIGURE_LABEL_RE.fullmatch(" ".join(txt.split())) is not None
  115. def audit(manifest: dict) -> tuple[Report, str]:
  116. """Return (report, visible_only_text). Pure function of the manifest."""
  117. rep = Report(source=str(manifest.get("source", "<manifest>")))
  118. visible_chunks: list[str] = []
  119. all_chunks: list[str] = []
  120. hidden_chunks: list[str] = []
  121. # -- metadata injection -----------------------------------------------------
  122. for field_name, value in (manifest.get("metadata") or {}).items():
  123. blob = str(value)
  124. for rx in INJECTION_RE:
  125. m = rx.search(blob)
  126. if m:
  127. rep.findings.append(Finding(
  128. 0, "METADATA", "HIGH",
  129. blob[max(0, m.start() - 20):m.end() + 20].strip(),
  130. f"injection phrase in metadata field '{field_name}'"))
  131. rep.injection_hits += 1
  132. break # one finding per metadata field is enough
  133. # -- span analysis ----------------------------------------------------------
  134. for sp in manifest.get("spans", []):
  135. txt = sp.get("text", "")
  136. if not txt.strip():
  137. continue
  138. all_chunks.append(txt)
  139. reasons: list[str] = []
  140. color = sp.get("color", [0, 0, 0])
  141. bg = sp.get("bg", [255, 255, 255])
  142. size = float(sp.get("size", 12.0))
  143. vfrac = float(sp.get("visible_frac", 1.0))
  144. d = _dist(color, bg)
  145. if d < CONTRAST_THRESH:
  146. reasons.append(f"LOW_CONTRAST text{tuple(color)} vs bg{tuple(bg)} (d={d:.0f})")
  147. if size < MIN_FONT_PT:
  148. reasons.append(f"TINY_FONT {size:.1f}pt")
  149. if vfrac < OFF_PAGE_VISIBLE_FRAC:
  150. reasons.append(f"OFF_PAGE {vfrac*100:.0f}% of box on-page")
  151. # Rendering evidence from the extractor. A span get_text() reports is not
  152. # necessarily a span anyone can see: render mode 3 and opacity 0 come back
  153. # as ordinary spans, and so does text under an opaque shape or on its own
  154. # colour. Left in the visible text, they went to the LLM as "safe".
  155. if sp.get("render_mode") == 3:
  156. reasons.append("INVISIBLE render mode 3")
  157. if sp.get("opacity") is not None and float(sp["opacity"]) <= 0.0:
  158. reasons.append("TRANSPARENT opacity 0")
  159. glyphs, inked = sp.get("glyphs"), sp.get("glyphs_inked")
  160. if (glyphs and inked is not None and vfrac >= OFF_PAGE_VISIBLE_FRAC
  161. and int(inked) < MIN_INKED_GLYPH_FRAC * int(glyphs)):
  162. reasons.append(f"NOT_RENDERED {int(inked)}/{int(glyphs)} glyphs drawn in the text "
  163. "colour (covered, same colour as what is under it, or not painted)")
  164. if len(reasons) == 1 and reasons[0].startswith("OFF_PAGE") and _is_figure_label(txt):
  165. # Kept in the hidden text the injection scan reads, so that scan behaves
  166. # exactly as before; only this span's own finding stops counting.
  167. hidden_chunks.append(txt)
  168. rep.findings.append(Finding(
  169. int(sp.get("page", 0)), "OFF_PAGE", "INFO", txt.strip()[:200],
  170. f"{reasons[0]}; figure/table label only (Editorial Manager places "
  171. "these off-page); not counted in the verdict"))
  172. elif reasons:
  173. rep.hidden_char_count += len(txt)
  174. hidden_chunks.append(txt)
  175. rep.findings.append(Finding(
  176. int(sp.get("page", 0)), reasons[0].split()[0], "HIGH",
  177. txt.strip()[:200], "; ".join(reasons)))
  178. else:
  179. visible_chunks.append(txt)
  180. # -- invisible render mode --------------------------------------------------
  181. for iv in manifest.get("invisible_strings", []):
  182. txt = iv.get("text", "")
  183. if not txt.strip():
  184. continue
  185. all_chunks.append(txt)
  186. hidden_chunks.append(txt)
  187. rep.hidden_char_count += len(txt)
  188. rep.findings.append(Finding(
  189. int(iv.get("page", 0)), "INVISIBLE", "HIGH", txt.strip()[:200],
  190. "text under render mode 3 (invisible)"))
  191. # -- injection-phrase scan (severity depends on hidden context) -------------
  192. full_text = " ".join(all_chunks)
  193. hidden_text = " ".join(hidden_chunks)
  194. for rx in INJECTION_RE:
  195. m = rx.search(full_text)
  196. if not m:
  197. continue
  198. in_hidden = bool(rx.search(hidden_text))
  199. rep.injection_hits += 1
  200. rep.findings.append(Finding(
  201. 0, "INJECTION", "HIGH" if in_hidden else "LOW",
  202. full_text[max(0, m.start() - 25):m.end() + 25].strip(),
  203. "phrase inside HIDDEN text" if in_hidden
  204. else "phrase in visible text (verify manually; may be legitimate)"))
  205. return rep, "\n".join(visible_chunks)
  206. def format_report(rep: Report, color: bool) -> str:
  207. tag = {"CLEAN": "\033[92m", "SUSPICIOUS": "\033[93m",
  208. "INJECTION DETECTED": "\033[91m"}.get(rep.verdict, "") if color else ""
  209. end = "\033[0m" if color else ""
  210. n_info = len(rep.findings) - len(rep.blocking())
  211. lines = [f"{tag}== {rep.verdict} =={end} {rep.source}",
  212. f"findings={len(rep.blocking())} hidden_chars={rep.hidden_char_count} "
  213. f"injection_hits={rep.injection_hits}" + (f" info={n_info}" if n_info else "")]
  214. if not rep.blocking():
  215. lines.append("no hidden or injected text detected."
  216. + (" Off-page figure/table labels listed as INFO." if n_info else ""))
  217. if not rep.findings:
  218. return "\n".join(lines)
  219. for f in sorted(rep.findings, key=lambda x: (_SEV_ORDER.get(x.severity, 3),
  220. x.kind, x.page)):
  221. loc = f"p{f.page}" if f.page else "meta"
  222. lines.append(f"[{f.severity:<6}] {f.kind:<12} {loc:>5} {f.detail}")
  223. lines.append(f" > {f.text!r}")
  224. return "\n".join(lines)
  225. def _load(path: str) -> dict:
  226. raw = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
  227. return json.loads(raw)
  228. def main(argv: list[str] | None = None) -> int:
  229. ap = argparse.ArgumentParser(description=__doc__,
  230. formatter_class=argparse.RawDescriptionHelpFormatter)
  231. ap.add_argument("manifest", help="span-manifest JSON from scan_pdf_layers.py ('-' = stdin)")
  232. ap.add_argument("--strict", action="store_true",
  233. help="exit non-zero when the verdict reaches --fail-on")
  234. ap.add_argument("--fail-on", choices=["never", "suspicious", "injection"],
  235. default="suspicious", help="strict-mode failure threshold (default: suspicious)")
  236. ap.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
  237. ap.add_argument("--json", action="store_true", help="emit JSON instead of a text report")
  238. ap.add_argument("--sanitize", metavar="OUT",
  239. help="write visible-only text (safe to feed an LLM) to OUT")
  240. args = ap.parse_args(argv)
  241. try:
  242. manifest = _load(args.manifest)
  243. except (OSError, json.JSONDecodeError) as e:
  244. print(f"error: cannot read manifest: {e}", file=sys.stderr)
  245. return 2
  246. rep, visible = audit(manifest)
  247. if args.sanitize:
  248. with open(args.sanitize, "w", encoding="utf-8") as fh:
  249. fh.write(visible)
  250. if not args.quiet:
  251. if args.json:
  252. print(json.dumps({"detector": "check_pdf_injection", "source": rep.source, "verdict": rep.verdict,
  253. "hidden_char_count": rep.hidden_char_count,
  254. "injection_hits": rep.injection_hits,
  255. "findings": [asdict(f) for f in rep.findings]},
  256. ensure_ascii=False, indent=2))
  257. else:
  258. print(format_report(rep, color=sys.stdout.isatty()))
  259. if args.strict:
  260. thresh = {"never": 99, "suspicious": 1, "injection": 2}[args.fail_on]
  261. if _VERDICT_RANK[rep.verdict] >= thresh:
  262. return 1
  263. return 0
  264. if __name__ == "__main__":
  265. raise SystemExit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.