CQF Skills

Open source Agent Skills for working with CQL, FHIR, FHIR Clinical Reasoning, and FHIR content Implementation Guides, maintained by the Clinical Quality Framework community.

Skills are folders of instructions, references, and scripts that an AI agent loads on demand when a task calls for them. These skills teach agents to author, review, test, and package clinical knowledge artifacts (CQL libraries, measures, PlanDefinitions, and the IGs that publish them) using the conventions of the HL7 and CQF specifications and tooling.

The skills follow the open Agent Skills format, so they work in Claude Code, Claude.ai, the Claude API, and other agents that support SKILL.md.

Status: early development. Skills are being brought in from other repositories one at a time.

Skills are grouped into plugins by domain (cql, fhir, clinical-reasoning, fhir-ig), so you can install only the ones you need. Some plugins are maintained in their own repositories and listed here so they can be installed from one marketplace.

This repository is a Claude Code plugin marketplace.

/plugin marketplace add cqframework/cqf-skills
/plugin install cql@cqf-skills
/plugin install fhir@cqf-skills
/plugin install clinical-reasoning@cqf-skills
/plugin install cql-mcp@cqf-skills

To pick up new releases, run /plugin marketplace update cqf-skills.

Installing cql-mcp installs its skill and registers the cql-mcp server, with the workspace set to the project directory you start Claude Code from. The server needs Node.js 22+ and a JDK 17+. On first use it downloads the server package and the CQL language server, so the first start can be slow. If you already registered cql-mcp yourself with claude mcp add, remove that registration to avoid running two servers.

Each folder under skills/ is self-contained. Copy or symlink the ones you want into your agent's skills directory, for example:

git clone https://github.com/cqframework/cqf-skills.git
cp -r cqf-skills/skills/cql ~/.claude/skills/        # Claude Code (personal)
cp -r cqf-skills/skills/cql .claude/skills/          # Claude Code (project)
cp -r cqf-skills/skills/cql .agents/skills/          # agents that use .agents/skills

Check your agent's documentation for the exact location it reads skills from.

Plugins maintained elsewhere aren't under skills/. For cql-mcp, set up the server for your client by following the cql-mcp install guide, and get the skill from the cql-mcp-skill.zip attached to each cql-mcp release.

Zip a skill folder (the zip must contain the folder itself, not just its contents). Then upload it under Settings → Capabilities → Skills on Claude.ai, or through the Skills API. Each release attaches prebuilt zips.

cqf-skills/
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace: defines plugins as groups of skills
├── skills/                     # One folder per skill; the folder name is the skill name
│   └── <skill-name>/
│       ├── SKILL.md            # Required: YAML frontmatter + instructions
│       ├── references/         # Optional: detail loaded only when needed
│       ├── scripts/            # Optional: deterministic helpers the agent runs
│       └── assets/             # Optional: templates and files copied into output
├── evals/                      # Evaluation cases per skill (not shipped with the skill)
│   └── <skill-name>/
├── template/
│   └── SKILL.md                # Starting point for new skills
├── scripts/
│   └── validate_skills.py      # Lint: frontmatter, naming, marketplace consistency
├── .github/workflows/
│   └── validate.yml            # CI: runs the validator on every PR
├── AGENTS.md                   # Instructions for agents contributing to this repo
├── CONTRIBUTING.md             # Authoring guidelines and review checklist
├── CHANGELOG.md
└── LICENSE                     # Apache-2.0

Skills sit in a single flat skills/ directory rather than nested under plugins. This keeps every skill installable on its own with any Agent Skills–compatible tool. The plugin groupings live only in marketplace.json.

---
name: cql-authoring
description: Writes and reviews CQL libraries targeting FHIR, following CQL
  authoring conventions. Use when creating or editing .cql files, defining
  retrieves, value set and code declarations, or measure population criteria.
license: Apache-2.0
---

# CQL Authoring

## Workflow
1. ...

## References
- For the FHIRHelpers and QICore model conventions, see [references/models.md](references/models.md).

• name: lowercase letters, digits, and hyphens; at most 64 characters; must match the folder name.
• description: at most 1024 characters, written in the third person. It must say what the skill does and when to use it. Agents decide whether to load a skill from its description alone.
• Body: keep it under about 500 lines. Move detail into references/ and link to it one level deep, so the agent loads it only when it needs it (progressive disclosure).

See CONTRIBUTING.md for the full authoring guidelines.

1. Specification-grounded. Guidance follows the published HL7 specifications (CQL, Using CQL with FHIR, CRMI, CPG, Quality Measures, SDC). Skills link to the canonical spec rather than copying it, and note which version they target.
2. Teach what the model doesn't already know. Skip general FHIR or programming background. Focus on conventions, pitfalls, tooling behavior, and decision points.
3. Tooling-aware, not tooling-locked. Prefer the CQF reference tooling (the CQL translator, the Clinical Reasoning engine, and the IG Publisher). Keep the guidance usable without any particular agent or IDE.
4. Deterministic where possible. When a step can be scripted (validation, translation, packaging), ship a script instead of prose.
5. Self-contained. A skill must not reference files outside its own folder, because each skill can be installed on its own.
6. Evaluated. Every skill ships with eval cases under evals/<skill-name>/ that show it improves agent results on realistic tasks.
7. No PHI. Examples and test data must be synthetic.

Contributions are welcome, especially from implementers with hands-on CQL, measure, and IG experience. Read CONTRIBUTING.md, start from template/SKILL.md, and run the validator before you open a PR:

pip install pyyaml
python scripts/validate_skills.py

To propose a new skill, open an issue that describes the tasks it should handle and two or three example prompts.

• cqframework/clinical_quality_language: CQL specification tooling, translator, and engine
• cqframework/clinical-reasoning: FHIR Clinical Reasoning operations (measure evaluation, $apply, $package)
• cqframework/vscode-cql: CQL support for VS Code
• MeasureAuthoringTool: MADiE, the CMS Measure Authoring Development Integrated Environment

Apache License 2.0. Unless otherwise noted, each skill is also licensed under Apache-2.0, as declared in its SKILL.md frontmatter.

HL7®, FHIR®, and the FHIR flame logo are registered trademarks of Health Level Seven International.