Skip to content

The FHIR Frog Skill

The FHIR Frog skill is an AI agent skill for Claude and Kiro that teaches the assistant how to use the FHIR Frog MCP tools. This page explains what the skill does, how it is structured, and how to keep it up to date.

What is a skill?

A skill is a document that teaches an AI agent how to perform a specific domain task. The FHIR Frog skill lives in skill/fhir-frog/SKILL.md and is loaded whenever Claude or Kiro connects to the MCP server.

The skill:

  1. Defines the persona: Who is the user (IG developer, system tester)?
  2. Teaches the workflow: What sequence of tools should be called?
  3. Documents traps: Where do the published docs disagree with real behaviour?
  4. Sets constraints: What safety rules must always apply?

Skill structure

The FHIR Frog skill has four main sections:

1. Overview (first step, every session)

Always call frog_doctor first. It reports:

  • Docker status (is it running?)
  • Java version (v17+?)
  • Port availability (are the ports free?)
  • FHIR packages cache (do we have packages?)
  • Authoring tools (sushi, fpl, IG Publisher)

If frog_doctor reports fail, stop and ask the user to fix the issue before proceeding.

2. Two personas and their workflows

IG developer (author tests, wire builds, publish):

  1. Choose layout (Test IG or IG with tests)
  2. Author tests in TSH or JSON TestScript
  3. Validate early and often (frog_tsh_validate, frog_testscript_lint)
  4. Check the IG (frog_check_ig)
  5. Wire the build (Maven/Ant integration)
  6. (v0.2+) Publish the Test IG

System tester (run tests, diagnose failures):

  1. Register or start a server
  2. Get test files (from workspace or a Test IG package)
  3. Run tests (frog_run_local or frog_run_remote)
  4. Understand failures (frog_report_summarise)
  5. (v0.2+) Export results, compare runs

3. Known traps (doc conflicts)

The published docs sometimes disagree with real behaviour:

Trap Reality Fix
TSH syntax on website Not the real grammar; use references/tsh-cheatsheet.md Validate with frog_tsh_validate
.tsh files are runnable They compile to JSON; the runtime runs JSON only Compile with frog_tsh_compile
CLI reports are detailed They are stubs (no per-assertion detail) Use MCP tools instead
Runner API is /api It is /api/v1 Use tools; they know the right path
Test IGs are published They are only in the runner image or exports Use frog_package_install
read Patient/123 works It fails client-side with HTTP 400 Use search Patient instead

4. Error codes and fixes

When a tool returns an error, act on the error code:

  • needs_confirmation: Not an error; show the plan and ask
  • docker_unavailable: Start Docker or check the socket
  • network_error: Check the runner is running and the URL is correct
  • package_not_found: Install the package with frog_package_install
  • timeout: Retry or increase the timeout

See references/troubleshooting.md for all codes and fixes.

Reference documents

The skill knows about these reference documents:

Document Contents
references/tsh-cheatsheet.md TSH grammar as it really is (not the website version)
references/testscript-json.md JSON TestScript syntax that actually runs
references/testplan-cheatsheet.md TestPlan format (v0.2+)
references/server-specs.md backends.yaml, server-specs, auth config
references/runner-and-docker.md Local runner, SUT, Docker setup, macOS notes
references/test-ig-publishing.md Test IG build, version, publish checklist
references/troubleshooting.md Error codes to causes to fixes
examples/workflow-ig-developer.md Worked example: scaffold, author, validate
examples/workflow-system-tester.md Worked example: register, run, read results

When you need specific technical information, the assistant loads these documents instead of guessing.

Tool availability by release

The skill tracks which tools exist in each release:

Release Tools added
v0.1 Core tools: doctor, scaffold, compile, validate, lint, run, server management
v0.2 Advanced: testplan, fixtures, publish, export, compare, ci
v0.3 Future: migrate, render, matrix

If a tool is missing, the skill tells the user which release will provide it.

Safety rules (always)

  1. Ask before confirm=true.
    Show the plan first; get explicit approval before performing side effects.

  2. Dry-run before publish.
    frog_test_ig_publish (planned, v0.2) will default to dry_run=true; real publish will need both dry_run=false and confirm=true, each only after the user says yes.

  3. No secrets in arguments.
    Auth is configured through ${ENV_VAR} references; the user sets environment variables themselves.

  4. Stay in the workspace.
    All paths are relative to FROG_WORKSPACE; if a path is rejected, ask the user for one inside the workspace instead.

How to update the skill

New tool in a release

When a tool is added to FHIR Frog, update the skill:

  1. Add the tool name and description to the tool list
  2. Update the "Tool availability by release" table
  3. Update the relevant workflow (IG developer or system tester)
  4. Add any new traps to the "Known traps" table

Example (tool added in v0.2):

| v0.2 | `frog_generate_from_ig`, `frog_fixture_validate`, `frog_test_ig_publish` |

New reference document

When a reference document is written (e.g. a new guide or troubleshooting page), add it to the "Reference documents" table:

| `references/ci-snippets.md` | GitLab and GitHub CI configuration examples |

Known trap discovered

When a user finds a real trap (doc vs. reality mismatch), add it to the table:

| Trap | TSH `in` operator keeps only first code | Compiled JSON ignores codes after the first | Use `validateProfile` instead for multiple codes |

Structure of SKILL.md

The file is organized like this:

---
name: fhir-frog
description: (agent-facing overview)
license: Apache-2.0
compatibility: (version and Docker requirements)
metadata:
  version: "0.1"
  source: fhirfrog/fhir-frog-mcp
  audience: IG developers, system testers, terminologists
---

# FHIR Frog

(Intro and two principles)

## First step, every session

(Always call frog_doctor)

## Safety rules (always)

(Confirm, dry-run, secrets, workspace)

## Who is the user? Pick a workflow

(Table of personas and links)

## IG developer workflow

(Tool sequence with explanations)

## System tester workflow

(Tool sequence with explanations)

## Known traps

(Table of doc conflicts)

## Release availability

(Tool inventory by release)

## Reference files

(Table of reference documents)

## What not to do

(Antipatterns and mistakes)

Version pinning

The skill is versioned with the MCP release:

  • Skill version: matches MCP_VERSION in the build
  • Reference docs: updated alongside the skill
  • Tool inventory: auto-generated from the live registry

When you release a new MCP version, update skill/fhir-frog/SKILL.md and the reference documents, then release together.

Integration with Claude Desktop and Kiro

When Claude or Kiro starts with the MCP server:

  1. The agent receives the tools/list (all available tools)
  2. The agent loads SKILL.md from the skill directory
  3. The skill teaches the agent which tools to call and in what order

If the skill is missing or out of date, the agent is less helpful (it will not know about traps or the recommended workflows).

See also

For the full FHIR Frog skill document and workflow examples, see the skill/fhir-frog/ directory in the fhir-frog-mcp repository.