fhir-developer-skill

Q: How do I install fhir-developer-skill?

Run npx skills add https://github.com/anthropics/healthcare --skill fhir-developer-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/fhir-developer-skill/ (personal) or .claude/skills/fhir-developer-skill/ (project).

by anthropics OfficialBackend & APIs

FHIR API development guide for building healthcare endpoints. Use when: (1) Creating FHIR REST endpoints (Patient, Observation, Encounter, Condition, MedicationRequest), (2) Validating FHIR resources and returning proper HTTP status codes and error responses, (3) Implementing SMART on FHIR authorization and OAuth scopes, (4) Working with Bundles, transactions, batch operations, or search pagination. Covers FHIR R4 resource structures, required fields, value sets (status codes, gender, intent), coding systems (LOINC, SNOMED, RxNorm, ICD-10), and OperationOutcome error handling.

Installs: 664
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/anthropics/healthcare --skill fhir-developer-skill

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads fhir-developer-skill automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

FHIR Developer Skill

Quick Reference

HTTP Status Codes

Code	When to Use
`200 OK`	Successful read, update, or search
`201 Created`	Successful create (include `Location` header)
`204 No Content`	Successful delete
`400 Bad Request`	Malformed JSON, wrong resourceType
`401 Unauthorized`	Missing, expired, revoked, or malformed token (RFC 6750)
`403 Forbidden`	Valid token but insufficient scopes
`404 Not Found`	Resource doesn't exist
`412 Precondition Failed`	If-Match ETag mismatch (NOT 400!)
`422 Unprocessable Entity`	Missing required fields, invalid enum values, business rule violations

Required Fields by Resource (FHIR R4)

Resource	Required Fields	Everything Else
Patient	(none)	All optional
Observation	`status`, `code`	Optional
Encounter	`status`, `class`	Optional (including `subject`, `period`)
Condition	`subject`	Optional (including `code`, `clinicalStatus`)
MedicationRequest	`status`, `intent`, `medication[x]`, `subject`	Optional
Medication	(none)	All optional
Bundle	`type`	Optional

Required vs Optional Fields (CRITICAL)

Only validate fields with cardinality starting with "1" as required.

Cardinality	Required?
`0..1`, `0..*`	NO
`1..1`, `1..*`	YES

Common mistake: Making subject or period required on Encounter. They are 0..1 (optional).

Value Sets (Enum Values)

Invalid enum values must return 422 Unprocessable Entity.

Patient.gender

male | female | other | unknown

Observation.status

Encounter.status

Encounter.class (Common Codes)

Code	Display	Use
`AMB`	ambulatory	Outpatient visits
`IMP`	inpatient encounter	Hospital admissions
`EMER`	emergency	Emergency department
`VR`	virtual	Telehealth

Condition.clinicalStatus

Condition.verificationStatus

MedicationRequest.status

MedicationRequest.intent

Bundle.type

Validation Pattern

Python/FastAPI:

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

def operation_outcome(severity: str, code: str, diagnostics: str):
    return {
        "resourceType": "OperationOutcome",
        "issue": [{"severity": severity, "code": code, "diagnostics": diagnostics}]
    }

VALID_OBS_STATUS = {"registered", "preliminary", "final", "amended",
                    "corrected", "cancelled", "entered-in-error", "unknown"}

@app.post("/Observation", status_code=201)
async def create_observation(data: dict):
    if not data.get("status"):
        return JSONResponse(status_code=422, content=operation_outcome(
            "error", "required", "Observation.status is required"
        ), media_type="application/fhir+json")

    if data["status"] not in VALID_OBS_STATUS:
        return JSONResponse(status_code=422, content=operation_outcome(
            "error", "value", f"Invalid status '{data['status']}'"
        ), media_type="application/fhir+json")
    # ... create resource

TypeScript/Express:

const VALID_OBS_STATUS = new Set(['registered', 'preliminary', 'final', 'amended',
  'corrected', 'cancelled', 'entered-in-error', 'unknown']);

app.post('/Observation', (req, res) => {
  if (!req.body.status) {
    return res.status(422).contentType('application/fhir+json')
      .json(operationOutcome('error', 'required', 'Observation.status is required'));
  }
  if (!VALID_OBS_STATUS.has(req.body.status)) {
    return res.status(422).contentType('application/fhir+json')
      .json(operationOutcome('error', 'value', `Invalid status '${req.body.status}'`));
  }
  // ... create resource
});

Pydantic v2 Models (use Literal, not const=True):

from typing import Literal
from pydantic import BaseModel

class Patient(BaseModel):
    resourceType: Literal["Patient"] = "Patient"
    id: str | None = None
    gender: Literal["male", "female", "other", "unknown"] | None = None

Coding Systems (URLs)

System	URL
LOINC	`http://loinc.org`
SNOMED CT	`http://snomed.info/sct`
RxNorm	`http://www.nlm.nih.gov/research/umls/rxnorm`
ICD-10	`http://hl7.org/fhir/sid/icd-10`
v3-ActCode	`http://terminology.hl7.org/CodeSystem/v3-ActCode`
Observation Category	`http://terminology.hl7.org/CodeSystem/observation-category`
Condition Clinical	`http://terminology.hl7.org/CodeSystem/condition-clinical`
Condition Ver Status	`http://terminology.hl7.org/CodeSystem/condition-ver-status`

