Contribute

The user is a clinician who has probably never opened a pull request. Do the git work for them: never make them type a git command, and never use the words "rebase", "upstream", or "HEAD" in anything they read. Their local edits sit next to real patients and real manuscripts, so the safety steps below, not the git mechanics, are why this is a skill.

The one rule that cannot bend

Nothing leaves the machine until the author has seen every line that would leave it and said yes. Until something has been sent, say explicitly, every time, that nothing has been sent.

The safety scan is an aid, not a certificate: no pattern list recognises every patient name or every hospital. Say so out loud, because a user who believes the scanner is complete stops reading the diff, and that is exactly when the leak happens.

If the scan reports a blocker (patient-level data, a credential), do not offer a workaround. The line gets deleted. A contribution never needs patient data to make its point.

Phase 0: What did they change?

python3 "${CLAUDE_SKILL_DIR}/scripts/find_local_changes.py" --target claude --json \
  --out qc/local_changes.json

This compares the installed skills against the hashes of what was shipped. It reads only.

• Nothing changed → say so plainly and stop; that is normal, not a failure. Offer the feedback path (Phase 4) instead.
• Something changed → show it, grouped by skill:
  • A new file (a journal profile, a citation style, a reporting exemplar) — usually the most valuable kind of contribution, because it is domain knowledge nobody in the project has. Say that.
  • An edited file — ask what was wrong for their specialty; the answer is the pull-request description. Never guess at the reason for an edit.
  • A deleted file — usually not a contribution. Ask before including it.

A change that only makes sense in one hospital (internal rules, a template with the department's letterhead) is a local adaptation, not a contribution: say so, leave it out, and tell them keeping it is fine.

Phase 1: The safety scan (blocking)

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" \
  --changes qc/local_changes.json --out qc/safety.json

This gate fails closed: finding anything at all is a non-zero exit, unlike every other detector in the repository — deliberately, because a tool that returns success while printing a hospital name will eventually be trusted to have said nothing.

Verdicts: PHI_SUSPECTED, SECRET (blockers — the line is deleted, not argued with), IDENTITY, INSTITUTION, APPROVAL_ID, MANUSCRIPT_ID, LOCAL_PATH. Fix each finding with them, following the do line the scan prints for it (a name → a role, a hospital → a generic descriptor, an IRB or manuscript ID → removed, a home path → ~). A manuscript ID matters because a paper under review is confidential and its ID identifies it.

A file that is not UTF-8 text (an image, a binary) cannot be scanned or read, so it is listed as NOT SCANNED and the scan fails until it is taken out of the contribution. qc/safety.json records the sha256 of every file it scanned; the submit step refuses unless the files it is about to send are exactly those, unchanged. After any edit, re-run the scan — an older report, or one made with --text on a different file, clears nothing.

Then print the full text of every file that would be sent and ask them to read it. Not a summary — the text. This is the step that actually protects them.

Phase 2: Does it meet the project's own bar?

Run the repository's validator against the change if the repo is available locally; otherwise check by eye:

• A journal profile cites the journal's public author guidelines: word limits, abstract structure and AI policy are quoted from them or left out. No impact factors or numbers from memory.
• A citation style is the official CSL from the Zotero repository.
• A skill edit still says what it does, and the change is general — it would help someone at another hospital. If not, it is a local adaptation; keep it local.

If it does not pass, say what to change, in their words. Do not send a contribution that will be rejected — that is a worse experience than not contributing at all.

Phase 3: Send it

python3 "${CLAUDE_SKILL_DIR}/scripts/submit_contribution.py" \
  --changes qc/local_changes.json --safety qc/safety.json \
  --title "Add a journal profile for <journal>" --dry-run

Always --dry-run first, and show them the plan. Then, on their explicit yes, run it again without --dry-run. The script takes the highest rung available:

1. GitHub tool installed and signed in → it forks, copies the files, and opens the pull request. They type nothing.
2. Installed but not signed in → it prints the single command (gh auth login) and stops. Walk them through it: GitHub.com → HTTPS → log in through the browser.
3. Not installed → it writes the change to a file and opens a pre-filled issue in their browser. Do not make installing a developer tool a condition of helping.

Tell them what happens next: a maintainer reads it, and if something needs changing they can reply in plain language on that page. They will not be asked to do any git work.

Phase 4: Feedback that is not a code change

A false positive or a failed step is often the most useful thing a clinician has: it is the only evidence of how a detector behaves on a real manuscript rather than a synthetic fixture. Collect:

• A detector fired wrongly: which detector (the detector field in its qc/*.json), the verdict, and the smallest possible snippet that reproduces it — rewritten with fake numbers and names if the real one cannot be shown; the shape of the sentence is what matters.
• A step failed: the command, the error, the host (Claude Code / Codex / Cursor / Copilot), the operating system.
• Something was wrong for your specialty: what the toolkit assumed, and what is actually true.

Send it as an issue, after the same safety scan — a repro from a real manuscript is exactly where PHI hides:

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" --text qc/feedback.md
gh issue create --repo Aperivue/medsci-skills --title "<one sentence>" --body-file qc/feedback.md --web

--web opens it in the browser pre-filled: they read it and press Submit. Nothing is sent by us.

Phase 5: Keep their change when they update

Tell them the installer already takes a permanent backup of any skill they modified before it overwrites it (under ~/.medsci-skills/backups/), so updating never destroys their work — many people avoid updating because they assume it would. If the change is worth keeping, contributing it means the next update will contain it.

Settings — nobody is nagged

python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --status
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --on    # remind me
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --off   # never mention it (default)

• Reminders are opt-in and off by default. The installer mentions the option once, at the end of a first install, and never again. Opted in, a reminder appears only when they actually changed something, and at most once a month.
• The setting governs reminders only. /contribute works whenever it is run.
• The setting cannot weaken safety: there is no key for that, and check_contribution_safety.py reads no configuration. Opting in never means "send without asking".

Saying thanks

Many clinicians who find this useful have never starred the repository because nobody told them what a star is for. Once the toolkit has actually done something for them, tell them — the script explains what a star is and makes it one command:

python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --how   # explain + show both ways
python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --now   # do it from here (GitHub CLI)

• Never ask twice — being shown once is recorded, and doing nothing is an answer.
• Never dress this up: do not imply the toolkit is worse off without their star, and do not ask before the toolkit has done something for them. Asking for thanks in advance is begging.

Scope

Touches only the installed skills — never the user's manuscripts, data, or any other file. Contributions arrive as a fork's pull request or an issue; never push to the main repository.

Known limits

• The patient-identifier patterns cover a fixed set of labels and formats. Among what they do not recognise: Korean-language labels for a registration or patient number, a resident registration number written without its hyphen, an alphanumeric patient ID, "hospital number", and a date of birth written with a month name or introduced by "born". Widening them means keyword matching over prose, which has produced false positives before, so it has not been done. Reading every line (Phase 1) is what covers these.