Claude Code for Clinicians Chapter 12

Chapter 12: Skills

The word “skill” is going to do double duty in this chapter, and we should sort it out before we go any further. A clinical skill is something a person does — placing a central line, reading a chest X-ray, counseling a family on the implications of a Whipple. In Claude Code, a skill is something different: a packaged playbook, sitting in a folder, that Claude reads on demand when the task in front of it matches the skill’s description. It is not a thing Claude does. It is a written set of instructions Claude uses when the moment calls for it.

A better medical analogy is the clinical pathway. KHCC has a febrile-neutropenia pathway: when a patient presents with fever and a recent absolute neutrophil count below 500, the pathway tells you exactly which cultures to draw, which broad-spectrum antibiotics to start, which imaging to order, and when to escalate. The pathway does not do the work. It tells the resident in front of the patient exactly how the work is done here. A Claude skill is the same idea: a written playbook Claude pulls in when the situation in front of it calls for that playbook.

🧠 Remember. A skill is a folder containing a written playbook. There is no plugin, no install step. If the folder is in the right place, the skill is available.

How a Skill Differs From a Slash Command

We met slash commands in Chapter 11. They look similar to skills — both are markdown files holding prompts — but they are triggered differently.

A rule of thumb: if the trigger is a verb you can type once (“commit this,” “run the eval suite”), it probably wants to be a slash command. If the trigger is a kind of task Claude needs to recognize on its own (“the user is asking me to refactor code — go read the refactoring playbook”), it probably wants to be a skill. Some workflows want both.

Where Skills Live, and What’s Inside

A skill lives at .claude/skills/<skill-name>/SKILL.md. The minimum viable skill is a single file with a small block of metadata at the top:

---
name: code-refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when the user asks to refactor code, improve code structure, reduce technical debt, clean up legacy code, eliminate code smells, or improve maintainability. Guides through a phased approach with research, planning, and safe incremental changes.
---

# Code Refactoring Skill

A systematic approach to refactoring code...
[rest of the playbook]

Two fields are required.

name is the skill’s identifier. Use lowercase letters and hyphens. The folder name should match.

description is the most important line in the whole file. This is the text Claude reads at the start of every session, scanning for a match against whatever you ask it to do. A vague description (“use this for code stuff”) will trigger on everything and become noise. A precise description (“use when the user asks to refactor code, reduce technical debt, or eliminate code smells”) triggers when it should and stays out of the way when it should not.

Everything below the metadata is the playbook itself. It can be as long as it needs to be. The key trick is that Claude only loads the playbook when the skill actually fires — it does not pay the cost of the playbook on every session, only the cost of the short description.

🔧 Technical Stuff. The match between your request and a skill’s description is done by Claude itself, not by a regular expression or keyword search. That is why the description has to be written as instructions to the model — phrases like “Use when…” and “Trigger for…” work because they tell the model what to do, not what to look for.

The Anatomy of a Real Skill

A skill is usually more than one file. The SKILL.md is the entry point, but a mature skill brings in supporting material: reference documents that hold the long-form detail, templates the skill can paste into a new file, and small helper scripts the skill can run.

Here is what a real refactoring skill might look like on disk:

.claude/skills/code-refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

SKILL.md is the spine. It defines the six phases of a refactor — research, test coverage, smell identification, planning, incremental implementation, review — and points at the supporting files when more detail is needed:

See [references/code-smells.md](references/code-smells.md) for the complete catalog.
See [templates/refactoring-plan.md](templates/refactoring-plan.md) for the planning template.

The clever part: Claude does not read code-smells.md at session start. It does not even read it when the skill fires. It reads it only at the moment mid-refactor when it actually needs the smell catalog. The reference document might be hundreds of lines, and it costs zero attention until the moment it is needed.

Scripts work the same way. A script in scripts/ is a small tool Claude can run — python scripts/detect-smells.py src/auth.py — rather than read. Deterministic work belongs in scripts; only the judgment calls belong inside the LLM’s head.

⚠️ Warning. Skills can carry executable scripts. Anyone who installs your skill into their project is trusting your scripts to behave. Read the scripts before you install a skill from somewhere you do not know, and do not ship a skill with a curl | bash script in it.

Three KHCC Skills Worth Building

Here are three skills that would earn their place in an AI Office workflow.

aidi-extractions