Common LOINC Codes (Vital Signs)

Code	Description
`8867-4`	Heart rate
`8480-6`	Systolic blood pressure
`8462-4`	Diastolic blood pressure
`8310-5`	Body temperature
`2708-6`	Oxygen saturation (SpO2)

Data Type Patterns

Coding (direct) vs CodeableConcept (wrapped)

Coding - Used by Encounter.class:

{"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB"}

CodeableConcept - Used by Observation.code, Condition.code:

{"coding": [{"system": "http://loinc.org", "code": "8480-6"}], "text": "Systolic BP"}

Reference

{"reference": "Patient/123", "display": "John Smith"}

Identifier

{"system": "http://hospital.example.org/mrn", "value": "12345"}

Common Mistakes

Mistake	Correct Approach
Making `subject` or `period` required on Encounter	Both are 0..1 (optional). Only `status` and `class` are required
Using CodeableConcept for `Encounter.class`	`class` uses Coding directly: `{"system": "...", "code": "AMB"}`
Returning 400 for ETag mismatch	Use `412 Precondition Failed` for If-Match failures
Returning 400 for invalid enum values	Use `422 Unprocessable Entity` for validation errors
Forgetting Content-Type header	Always set `Content-Type: application/fhir+json`
Missing Location header on create	Return `Location: /Patient/{id}` with 201 Created

Resource Structures

For complete JSON examples of all resources, see references/resource-examples.md.

Quick reference for error responses:

{
  "resourceType": "OperationOutcome",
  "issue": [{"severity": "error", "code": "not-found", "diagnostics": "Patient/123 not found"}]
}

RESTful Endpoints

POST   /[ResourceType]              # Create (returns 201 + Location header)
GET    /[ResourceType]/[id]         # Read
PUT    /[ResourceType]/[id]         # Update
DELETE /[ResourceType]/[id]         # Delete (returns 204)
GET    /[ResourceType]?param=value  # Search (returns Bundle)
GET    /metadata                    # CapabilityStatement
POST   /                            # Bundle transaction/batch

Conditional Operations

If-Match (optimistic locking):

Client sends: If-Match: W/"1"
Mismatch returns 412 Precondition Failed

If-None-Exist (conditional create):

Client sends: If-None-Exist: identifier=http://mrn|12345
Match exists: return existing (200)
No match: create new (201)

Reference Files

For detailed guidance, see:

Resource Examples: Complete JSON structures for Patient, Observation, Encounter, Condition, MedicationRequest, OperationOutcome, CapabilityStatement
SMART on FHIR Authorization: OAuth flows, scope syntax (v1/v2), backend services, scope enforcement
Pagination: Search result pagination, _count/_offset parameters, link relations
Bundle Operations: Transaction vs batch semantics, atomicity, processing order

Implementation Checklist

Set Content-Type: application/fhir+json on all responses
Return meta.versionId and meta.lastUpdated on resources
Return Location header on create: /Patient/{id}
Return ETag header: W/"{versionId}"
Use OperationOutcome for all error responses
Validate required fields → 422 for missing
Validate enum values → 422 for invalid
Search returns Bundle with type: "searchset"

Quick Start Script

To scaffold a new FHIR API project with correct Pydantic v2 patterns:

python scripts/setup_fhir_project.py my_fhir_api

Creates a FastAPI project with correct models, OperationOutcome helpers, and Patient CRUD endpoints.

FAQ

What does the fhir-developer-skill skill do?

How do I install fhir-developer-skill?

Run npx skills add https://github.com/anthropics/healthcare --skill fhir-developer-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/fhir-developer-skill/ (personal) or .claude/skills/fhir-developer-skill/ (project).

Which AI agents can use fhir-developer-skill?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is fhir-developer-skill safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains fhir-developer-skill?

It is published by anthropics in anthropics/healthcare, and it is an official skill from the maker of the technology it covers. It has 664 recorded installs.

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs

fhir-developer-skill

Install

Install

Describe the task

Review the result

SKILL.md

FHIR Developer Skill

Quick Reference

HTTP Status Codes

Required Fields by Resource (FHIR R4)

Required vs Optional Fields (CRITICAL)

Value Sets (Enum Values)

Patient.gender

Observation.status

Encounter.status

Encounter.class (Common Codes)

Condition.clinicalStatus

Condition.verificationStatus

MedicationRequest.status

MedicationRequest.intent

Bundle.type

Validation Pattern

Coding Systems (URLs)

Common LOINC Codes (Vital Signs)

Data Type Patterns

Coding (direct) vs CodeableConcept (wrapped)

Reference

Identifier

Common Mistakes

Resource Structures

RESTful Endpoints

Conditional Operations

Reference Files

Implementation Checklist

Quick Start Script

FAQ

More from anthropics/healthcare

Popular backend & apis skills