macOS / Linux:

curl -fsSL https://gitlab.com/tomgriffin/juliette/-/raw/main/install-remote.sh | sh

Windows (PowerShell):

irm https://gitlab.com/tomgriffin/juliette/-/raw/main/install-remote.ps1 | iex

---

Juliette is a Claude plugin for healthcare actuaries, value-based care strategists, financial modelers, health economists, ACO operators, and managed care analytics architects working on New York. It combines authoritative NYS Medicaid and CMS reference data with a live-data layer (eight MCP servers) and 23 domain skills that turn it all into actuarial deliverables.

What's inside

• 23 skills organized into 7 domain categories spanning VBP design and attestation, MA bid development, risk adjustment, Stars/QARR quality analytics, SPARCS hospital benchmarking, Medicaid enrollment, MLTC, HRSN ROI, DRG pricing, rebasing strategy, MCO rate setting, SCN coordination, full ACO/IPA management, a 262-term glossary, plain- language translation, memory persistence, and guided onboarding.
• 8 live-data MCP servers wrapping public APIs from NYSDOH, CMS, Census, NPPES, NLM VSAC, FDA, and CDC.
• Authoritative NYSDOH 2026 reference PDFs for the VBP Roadmap and seven measure sets.
• 49+ bundled CSV / PDF reference files covering rate cells, measure sets, MCO and provider rosters, geography crosswalks, risk adjustment factor tables, ACO governance, distribution methodology, behavioral health crisis continuum, maternal mortality review, cancer registry, and HRSN/SDOH context.
• Eval harness with 15 test cases covering skill routing, refusal behavior, and output accuracy.

Skill directory

Skills are organized by domain under skills/:

entry/ — Onboarding and cross-cutting

Skill	Purpose
start-here	Absolute first entry point for new users; 30-second intro
juliette-orientation	Full discovery flow and routing matrix to downstream skills
juliette-memory	Persist user profile, book of business, and preferences across sessions; integrates with claude.ai chat memory
glossary	262-term lookup across 44 categories (NY VBP, federal Medicare, ACO, MLTC, quality, risk adjustment, HRSN, contracting, compliance, analytics)
plain-language	Translate actuarial output for CFOs, boards, trustees, and members

data-layer/ — Data routing

Skill	Purpose
data-sources	Single source of truth; routes every data request between 8 MCP servers, bundled CSVs, and external fetches

vbp-contracting/ — VBP and contracting

