med-mentor is a custom agent skill and structured workspace environment designed for medical students, residents, physicians, nurses, and other healthcare trainees. It enables AI coding agents (like Claude Code or Antigravity) to guide users through structured, stateful clinical lessons, board preparation (USMLE, COMLEX, NCLEX, specialty board exams), and clinical reasoning drills using interactive HTML widgets.
- How it Works
- Getting Started
- Features & Capabilities
- Repository & Workspace Structure
- Contributing
- License
The skill structures learning dynamically over multiple sessions. Instead of dumping raw textbook information, the agent guides the user by building interactive lessons (with flashcards, diagnostic calculators, quizzes, and clinical algorithms) custom-fit to the user's knowledge stage.
sequenceDiagram
participant User
participant Agent as AI Coding Agent (Claude)
participant Skill as med-mentor Skill (SKILL.md)
participant Workspace as Teaching Workspace
User->>Agent: "Teach me antiarrhythmics / board prep"
Agent->>Skill: Reads SKILL.md & references
Agent->>Workspace: Checks MISSION.md & learning-records/
Note over Agent,Workspace: Determines Zone of Proximal Development (ZPD)
Agent->>Workspace: Scaffolds a new Interactive HTML Lesson
Workspace->>User: Renders lesson.html (quizzes, checklists, etc.)
User->>Agent: Interacts and answers questions
Agent->>Workspace: Logs clinical pearls & misses to learning-records/
To enable your AI agent to dynamically teach you clinical subjects, add this skill to your workspace. The skill is fully compatible with any agent harness supporting workspace configuration directories:
- Claude Code (
.agents/skills/) - Antigravity & Antigravity CLI (
.agents/skills/) - Codex & Codex CLI (
.codex/skills/) - OpenCode (
.opencode/skills/) - Hermes Agent (
.hermes/skills/) - Cline, Roo-Code, Amp, etc.
Run the following command in your terminal inside your project/study directory:
npx skills add Premansh12/med-mentorThe skills manager will automatically detect your active agent harness and install the skill files in the correct configuration subdirectory.
If you want to manually initialize a new study directory with the required folders (lessons/, assets/, learning-records/) and templates (MISSION.md, RESOURCES.md, NOTES.md), you can run the CLI script directly from GitHub. This will automatically copy the skill configuration files for all supported agent harnesses (Claude Code, Codex, Antigravity, OpenCode, and Hermes Agent) at once:
npx github:Premansh12/med-mentorImagine having a personal medical school mentor, board exam coach, and senior attending resident sitting inside your terminal, walking you through patient cases, quizzing you on drug dosages, and grading your diagnostic accuracy—all tailored to your active study goals.
Lessons aren’t just static text. Agents generate clean, offline-ready HTML interfaces directly in your study folder:
- Active-Recall Flashcards: Double-sided diagnostic cards with interactive click-to-flip functionality.
- Clinical Algorithm Flowcharts: Interactive decision-making trees (e.g., “Determine next step in suspected Pulmonary Embolism based on Wells Criteria”).
- Interactive Quizzes: Multiple-choice board prep questions with immediate clinical rationale disclosures.
- Dosage & Metric Calculators: Live calculators to practice patient dosing (e.g., GFR, CHADS₂-VASc score).
- Interactive Checklists: Procedural guides (OSCE preparation) to check off surgical or diagnostic steps.
Lessons paired with ./assets/styles.css are designed to look like editorial medical journals (clean typography, zero clutter, phone-friendly layouts) to reduce cognitive load while studying.
An integrated safety gate ensures all medical instruction is high-fidelity and citation-backed:
- No fictitious patient data.
- Mandatory links to primary guidelines (AHA, ACC, DSM-5, etc.).
- Automatic clinical disclaimer footers built into every lesson.
Upload or reference your own notes or curriculum documents to ground study sessions:
- Structured Resource Learning: Convert lecture slides, guideline articles, or textbook chapters into compressed, Tufte-style reference documents.
- Custom Vignette Practice: Generate diagnostic quizzes from uploaded note files or practice-test questions.
- Intelligent Study Planning: Provide a rotation schedule, syllabus outline, or exam blueprint to automatically structure a sequenced study plan.
The skill is designed to run natively inside any of your favorite agent tools:
- Includes configuration and deployment support for Claude Code, Antigravity, Codex, OpenCode, and Hermes Agent.
- Zero manual mapping needed; the CLI configures and installs the skill files to the correct agent directories automatically.
This repository contains the skill configuration, documentation references for the AI agent, and template formats:
med-mentor/
├── assets/
│ └── styles.css # The seed stylesheet (copied to target workspaces)
├── bin/
│ └── cli.js # CLI execution script (run via npx)
├── formats/
│ ├── MISSION-FORMAT.md # Template for the user's MISSION.md
│ ├── RESOURCES-FORMAT.md # Template for the user's RESOURCES.md
│ └── LEARNING-RECORD-FORMAT.md # Template for session learning records
├── references/
│ ├── design-system.md # Visual design & editorial system guidelines
│ ├── learning-design.md # Educational philosophy and lesson pacing
│ ├── lesson-authoring.md # Interactive HTML widgets and asset specs
│ ├── mission-and-resources.md # Guidance on setting up goals and study sources
│ ├── reference-documents.md # Reference documents layout guidelines
│ ├── pdf-ingestion.md # Instructions for extracting/learning from user PDFs
│ └── safety-and-sourcing.md # Non-negotiable clinical safety & citation rules
├── SKILL.md # Entry point skill definition for agents
└── LICENSE # GNU GPL v3 License
Tip
assets/styles.css in this repository serves as a starter implementation of the editorial visual guidelines. The CLI automatically copies it into the ./assets/ folder of new workspaces so you can extend it rather than redefining custom CSS styling per lesson.
When the skill runs or is initialized, it builds the following workspace in your current directory:
workspace/
├── MISSION.md # Why you are studying and what exams you're targetting
├── RESOURCES.md # List of verified clinical resources & directories
├── NOTES.md # Your personal preferences and study notes
├── lessons/ # Short, self-contained interactive HTML lessons
├── learning-records/ # Numbered markdown files recording learned pearls and misses
└── assets/ # Shared CSS, JS quiz engines, and calculators
We welcome contributions to help improve the med-mentor framework! Whether you are a developer improving the CLI scaffolding or a medical professional writing clinical references/lesson templates:
- Fork this repository.
- Create a new branch:
git checkout -b feature/amazing-feature. - If extending medical reference materials under
references/, make sure they strictly adhere to the guidelines in references/safety-and-sourcing.md (no real patient data, clear clinical citation). - Commit your changes and push:
git commit -m 'Add antiarrhythmic references' && git push origin feature/amazing-feature. - Open a Pull Request.
This project is licensed under the terms of the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the full text.