Skills¶

Skills are markdown instruction overlays that change how the agent approaches a task. They are not the same thing as agent modes, and they are not a mechanism for registering new native medical backends.

OpenMed currently ships 20 built-in skills. You can also add your own local skills.

What skills do¶

Skills can:

add domain-specific instructions
bias the workflow shape the model follows
provide reusable task framing for common jobs
optionally carry metadata such as allowed_tools

Important boundary:

skills are mainly prompt/instruction overlays
hard tool restriction is primarily enforced by agent mode, not by the skill layer alone

How to use skills¶

Use any of these entry points:

type $ in the TUI to browse skills
run /skill in the TUI
launch with openmed agent --skill <skill-id>
ask the agent to load a specific skill

Example:

openmed agent --skill reviewing-prior-auth

Built-in skills¶

Skill ID	Purpose
`analyzing-clinical-text`	Clinical entity extraction, note comparison, medication review, and related text analysis
`analyzing-health-data`	Multi-source consumer record import, trend analysis, reconciliation, visit prep, narratives, and optional FHIR-oriented output
`authoring-openmed-skills`	OpenMed skill creation rules, workflow routing, and release-ready skill catalog behavior
`auditing-medical-codes`	ICD-10 specificity review, terminology cross-checks, coding compliance, and HCC / RAF-oriented audits
`care-coordination`	Inbox triage, discharge handoff, adapter-prepared input packs, follow-up tasks, and reviewer-safe patient drafts
`citing-evidence`	Source registry, inline citation ID, PubMed, official guidance, deep-research outputs, and evidence-gap rules
`developing-fhir`	FHIR R4 implementation, validation, and debugging
`documenting-clinical-visits`	SOAP-note generation from visit transcripts with coding hints
`drafting-trial-protocols`	Structured trial protocol drafting from provided inputs
`escalating-to-reviewer`	Reviewer-gated draft/finalize behavior with approval tokens and reviewer metadata
`explaining-eob-claims`	Plain-language explanation of EOB and claim data
`handling-phi-disclosure`	Output-side PHI disclosure, redaction, local artifact safety, and audit notes
`managing-case-context`	Explicit case-scoped context using `case_id` and local case workspaces
`preparing-clinical-artifacts`	Clinical artifact packaging across PDF, DOCX, XLSX, Markdown, and JSON
`processing-pii`	PII detection, extraction, and de-identification workflows
`researching-literature`	PubMed search, abstract retrieval, clinical literature deep research, and evidence synthesis
`reviewing-appeals`	Appeal review against denial requirements and evidence gaps
`reviewing-prior-auth`	Prior-auth review against codes and LCD/NCD criteria
`running-clinical-workflows`	Guidance for deterministic workflows plus domain, evidence, PHI, reviewer, case-context, and artifact skill pairing
`special-pathogen-triage`	Returned-traveler fever/VHF workups with official-source evidence and reviewer-gated packets

Two practical rules:

pair analyzing-health-data with --agent consumer when you want the restricted personal-health lane
pair care-coordination with --agent coordination when you want inbox/discharge work plus reviewer-safe finalize flows

Workflow skill recommendations¶

Deterministic workflows now expose skill guidance in two places:

list_workflows() returns recommended_skills for each workflow.
Successful run_workflow(...) results include recommended_skills plus a short skill_hint.

This matters when an agent jumps straight to a workflow. The workflow still runs deterministically, but the skill recommendations tell the model which overlays to load before summarizing the receipt, writing artifact commentary, or finalizing reviewer-gated output.

High-signal pairings:

Workflow	Skills to show in demos
`clinical_literature_research`	`researching-literature`, `citing-evidence`, `preparing-clinical-artifacts`
`special_pathogen_workup`	`special-pathogen-triage`, `citing-evidence`, `escalating-to-reviewer`, `handling-phi-disclosure`, `preparing-clinical-artifacts`
`prior_auth_review` / `appeal_review`	Domain review skill, `citing-evidence`, `escalating-to-reviewer`, `handling-phi-disclosure`, `preparing-clinical-artifacts`
`clinical_inbox_triage` / `discharge_handoff`	`care-coordination`, `escalating-to-reviewer`, `handling-phi-disclosure`, `preparing-clinical-artifacts`, `managing-case-context`

Domain skills also include Companion skills sections so the graph works in the other direction: if the agent starts by loading reviewing-prior-auth, the skill points it toward the reusable evidence, reviewer, PHI, and artifact guardrails.

Add your own skills¶

Custom skills load from:

~/.config/openmed/skills/
or OPENMED_SKILLS_DIR if you override the directory

Supported formats:

a flat markdown file named <skill-id>.md
a package directory named <skill-id>/SKILL.md

The filename or folder name becomes the skill ID used by $, /skill, load_skill, and openmed agent --skill.

Example: flat markdown skill¶

~/.config/openmed/skills/payer-policy-review.md

---
description: Review payer policy context before prior auth analysis.
allowed_tools:
  - search_pubmed
  - mcp__guidelines__*
---

Always check the payer policy toolset before drafting the recommendation.
Prefer policy citations over generic summaries when both are available.

Example: package skill¶

~/.config/openmed/skills/payer-policy-review/SKILL.md

Review payer policy context before prior auth analysis.

Always check the payer policy toolset before drafting the recommendation.
Prefer policy citations over generic summaries when both are available.

Skill loading behavior¶

New or edited skills are picked up on restart
User skills can override built-in skills by reusing the same skill ID
The TUI skill picker shows built-in and user skills together
User-added skills and user-added MCP servers are supported today
Brand-new native medical tool integrations are not a public extension surface yet
Native DOCX/XLSX and case-context support are tool additions; the matching skills only guide when and how to use them

Skill vs agent mode vs MCP¶

Use the right surface for the right job:

Surface	Use it when...
Skill	You want reusable instructions for how the agent should approach a task
Agent mode	You want a different tool-access boundary such as `clinical`, `consumer`, `coordination`, or `plan`
MCP	You need external tools or data sources that are not already part of OpenMed's native tool inventory

Example prompts¶

Load the reviewing-prior-auth skill and review this request against LCD criteria.

Load the documenting-clinical-visits skill and turn this transcript into a structured SOAP note.

Load the running-clinical-workflows skill and run a chart summary on tests/fixtures/demo_inputs/case_001/intake_note.txt

Load the analyzing-health-data skill, import this FHIR export, and run a draft consumer_summary with timeline, trends, reconciliation notes, and visit-prep questions.

Load the care-coordination skill, normalize this portal export into a thread pack, and run a draft clinical_inbox_triage workflow.