This is the most useful one. Almost every clinical pipeline at the AI Office is, underneath, a structured extraction pipeline: take a free-text source (a pathology report, an ER note, a chemo order) and turn it into a row of structured data in a gold table. The pattern is the same every time — call Azure OpenAI’s gpt-4.1-mini through PydanticAI, decrypt names with Fernet, encode MRNs with Optimus, append to a gold table, run against the deceased-patient eval cohort before shipping. (Chapter 0.5 covers each of those pieces if any are unfamiliar.)

A skill that packages this pattern would have:

Now, whenever a clinician says “I need to extract chemo orders for the febrile-neutropenia cohort,” Claude reads the description, recognizes that this is an AI Office extraction task, and pulls in the playbook automatically. The clinician does not have to remember the skill exists.

r-clinical-analysis

The KHCC bone marrow transplant outcomes paper, the Wilms tumor analyses, the post-surgery infection cohort paper — all of them follow the same R analysis spine: a baseline characteristics table from gtsummary, Kaplan-Meier curves with Lancet theming via survminer, univariable and multivariable Cox regression via finalfit, a calibration plot, a small set of standard sanity checks. Every clinician on a new project rebuilds this from memory, and small details drift between papers.

A skill encoding the spine, with reference documents for the table-1 patterns, the Lancet theming customizations, and the date-handling gotchas, would mean every clinical R analysis at KHCC ships with consistent table formats, consistent figure styling, and the same checks for missing data.

scientific-writing

A skill for writing publication-ready academic prose. The trigger description would be along the lines of “use when the user asks to draft a manuscript, a literature review, a grant proposal, an abstract, or any academic document.” Inside, the spine covers the two-stage outline-then-prose process, citation discipline (verify before you cite), and reporting-guideline compliance (CONSORT for trials, STROBE for cohort studies, PRISMA for reviews). Reference files hold the section-by-section IMRAD playbook and the reporting-guideline checklists. Templates hold a LaTeX skeleton and a cover-letter template.

Now any clinician at KHCC who asks Claude to draft a paper gets the same disciplined output, with the same citation rules, the same structure, and the same reporting-guideline checks every time.

💡 Tip. Write the SKILL.md last. Build the reference documents and templates first, because that forces you to articulate the actual content. Once the references exist, the SKILL.md becomes a short spine that ties them together. You end up with a sharper, shorter skill.

The Context Trick (Why Skills Are Cheap)

This is the property that makes skills worth using: they do not inflate your baseline context.

When a session starts, Claude only loads the names and descriptions of available skills — a line or two per skill. You can have 30 skills installed and the baseline cost is 30 short descriptions — basically nothing.

When you ask something that matches a description, Claude loads that skill’s SKILL.md body. When the SKILL.md references other files (references/foo.md, templates/bar.py, scripts/baz.py), Claude reads those only at the moment it actually needs them.

So the heavy reference material — the dozens of pages of patterns, the example notebooks, the full schema reference — costs nothing until the moment it matters. Compare this to dumping the same content into CLAUDE.md, where it would cost tokens every single turn forever.

🧠 Remember. Universal rules go in CLAUDE.md. Conditional playbooks go in skills. The rule of thumb: if it applies to every session, CLAUDE.md. If it applies only when the user is doing a specific kind of task, a skill.

Where Skills Live

Anthropic publishes a set of high-quality skills you can install and adapt: docx (working with Word documents), pptx (PowerPoint), xlsx (Excel), pdf (PDFs), and more, and recent versions of Claude Code bundle several skills out of the box. Browsing these is the fastest way to see how a well-built skill is structured. Copy one, change the parts you need, and you have a working starter.

Try This

  1. Pick one workflow you have explained to Claude more than twice this month. Write the explanation down. The first draft is your SKILL.md.
  2. Write the description in two different ways. Once for what the skill does (“draft a clinical manuscript”). Once for when Claude should reach for it (“use when the user asks to write, draft, or revise a clinical research manuscript, abstract, or grant proposal”). The second one is what triggers it. Make it specific.
  3. Save the file at .claude/skills/<your-skill-name>/SKILL.md. Start a fresh session. Phrase a request that should fire the skill. Notice Claude reading it in.
  4. Phrase a request that should not fire the skill. Confirm Claude leaves it alone. If it fires anyway, your description is too broad. Tighten it.

Watch Out