Agent Skills

Agent Skills

Skills are contextual prompts that teach AI coding assistants how to accomplish specific tasks.

For the canonical list of bundled skills, see src/m4/skills/SKILLS_INDEX.md.

What Skills Do

Without skills, an AI assistant might guess at APIs or make assumptions about clinical concepts. With M4 skills installed:

• m4-api: Claude knows to call set_dataset() before queries, returns proper DataFrames, handles errors correctly
• Clinical skills: Claude understands SOFA scoring, Sepsis-3 criteria, KDIGO AKI staging, and other validated clinical concepts

Skills activate automatically when relevant. Ask Claude to "calculate SOFA scores for my cohort" and it will use the validated SQL from MIT-LCP without you needing to look up the implementation.

Installing Skills

During initial setup:

m4 config claude --skills

Or install to an existing project:

# Interactive tool and skill selection
m4 skills

# Install all skills for specific tools
m4 skills --tools claude,cursor

# Install only validated clinical skills
m4 skills --tools claude --tier validated --category clinical

# Install specific skills by name
m4 skills --tools claude --skills sofa-score,sepsis-3-cohort,m4-api

# Install only system skills
m4 skills --tools claude --category system

# List installed skills (with tier and category)
m4 skills --list

When --tools is omitted, an interactive prompt lets you select tools. When no filter flags (--skills, --tier, --category) are provided in interactive mode, you are also prompted to choose between installing all skills or filtering by category, tier, or individual selection.

Filters combine with AND logic: --tier validated --category clinical installs only skills that are both validated and clinical. Filtered installs are additive — existing skills that don't match the filter are left untouched.

Skills are installed to .claude/skills/ (or equivalent for other tools). AI assistants automatically discover skills in these locations.

Available Skills

M4 Framework

Severity Scores

Sepsis and Infection

Organ Failure

Medications and Treatments

Laboratory and Measurements

Cohort Definitions

Data Quality and Structure

Skills vs. Derived Tables

Skills and derived tables are complementary features that share the same clinical knowledge source (mimic-code), but serve different purposes:

Derived tables (mimiciv_derived.*) provide pre-computed results. After running m4 init-derived mimic-iv, tables like mimiciv_derived.sofa and mimiciv_derived.sepsis3 are ready to query directly. For standard analyses -- computing mortality by SOFA score, identifying sepsis cohorts, filtering by AKI stage -- derived tables are the preferred approach. They are faster (no complex SQL at query time), validated (production-tested SQL from mimic-code), and consistent (every user gets the same results).

Skills provide adaptable SQL patterns that the AI assistant can modify for non-standard use cases. When a researcher needs a custom SOFA variant, wants to apply different time windows, or needs to combine concepts in novel ways, skills give the AI the clinical knowledge to generate correct queries from scratch.

When to use which:

• Use derived tables for standard clinical concepts (scores, cohorts, staging) -- they are pre-computed and immediately available
• Use skills when you need customized logic, non-standard criteria, or when working with datasets that do not have derived tables (e.g., eICU)
• Skills and derived tables can be used together -- for example, joining a custom cohort with mimiciv_derived.sofa for severity scores

Skill Structure

Each skill is a directory containing a SKILL.md file:

.claude/skills/
├── m4-api/
│   └── SKILL.md
├── sofa-score/
│   └── SKILL.md
│   └── scripts/
│       └── sofa.sql
├── sepsis-3-cohort/
│   └── SKILL.md
│   └── scripts/
│       └── sepsis3.sql
...

The SKILL.md contains:

---
name: sofa-score
description: Calculate SOFA score for ICU patients...
tier: validated
category: clinical
---

# SOFA Score Calculation

[Detailed instructions, SQL examples, clinical context...]

The frontmatter has four required fields: name, description, tier (one of validated, expert, community), and category (clinical or system). See src/m4/skills/SKILL_FORMAT.md for full details.

Clinical skills include validated SQL scripts in their scripts/ subdirectory.

Creating Custom Skills

You can extend M4 with project-specific skills. Create a skill for your research domain:

---
name: cardiac-surgery-cohort
description: Identify cardiac surgery patients. Triggers on "CABG", "valve replacement", "cardiac surgery"
tier: community
category: clinical
---

# Cardiac Surgery Cohort Selection

When identifying cardiac surgery patients in MIMIC-IV:

1. Use procedure codes from `procedures_icd` table
2. Filter by ICD-10-PCS codes starting with '02' (heart and great vessels)
3. Consider combining with `d_icd_procedures` for code descriptions

## Standard Query

\`\`\`python
from m4 import set_dataset, execute_query

set_dataset("mimic-iv")
cardiac_cohort = execute_query("""
    SELECT DISTINCT p.subject_id, p.hadm_id
    FROM procedures_icd p
    WHERE p.icd_code LIKE '02%'
      AND p.icd_version = 10
""")
\`\`\`

Place in .claude/skills/cardiac-surgery-cohort/SKILL.md and Claude will use it when discussing cardiac surgery research.

Tips for Effective Skills

Be specific about triggers. The description should clearly indicate when the skill applies. Too broad and it activates unnecessarily; too narrow and it won't help.

Include working code examples. Claude learns patterns from examples. Show exact imports, function calls, and expected outputs.

Document edge cases. What errors might occur? What datasets are required? What modalities are needed?

Keep skills focused. One skill per domain or workflow. Combine related but distinct capabilities in separate skills.

Reference validated sources. Clinical skills should cite their sources (e.g., "based on MIT-LCP mimic-code repository").

Verifying Installation

Check which M4 skills are installed:

m4 skills --list

The output shows each tool with its installed skills, tier, and category:

Installed M4 skills:

  ● Claude Code (N skills)
    └─ apsiii-score                    clinical   validated
    └─ sofa-score                      clinical   validated
    └─ m4-api                          system     community
    ...

Or look in your project:

ls .claude/skills/
# m4-api/  sofa-score/  sepsis-3-cohort/  ...

Clinical Skill Sources

All clinical research skills are extracted from MIT-LCP validated repositories:

• mimic-code: https://github.com/MIT-LCP/mimic-code
• eicu-code: https://github.com/MIT-LCP/eicu-code

These repositories contain peer-reviewed implementations used in hundreds of published studies.