medsci-skills 4.1.0

package/README_FIRST.md

@@ -0,0 +1,27 @@
+# MedSci Skills Classroom Installer
+
+This ZIP is for non-programmer classroom installation.
+
+## Windows
+
+1. Unzip this folder.
+2. Double-click `installers/install-windows.cmd`.
+3. Restart Claude Code Desktop, Codex Desktop, or Cursor.
+4. Paste this first test prompt:
+
+```text
+MedSci Skills가 설치됐는지 확인하고, 오늘 실습에 쓸 대표 스킬 5개만 보여줘.
+```
+
+If Windows shows a security warning, choose **More info** and then **Run anyway**.
+The installer copies the `skills/` folder into local agent skill folders and writes
+an install log in this folder.
+
+## macOS
+
+1. Unzip this folder.
+2. Double-click `installers/install-macos.command`.
+3. Restart Claude Code Desktop, Codex Desktop, or Cursor.
+4. Paste the same first test prompt above.
+
+If macOS blocks the file, right-click it, choose **Open**, and confirm once.

package/bin/medsci-skills.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/*
+ * medsci-skills — terminal-friendly installer shortcut for the MedSci Skills suite.
+ *
+ * Zero-dependency Node shim. The actual install logic lives in the dependency-free
+ * Python installer (installers/install.py); this CLI only wraps it and adds a light
+ * `doctor` diagnostic. For deep environment diagnostics use the in-agent `setup-medsci`
+ * skill — this `doctor` is intentionally a thin npm-level check, not a replacement.
+ *
+ * Canonical distribution stays the GitHub repo + Claude Code plugin marketplace;
+ * this package is a convenience shortcut for terminal users.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const INSTALLER = path.join(PKG_ROOT, 'installers', 'install.py');
+const CATALOG = path.join(PKG_ROOT, 'metadata', 'skills_catalog.json');
+
+function readPkg() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+  } catch (e) {
+    return { name: 'medsci-skills', version: 'unknown' };
+  }
+}
+
+function pythonCmd() {
+  // Require a Python 3 interpreter — installers/install.py is Python 3 only.
+  // 'python' is accepted only if it reports Python 3.x (some systems alias it to 2.7).
+  for (const cmd of ['python3', 'python']) {
+    const r = spawnSync(cmd, ['--version'], { encoding: 'utf8' });
+    if (r.status === 0) {
+      const out = (r.stdout || '') + (r.stderr || ''); // Py2 prints version to stderr
+      if (/Python 3\./.test(out)) return cmd;
+    }
+  }
+  return null;
+}
+
+function printHelp() {
+  const pkg = readPkg();
+  process.stdout.write(
+`${pkg.name} v${pkg.version}
+MedSci Skills — medical/scientific research skill suite for AI coding agents.
+
+Usage:
+  npx medsci-skills <command> [options]
+  medsci-skills <command> [options]      (after a global install)
+
+Commands:
+  install [--target all|claude|codex|cursor] [--cursor-project <dir>] [--dry-run]
+                       Copy the skills into your agent's skill folder.
+                       Delegates to the dependency-free Python installer and
+                       passes every flag through (including Cursor rule install).
+  list                 List the bundled skills, grouped by category.
+  doctor               Quick environment check (Node, Python, skill folders).
+                       For a full check, run the in-agent 'setup-medsci' skill.
+  --version, -v        Print the package version.
+  --help, -h           Show this help.
+
+Notes:
+  - npm/npx is a terminal-friendly shortcut. The canonical install paths are the
+    Claude Code plugin marketplace and the GitHub repo (see the project README).
+  - 'install'/'doctor' require python3 on PATH (the installer is dependency-free).
+`);
+}
+
+function cmdVersion() {
+  process.stdout.write(readPkg().version + '\n');
+}
+
+function cmdList() {
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf8'));
+  } catch (e) {
+    process.stderr.write('Could not read the skills catalog (' + CATALOG + ').\n');
+    return 1;
+  }
+  const skills = Array.isArray(catalog.skills) ? catalog.skills : [];
+  const groups = new Map();
+  for (const s of skills) {
+    const label = s.category_label || s.category || 'Other';
+    if (!groups.has(label)) groups.set(label, []);
+    groups.get(label).push(s.slug);
+  }
+  process.stdout.write(`MedSci Skills — ${skills.length} skills\n`);
+  for (const [label, slugs] of groups) {
+    process.stdout.write(`\n${label}\n  ${slugs.sort().join(', ')}\n`);
+  }
+  return 0;
+}
+
+function cmdDoctor() {
+  const pkg = readPkg();
+  const py = pythonCmd();
+  const claudeDir = path.join(os.homedir(), '.claude', 'skills');
+  const codexDir = path.join(os.homedir(), '.agents', 'skills');
+  const lines = [];
+  lines.push(`medsci-skills doctor — ${pkg.name} v${pkg.version}`);
+  lines.push(`  node           : ${process.version}`);
+  lines.push(`  python3        : ${py ? py + ' (found)' : 'NOT FOUND — needed for install'}`);
+  lines.push(`  installer      : ${fs.existsSync(INSTALLER) ? 'present' : 'MISSING'}`);
+  lines.push(`  ~/.claude/skills : ${fs.existsSync(claudeDir) ? 'exists' : 'not yet created'}`);
+  lines.push(`  ~/.agents/skills : ${fs.existsSync(codexDir) ? 'exists' : 'not yet created'}`);
+  lines.push('');
+  lines.push('For a full environment check (Python, R, Git, Zotero, MCP servers),');
+  lines.push("run the in-agent 'setup-medsci' skill after installing.");
+  process.stdout.write(lines.join('\n') + '\n');
+  return py ? 0 : 1;
+}
+
+function cmdInstall(rest) {
+  const py = pythonCmd();
+  if (!py) {
+    process.stderr.write(
+      'python3 was not found on your PATH.\n' +
+      'The installer is a dependency-free Python script. Install Python 3, or use the\n' +
+      'git / classroom / plugin-marketplace install paths described in the project README.\n');
+    return 1;
+  }
+  if (!fs.existsSync(INSTALLER)) {
+    process.stderr.write('Installer not found at ' + INSTALLER + '\n');
+    return 1;
+  }
+  const r = spawnSync(py, [INSTALLER, ...rest], { stdio: 'inherit' });
+  return r.status == null ? 1 : r.status;
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    printHelp();
+    return 0;
+  }
+  if (args[0] === '--version' || args[0] === '-v' || args[0] === 'version') {
+    cmdVersion();
+    return 0;
+  }
+  switch (args[0]) {
+    case 'list':
+      return cmdList();
+    case 'doctor':
+      return cmdDoctor();
+    case 'install':
+      return cmdInstall(args.slice(1));
+    default:
+      process.stderr.write(`Unknown command: ${args[0]}\n\n`);
+      printHelp();
+      return 2;
+  }
+}
+
+process.exit(main(process.argv));

package/installers/install-macos.command

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -u
+
+cd "$(dirname "$0")/.."
+
+echo "MedSci Skills Installer for macOS"
+echo
+
+if command -v python3 >/dev/null 2>&1; then
+  python3 installers/install.py --target all
+elif command -v python >/dev/null 2>&1; then
+  python installers/install.py --target all
+else
+  echo "Python was not found."
+  echo "Install Python 3 from https://www.python.org/downloads/ and run this installer again."
+fi
+
+echo
+read -r -p "Press Enter to close..."

package/installers/install-windows.cmd

@@ -0,0 +1,26 @@
+@echo off
+setlocal
+cd /d "%~dp0\.."
+
+echo MedSci Skills Installer for Windows
+echo.
+
+where py >nul 2>nul
+if %errorlevel%==0 (
+  py -3 installers\install.py --target all
+  goto done
+)
+
+where python >nul 2>nul
+if %errorlevel%==0 (
+  python installers\install.py --target all
+  goto done
+)
+
+echo Python was not found.
+echo Please install Python 3 from https://www.python.org/downloads/ and run this installer again.
+echo.
+
+:done
+echo.
+pause

package/installers/install-windows.ps1

@@ -0,0 +1,17 @@
+$ErrorActionPreference = "Stop"
+Set-Location (Join-Path $PSScriptRoot "..")
+
+Write-Host "MedSci Skills Installer for Windows"
+Write-Host ""
+
+if (Get-Command py -ErrorAction SilentlyContinue) {
+    py -3 installers/install.py --target all
+} elseif (Get-Command python -ErrorAction SilentlyContinue) {
+    python installers/install.py --target all
+} else {
+    Write-Host "Python was not found."
+    Write-Host "Please install Python 3 from https://www.python.org/downloads/ and run this installer again."
+}
+
+Write-Host ""
+Read-Host "Press Enter to close"

package/installers/install.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Install MedSci Skills for local agent apps.
+
+This installer is intentionally conservative and dependency-free. It copies the
+repository's skills into common local skill folders and optionally writes a
+small Cursor project rule that tells Cursor where to find the skills.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILLS_DIR = REPO_ROOT / "skills"
+LOG_NAME = "medsci-skills-install-log.txt"
+
+
+def log(message: str, log_lines: list[str]) -> None:
+    print(message)
+    log_lines.append(message)
+
+
+def default_target_dir(target: str) -> Path:
+    # Verified against official host docs on 2026-06-03 (see docs/host_compatibility.md):
+    #   claude -> ~/.claude/skills   (Claude Code; also read by GitHub Copilot and Cursor)
+    #   codex  -> ~/.agents/skills   (Codex personal scope per developers.openai.com/codex/skills;
+    #                                 also read by Cursor and GitHub Copilot)
+    # These two destinations together cover Claude Code, Codex, Cursor, and Copilot, so no
+    # per-host fork is needed. OpenClaw/Hermes remain unverified and are intentionally absent.
+    home = Path.home()
+    if target == "claude":
+        return home / ".claude" / "skills"
+    if target == "codex":
+        return home / ".agents" / "skills"
+    raise ValueError(f"Unknown target: {target}")
+
+
+def verify_discoverable(dest: Path, skill_names: list[str], log_lines: list[str]) -> None:
+    """Assert each installed skill landed at <dest>/<name>/SKILL.md so a host can discover it."""
+    missing = [s for s in skill_names if not (dest / s / "SKILL.md").is_file()]
+    log(f"  verified {len(skill_names) - len(missing)}/{len(skill_names)} skills discoverable at {dest}", log_lines)
+    if missing:
+        raise RuntimeError(f"discoverability check failed at {dest}: missing SKILL.md for {', '.join(missing)}")
+
+
+def copy_skills(target: str, dest: Path, log_lines: list[str], dry_run: bool) -> int:
+    if not SKILLS_DIR.exists():
+        raise FileNotFoundError(f"skills directory not found: {SKILLS_DIR}")
+
+    skill_dirs = sorted(p for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists())
+    log(f"\n[{target}] installing {len(skill_dirs)} skills to {dest}", log_lines)
+
+    if dry_run:
+        for skill in skill_dirs:
+            log(f"  DRY RUN copy {skill.name}", log_lines)
+        return len(skill_dirs)
+
+    dest.mkdir(parents=True, exist_ok=True)
+    for skill in skill_dirs:
+        shutil.copytree(skill, dest / skill.name, dirs_exist_ok=True)
+        log(f"  installed {skill.name}", log_lines)
+    verify_discoverable(dest, [s.name for s in skill_dirs], log_lines)
+    return len(skill_dirs)
+
+
+def install_cursor_rule(project: Path, log_lines: list[str], dry_run: bool) -> None:
+    rules_dir = project / ".cursor" / "rules"
+    rule_path = rules_dir / "medsci-skills.mdc"
+    body = f"""---
+description: Use MedSci Skills for medical research writing, literature search, statistics, figures, and submission workflows.
+alwaysApply: false
+---
+
+# MedSci Skills
+
+When the user asks for medical research workflows, inspect the relevant
+`skills/<skill-name>/SKILL.md` file in this repository before acting.
+
+Start with these entry points:
+
+- `skills/search-lit/SKILL.md` for literature search and verified citations
+- `skills/analyze-stats/SKILL.md` for statistical tables and analysis code
+- `skills/make-figures/SKILL.md` for publication figures
+- `skills/write-paper/SKILL.md` for manuscript sections
+- `skills/check-reporting/SKILL.md` for reporting guideline audits
+
+Use small single-skill tasks first. Avoid running the full end-to-end pipeline
+unless the user explicitly asks and provides the required project files.
+
+Repository path:
+`{REPO_ROOT}`
+"""
+    log(f"\n[cursor] writing project rule to {rule_path}", log_lines)
+    if dry_run:
+        log("  DRY RUN write Cursor rule", log_lines)
+        return
+    rules_dir.mkdir(parents=True, exist_ok=True)
+    rule_path.write_text(body, encoding="utf-8")
+    log("  installed Cursor project rule", log_lines)
+
+
+def run_self_test() -> int:
+    """Simulate installs into throwaway temp dirs, assert every skill is discoverable, and
+    prove no real host directory is touched. Returns 0 on pass, 1 on failure. Writes nothing
+    outside a TemporaryDirectory."""
+    import tempfile
+
+    source = sorted(p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists())
+    n = len(source)
+    problems: list[str] = []
+    sink: list[str] = []
+
+    # Snapshot real host dirs to prove the self-test never creates them.
+    host_dirs = [default_target_dir("claude"), default_target_dir("codex")]
+    existed_before = {d: d.exists() for d in host_dirs}
+
+    with tempfile.TemporaryDirectory(prefix="medsci-selftest-") as tmp:
+        tmp_path = Path(tmp)
+        dest = tmp_path / "skills"
+        try:
+            copied = copy_skills("self-test", dest, sink, dry_run=False)  # includes verify_discoverable
+        except Exception as exc:  # noqa: BLE001
+            problems.append(f"copy/verify raised: {exc}")
+            copied = -1
+        if copied != n:
+            problems.append(f"copied {copied} != source skill count {n}")
+
+        proj = tmp_path / "project"
+        install_cursor_rule(proj, sink, dry_run=False)
+        if not (proj / ".cursor" / "rules" / "medsci-skills.mdc").is_file():
+            problems.append("cursor project rule was not written")
+
+    for d in host_dirs:
+        if not existed_before[d] and d.exists():
+            problems.append(f"self-test created a real host dir: {d}")
+
+    print("MedSci Skills installer self-test")
+    print(f"  source skills: {n}")
+    if problems:
+        for p in problems:
+            print(f"  FAIL: {p}")
+        return 1
+    print(f"  OK: {n}/{n} skills discoverable in temp target; cursor rule written; no host dir touched")
+    return 0
+
+
+def write_log(log_lines: list[str]) -> Path:
+    stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    log_path = REPO_ROOT / f"{stamp}-{LOG_NAME}"
+    log_path.write_text("\n".join(log_lines) + "\n", encoding="utf-8")
+    return log_path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Install MedSci Skills locally.")
+    parser.add_argument(
+        "--target",
+        choices=["all", "claude", "codex", "cursor"],
+        default="all",
+        help="Install target. 'all' installs Claude and Codex, and Cursor if --cursor-project is provided.",
+    )
+    parser.add_argument(
+        "--cursor-project",
+        type=Path,
+        default=None,
+        help="Project folder where a .cursor/rules/medsci-skills.mdc rule should be written.",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Print actions without changing files.")
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Simulate installs into temp dirs, assert all skills are discoverable, and touch no host directory. Exits 0 on pass.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.self_test:
+        return run_self_test()
+    log_lines: list[str] = []
+    log("MedSci Skills Installer", log_lines)
+    log(f"Repository: {REPO_ROOT}", log_lines)
+    log(f"Python: {sys.version.split()[0]}", log_lines)
+    log(f"OS: {os.name}", log_lines)
+
+    try:
+        if args.target in {"all", "claude"}:
+            copy_skills("claude", default_target_dir("claude"), log_lines, args.dry_run)
+        if args.target in {"all", "codex"}:
+            copy_skills("codex", default_target_dir("codex"), log_lines, args.dry_run)
+        if args.target == "cursor" and not args.cursor_project:
+            log("\n[cursor] skipped: pass --cursor-project <folder> to install a Cursor rule.", log_lines)
+        if args.cursor_project:
+            install_cursor_rule(args.cursor_project.expanduser().resolve(), log_lines, args.dry_run)
+
+        log("\nDone. Restart Claude Code, Codex, or Cursor before testing the skills.", log_lines)
+        log("First test prompt:", log_lines)
+        log("MedSci Skills가 설치됐는지 확인하고, 오늘 실습에 쓸 대표 스킬 5개만 보여줘.", log_lines)
+    except Exception as exc:  # noqa: BLE001 - classroom installer should show friendly errors.
+        log(f"\nERROR: {exc}", log_lines)
+        log("If this happened during class, send the install log to the instructor.", log_lines)
+        write_log(log_lines)
+        return 1
+
+    log_path = write_log(log_lines)
+    print(f"\nInstall log: {log_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())