coding-hcc-risk-adjustment

Maps chronic conditions extracted by OpenMed to CMS-HCC V28 risk-adjustment categories and estimates a RAF (Risk Adjustment Factor) score as decision support. Use when the user wants to surface risk-adjustable diagnoses from notes, map ICD-10-CM codes to HCC categories, estimate or reconcile a patient/panel RAF, find suspected-but-undocumented HCCs, or check MEAT documentation support. Trigger keywords: HCC, CMS-HCC, V28, RAF score, risk adjustment, Medicare Advantage, hierarchical condition category, MEAT, recapture, suspect HCC, RADV. Pairs after OpenMed NER + ICD-10 coding: consume Disease/Pathology entities from openmed.analyze_text, code them (see coding-icd10), then roll up to HCCs. CMS-HCC mappings and weights are public from CMS. This is a coding-support aid for human review, never autonomous risk-adjustment coding.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is well-structured and actionable with executable code, a clear sequenced workflow, and strong compliance guardrails. Its main weaknesses are minor: a little framing prose that could be tightened and a couple of illustrative/placeholder code segments rather than fully wired ones.

Suggestions

Tighten the intro prose ('CMS pays Medicare Advantage plans based on RAF, so accurate, documented capture...') to the essential decision-support framing, trimming context Claude already knows.

Make the hierarchy example concrete — either load the official V28 hierarchy file in the snippet or point to the specific CMS file path — instead of leaving an empty illustrative dict.

Show how demo_factor is obtained (a one-line read from the CMS demographic table) so the RAF estimate is end-to-end executable.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with executable code and clear sections and avoids explaining basic concepts Claude already knows, but a few framing sentences ('CMS pays Medicare Advantage plans based on RAF...') are mildly explanatory and could be trimmed. It is noticeably above the 'mostly efficient with some unnecessary explanation' anchor but not perfectly lean.	4 / 5
Actionability	Two complete, executable Python blocks (crosswalk loading, estimate_raf, OpenMed hand-off) plus concrete CMS URLs give mostly copy-paste-ready guidance; minor gaps are the illustrative empty hierarchy dict and the un-coded demo_factor sourcing.	4 / 5
Workflow Clarity	A clear 7-step numbered sequence with an explicit validation checkpoint (step 6: no MEAT → flag as unsupported) and compliance guardrails ('never autonomous coding'); not a full validate→fix→retry feedback loop, so it sits just below the top anchor.	4 / 5
Progressive Disclosure	Single-file skill with no bundle directories and well-organized section headers; references are external CMS URLs (one level) rather than nested skill files. It is well-structured but, at ~165 lines, is denser than the simple-skill case that would score 5, so it sits just below the top anchor.	4 / 5
	Total	16 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is exemplary: it states concrete capabilities, gives explicit 'Use when...' triggers with natural keywords, and carves out a distinct niche with strong disambiguation. It also adds useful boundary framing (pairs-after OpenMed, never autonomous coding) without padding.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — mapping conditions to V28 HCC categories, estimating RAF, surfacing risk-adjustable diagnoses, mapping ICD-10-CM to HCC, finding suspected-but-undocumented HCCs, and checking MEAT support — giving comprehensive coverage of capabilities.	5 / 5
Completeness	Explicitly answers both 'what' (maps chronic conditions to HCCs and estimates RAF) and 'when' via a concrete 'Use when the user wants to...' clause with specific trigger phrases.	5 / 5
Trigger Term Quality	Provides extensive natural keywords a user would actually say — 'HCC, CMS-HCC, V28, RAF score, risk adjustment, Medicare Advantage, hierarchical condition category, MEAT, recapture, suspect HCC, RADV' — including synonyms and abbreviations.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche — CMS-HCC V28 risk adjustment with MEAT/RADV terminology — whose triggers are distinct and unlikely to fire for unrelated skills.	5 / 5
	Total	20 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: maziyarpanahi/openmed
Path: skills/coding-hcc-risk-adjustment/SKILL.md
Commit: 80da98c

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.