Skill	Purpose
vbp-modeling	Design and evaluate NYS Medicaid VBP arrangements (TCGP, HARP, Maternity, Children's, HIV/AIDS, MLTC); produces 26-tab financial model + term sheet
vbp-attestation	DOH-4255 packets and actuarial certification for NYSDOH submission
rebasing-and-trend	Multi-year VBP economics, target rebasing methodology, ratchet-down protection

federal-medicare/ — Federal Medicare

Skill	Purpose
ma-bid-rate-dev	Medicare Advantage bid build, county benchmarks, Star bonus economics, rebate share, Part D bid
risk-adjustment	CMS-HCC V28 (100% phase-in PY2026) RAF projection, transition impact, RADV exposure

quality-pophealth/ — Quality and population health

Skill	Purpose
quality-stars-qarr	CMS Star Ratings and NYS QARR/eQARR analytics; Tukey-aware cut-point projection
sparcs-benchmarking	NY hospital inpatient and ED benchmarking, severity-adjusted unit cost
medicaid-enrollment	County and plan-level enrollment forecasting, redetermination modeling
scn-coordination	Social Care Networks, HRSN screening cadence, April 2027 SCN-as-VBP transition
hrsn-roi	Health-Related Social Needs intervention ROI modeling

mco-provider-ops/ — MCO and provider operations

Skill	Purpose
mco-rate-setting	NYSDOH MMC capitation rate review, adequacy, formal comment letters
mltc-modeling	Managed Long-Term Care, PACE, MAP, FIDA, D-SNP economics
drg-pricing	APR-DRG hospital VBP payment modeling, case-rate proposals

aco-ipa/ — ACO and IPA management

Skill	Purpose
aco-formation	Entity selection, governance, network composition, regulatory pre-clearance
aco-distribution-design	Shared savings methodology selection, distribution waterfall modeling
aco-program-portfolio	Multi-program portfolio management (MSSP, REACH, MA delegated, NYS VBP, commercial)
aco-care-coordination-economics	Staffing model, intervention ROI ranking, sustainability test

MCP servers (live data)

Each MCP gives every skill on-demand access to a public API without manual fetches.

• NY Health Data wraps health.data.ny.gov. Pulls QARR plan performance (2008–) and health-disparities stratification; full SPARCS suite — row-level inpatient PUFs (2009–2024), IQI, PSI, PPR (readmissions), PPC (complications), PQI (adult, by zip), PDI (pediatric, by county and zip), PPV (avoidable ED, by county and zip), cost transparency by APR-DRG, and acute stroke mortality; MLTC plan performance (2014–); ED encounters by facility; Medicaid and CHPlus enrollment; managed care plan profiles; NY hospital roster; BRFSS; and vital statistics. Requires SOCRATA_APP_TOKEN (SODA v3 endpoints).
• Medicaid Data wraps data.medicaid.gov. Pulls TAF demographic, state drug utilization, federal MMC enrollment, Adult/Child Core Set quality, and 1115 waiver documents.
• CMS Data wraps data.cms.gov. Pulls Medicare Part B and Part D utilization by NPI, Hospital Care Compare, HCRIS hospital cost reports, Medicare Advantage enrollment by contract, Provider of Services, and Medicare Spending Per Beneficiary.
• Census Data wraps api.census.gov. Pulls ACS 5-year demographics, Subject tables (insurance, poverty), Data Profiles, Population Estimates, SAHIE uninsured rates, and SAIPE poverty estimates.
• NPPES wraps the CMS NPI registry. Lookup individual NPIs and search providers by name, taxonomy, or location.
• VSAC wraps the NLM Value Set Authority Center. Pulls HEDIS and CMS eCQM value sets with full ICD-10 / CPT / HCPCS / SNOMED / RxNorm code expansion (UMLS API key required).
• OpenFDA wraps api.fda.gov. Pulls drug labels, NDC details, drug shortages, recalls, and FAERS adverse event summaries.
• CDC PLACES wraps chronicdata.cdc.gov. Pulls PLACES county and tract chronic-disease prevalence, SDOH measures, BRFSS state-level estimates, and Social Vulnerability Index.

Installation

One-line install (recommended)

macOS / Linux:

curl -fsSL https://gitlab.com/tomgriffin/juliette/-/raw/main/install-remote.sh | sh

Windows (PowerShell):

irm https://gitlab.com/tomgriffin/juliette/-/raw/main/install-remote.ps1 | iex

This clones the repo to ~/juliette, creates a Python venv at ~/.juliette/venv, installs MCP server dependencies, and prompts for optional API keys. Re-running the command updates an existing installation.

Manual install

If you prefer to clone manually or to a custom location:

git clone https://gitlab.com/tomgriffin/juliette.git
cd juliette
./install.sh          # macOS / Linux
# .\install.ps1       # Windows (PowerShell)

After install

Add this to your shell profile so API keys load automatically:

macOS / Linux (~/.zshrc, ~/.bashrc, etc.):

[ -f ~/.juliette/env ] && source ~/.juliette/env

Windows (PowerShell $PROFILE):

if (Test-Path "$env:USERPROFILE\.juliette\env.ps1") { . "$env:USERPROFILE\.juliette\env.ps1" }

Then follow one of the usage methods below.

Claude Code CLI

Open Claude Code from the cloned repo directory:

cd juliette
claude

Claude Code auto-discovers the plugin via .claude-plugin/plugin.json, loads all 23 skills from skills/, and registers the 8 MCP servers defined in .mcp.json.

You can also load Juliette from any directory using the --plugin-dir flag:

claude --plugin-dir /path/to/juliette

Claude desktop app

The desktop app uses MCP servers for live data but does not load plugin skills directly. To add Juliette's 8 MCP servers to the desktop app:

1. Clone the repo and run the installer (see Quick install above).

2. In the Claude desktop app, go to Settings > Developer > Edit Config to open claude_desktop_config.json.

3. Copy the contents of juliette-desktop-config.json from the cloned repo into the mcpServers object in your desktop config file. The installer auto-generates this file with your actual paths and API keys — no manual editing needed.

4. Restart the Claude desktop app.

MCP server requirements

The MCP servers require Python 3.10+ and two pip packages. The installer handles this automatically. For manual setup:

python3 -m venv ~/.juliette/venv
~/.juliette/venv/bin/pip install -r mcp_servers/requirements.txt

Each MCP server is a standalone Python FastMCP script that Claude launches automatically when a skill requests live data. The servers use whichever python3 is on your PATH — if you installed via install.sh, they use the venv Python at ~/.juliette/venv/bin/python3.

API keys (optional)

All 8 MCP servers work without API keys at default public rate limits. Optional keys raise rate limits or unlock features:

Variable	MCPs affected	Notes
SOCRATA_APP_TOKEN	NY Health Data, Medicaid Data, CMS Data, CDC PLACES	Required for NY Health Data (SODA v3). Also raises rate limits for other Socrata MCPs. Get one free at dev.socrata.com/register
CENSUS_API_KEY	Census Data	Raises from 500 req/day. Get one at api.census.gov/data/key_signup.html
UMLS_API_KEY	VSAC	Required for value-set code expansion (ICD-10, CPT, SNOMED, RxNorm). Register at uts.nlm.nih.gov
FDA_API_KEY	OpenFDA	Raises from 40 req/min to 240 req/min

If you used the installer, keys are saved to ~/.juliette/env. Otherwise set them in your shell profile:

export SOCRATA_APP_TOKEN="..."
export CENSUS_API_KEY="..."
export UMLS_API_KEY="..."
export FDA_API_KEY="..."

Verify installation

Start Claude Code in any project and ask:

Juliette — what can you do?

Juliette should greet you with the start-here skill, list example prompts, and offer to route you to a specific workflow. If the MCP servers are working, asking "pull QARR plan performance" should return live data from health.data.ny.gov.

Development setup

Set up pre-commit hooks (validates skill files before each commit):

./hooks/setup.sh

Validation

Run all skill validators:

./scripts/validate.sh

Validate a single skill:

./scripts/validate.sh skills/entry/start-here/SKILL.md

Adding a new skill

1. Create skills/<category>/<skill-name>/SKILL.md
2. Add YAML frontmatter with name and description (description must start with "Use when...")
3. Directory name must match the name field
4. Names use only lowercase letters, numbers, and hyphens
5. Run ./scripts/validate.sh to check before committing

Docs

• docs/who-is-juliette.md — plain-language one-pager for non-technical stakeholders
• docs/skill-graph.svg — visual map of all 23 skills, 8 MCPs, and data flows
• CHANGELOG.md — release history
• KNOWN_LIMITATIONS.md — data currency, licensed data gaps, scope boundaries
• evals/ — test harness with 15 cases and scoring rubric

Versioning

See CHANGELOG.md for full release history. Current version: 1.2.0.