Firely Terminal: The natural CLI for AI FHIR Workflows

Three things happened recently that, when you put them together, point to something new and helpful in healthcare interoperability tooling.

First, a LinkedIn post caught attention across the FHIR community: Anthropic shipped a FHIR skill for Claude which is a reusable, shareable instruction set that teaches the AI assistant how to think and act like a FHIR expert. Alexander Goel’s team then enriched this skill with deeper FHIR domain knowledge.

Second, a developer essay made the rounds arguing that MCP (Model Context Protocol) is dead and that the humble CLI is actually the killer interface for AI agents because CLIs are stable, composable, and already understood by machines.

Third, Firely published an updated blog post on how to validate FHIR resources properly, covering the landscape of validators, the traps that trip people up, and what “real” conformance checking actually means.

Put those three together and the conclusion writes itself: Firely Terminal is the natural CLI for AI-assisted FHIR workflows. It is a CLI built for humans that turns out to be exactly what AI agents need. With Claude’s skill system, we can now teach Claude to use it correctly, consistently, and in the right order.

This post is about what we built: a /fhir-validation skill for Claude Code, using the Firely Terminal CLI and Java validation, and what happens when you put it to the test on Implementation Guide projects.

What is a Claude skill?

A Claude skill is a reusable instruction file you install into your Claude Code configuration (Anthropic’s CLI for Claude). When you type a command like /fhir-validation, it loads the skill, a structured prompt that tells Claude which tools to use, in which order, and what to watch out for.

Think of it as a runbook that Claude executes on your behalf, but one that adapts to your specific project rather than following a rigid script: if your project uses FSH, it runs SUSHI first; if you have a package.json, it runs fhir restore; if you already have a validator_cli.jar, it uses that instead of fetching a new one. The skill is not a macro, it is a set of expert guidelines that Claude applies with judgment.

The FHIR skill ecosystem is growing. Alexander Goel’s LinkedIn post highlighted that Anthropic had shipped a general FHIR skill, and our /fhir-validation skill builds on that foundation, going deeper into the validation workflow specifically.

The /fhir-validation Skill: what it knows

It knows the validator landscape. Firely Terminal (.NET-based), the HL7 Java Validator, and Python fhir.resources (schema-only, no profile checking). The skill knows when to use each, and recommends running both profile-aware validators to cross-check results.

It knows the right order of operations. fhir restore before validating (or you get spurious “unknown profile” errors). sushi build before validating FSH projects. fhir check before falling back to the fhir validate loop. These sequencing mistakes are the most common source of false errors.

It knows where to fix things. When a validation error points to fsh-generated/resources/StructureDefinition-MyProfile.json, the skill traces it back to the .fsh source file, because fsh-generated/ is wiped on every build. It finds the right file, makes the fix there, and rebuilds before revalidating.

It knows the Firely Terminal CLI. The skill carries the details to find the full command reference: every flag, every parameter. It will not hallucinate a –recursive flag that doesn’t exist.

It knows CI/CD. Validation can be automated with the FirelyTeam/firely-terminal-pipeline GitHub Action, and the skill knows how to set that up.

Putting it to the test

I downloaded/cloned the following projects into a local directory and ran /fhir-validation on it:

• A Firely Sample IG, with Simplifier compatible Implementation Guide, containing a mix of everything: .fsh files, resources, logical models, etc
• A nl-core package with only profiles and examples
• The Generic Functions for data exchange Implementation Guide that uses FSH and IG publisher built on top of nl-core amongst others

Running /fhir-validation

When I typed /fhir-validation validate resources in this repo in Claude IDE Chat, here is what happened:

Claude made an assessment first:

1. Claude checked for .NET SDK, Java and Firely Terminal which are all present for my machine
2. Found the Java validator_cli.jar in the input_cache folder
3. It found no sushi-config.yaml or .fsh files
4. It found no .rules.yaml file with custom business rules to check
5. Made an overview of the dependencies and resources it found

For the Firely Sample IG report, where I first asked to fhir-validate check resources to validate, it produced a very comprehensive overview and validation review plan.

Validation results

Then the Claude agent is off to do the heavy lifting. This may take a while depending on the size of the project and the number of resources. It runs the validators in the right order, parses the output, and reports back with a summary of errors and suggestions for fixes.

Here are two examples of the output it produced: one for the Firely Sample IG and the other for a nictiz.fhir.nl.r4.zib2020 package containing only conformance resources and examples, in which I had added an incorrect web-source extension for testing purposes. It found the error and reported back with the right error message and its source.

Remarks

The skill helps a lot in focusing the agent on the job at hand. However, it can take a while, so it helps to have deterministic validation processes in place. While investigating how to best set up a derived slicing structure in the Generic Function IG that is in development, I noticed that the agent can drift and propose fixes that are not correct.

I was trying to fix slicing issues flagged as instance examples matched against both slices. The agent took a very long time, even with additional guidance, to find the right source of the error and propose a solution, likely spending quite a few AI credits in the process.

For now, I am going to use this skill on an occasional basis. When starting a new project, I run it to get an overview and fix all the obvious errors before diving into the details. It is a great way to get a quick health check of your project and catch things you might miss with a single validator.

Next, I let the skill help me set up deterministic validation rules for the project, so I can run it more frequently and get faster feedback on changes.

Distilling QA business rules and adding CI/CD automated validation

With the fhir check command you can also execute custom business rules based on FHIRPath expressions and other features. The skill can help you distill those business rules from the resources in your project and create a custom rules.yaml file that you can use for validation. This way you can automate checks that are specific to your project and get even more value out of the validation process.

For example:

> /fhir-validation can you distill business rules from the resources to populate a custom rules.yaml for them?

It read about two files per resource type and created rules from them.

Another way to use the skill is to set up a CI/CD pipeline with the FirelyTeam/firely-terminal-pipeline GitHub Action. The skill can help you create the workflow file, configure the validation steps, and integrate it with your repository.

This way you can ensure that every change to your project is validated automatically, and you get feedback on errors as soon as they are introduced.

Why this matters

FHIR validation is genuinely tedious work. It requires familiarity with multiple tools, careful sequencing, and enough experience to tell a real conformance error from a setup problem. In practice, most implementers only run one validator, even though running two in parallel has become straightforward and catches things a single tool misses.

When errors do surface, the output can be cryptic enough that fixing them takes longer than finding them. That is where having an AI agent in the loop changes things. When the skill is loaded, Claude already knows the tools, the order of operations, and the common failure modes. It can read validation output, trace an error back to its source, explain what went wrong, and suggest a fix. The slow parts get fast.

The broader point connects back to the MCP-is-dead argument. The best AI integrations are not always the most technically elaborate ones. A well-designed CLI that produces predictable, readable output turns out to be exactly what an AI agent needs, because it composes cleanly with everything else in the workflow. Firely Terminal was already doing the right things. The skill just made it accessible to Claude.

A note that this post focused on validation as one example of what that looks like in practice. As the skill ecosystem grows, the same approach applies to other FHIR workflows.

Getting the Skill

The /fhir-validation skill is available as part of the FirelyTeam skills repository.

To use it, install it into your Claude Code configuration and type /fhir-validation in any FHIR project directory. Claude will assess your project, select the right validators, and run them in the correct order.

If you try the skill and run into something it handles badly, or something it handles well that surprised you, we would love to hear about it.

Note: Firely Terminal is free to use, and everything covered in this post works on the free tier. There are paid features that make some parts of the workflow faster, but if those are not available, the free tier will get you to the same result.