ICD-10 Coding Assistant

What it does

When your agent uses it

• Coding a problem list into ICD-10-CM diagnosis codes
• Routing a diagnosis phrase to the correct ICD-10 chapter
• Cross-walking legacy ICD-9 codes with GEMs
• Pre-filling encounter diagnoses for a coder to review

Example prompts

• “Suggest ICD-10-CM codes for type 2 diabetes with diabetic CKD and explain the choice.”
• “Route community-acquired pneumonia to its ICD-10 chapter and show the code range.”
• “Map these ICD-9 codes to ICD-10-CM using GEMs and flag the approximate matches.”
• “Take the diagnoses OpenMed extracted from this note and prepare candidate codes for the coder queue.”

Requirements

• OpenMed for extracting diagnosis and procedure spans
• CMS ICD-10-CM and ICD-10-PCS code files, or access to a FHIR terminology server
• Python with requests for the lookup example

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1Extract diagnosis/procedure spans with OpenMed (Disease/Pathology models).
2. 2Route to a chapter using the span's clinical theme and
3. 3Search the code text (local CMS table or the NLM API) for candidates.
4. 4Apply ICD-10-CM specificity rules in your rationale: laterality,
5. 5Rank candidates; present the top few **with rationale and the missing-
6. 6Emit {system: "http://hl7.org/fhir/sid/icd-10-cm", code, display}

What it can do on your machine

Read from SKILL.md and the folder at commit 252806a. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are python).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • clinicaltables.nlm.nih.gov
  • hl7.org

  Also links to:

  • cms.gov

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

ICD-10 Coding Assistant loads about 2k tokens when it runs, and up to ~2.7k if it reads all its reference files. Until then it costs about 215 tokens; SKILL.md has 610 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~215

When it runs · the whole SKILL.md, loaded when a task matches

~2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from maziyarpanahi/openmed at commit 252806a, republished under its Apache-2.0 licence (© maziyarpanahi). 610 words, ~1,957 tokens.

name

coding-icd10

description

Suggests candidate ICD-10-CM diagnosis codes (and ICD-10-PCS procedure codes) for diagnoses and procedures extracted by OpenMed, with rationale and a human-coder caveat. Use when the user wants to code a problem list, map a diagnosis span to a billable ICD-10-CM code, route a finding to the right chapter, cross-walk ICD-9 via GEMs, or pre-fill an encounter for coder review. Trigger keywords: ICD-10-CM, ICD-10-PCS, diagnosis coding, billable code, GEMs, problem list coding, encounter diagnosis, chapter range, CMS code lookup. references/icd10-chapters.md holds the chapter/section ranges. Pairs after OpenMed NER: consume Disease/Pathology entities from openmed.analyze_text and propose codes a certified coder validates. ICD-10-CM/PCS files are public domain from CMS — no license barrier (unlike CPT, which is restricted and out of scope).

license

Apache-2.0

metadata.project

OpenMed

metadata.category

terminology-coding

metadata.pairs

after

metadata.version

1.0

# CMS publishes the order/addenda file; load the code->description table.
# Columns: code (no dot), description; you insert the dot for display.
icd10cm = {}                       # "E1122" -> "Type 2 diabetes mellitus with diabetic chronic kidney disease"
with open("icd10cm_order_2025.txt", encoding="latin-1") as fh:
    for line in fh:
        code = line[6:13].strip()
        billable = line[14] == "1"     # '1' = valid billable code
        long_desc = line[77:].strip()
        if billable:
            icd10cm[code] = long_desc

def search_local(term: str, limit: int = 5):
    t = term.lower()
    hits = [(c, d) for c, d in icd10cm.items() if t in d.lower()]
    return sorted(hits, key=lambda cd: len(cd[1]))[:limit]

import requests

# NLM Clinical Tables (public, no key) — ICD-10-CM autocomplete/search:
def search_icd10cm(term: str, count: int = 7):
    r = requests.get(
        "https://clinicaltables.nlm.nih.gov/api/icd10cm/v3/search",
        params={"sf": "code,name", "terms": term, "maxList": count}, timeout=10,
    )
    r.raise_for_status()
    _total, codes, _extra, display = r.json()
    return list(zip(codes, [d[1] for d in display]))   # [(code, name), ...]

print(search_icd10cm("type 2 diabetes nephropathy"))

import openmed

note = "Assessment: type 2 diabetes with diabetic nephropathy; CAP."
result = openmed.analyze_text(
    note,
    model_name="disease_detection_superclinical",   # Disease category
    output_format="dict",
)

DX_LABELS = {"DISEASE", "CONDITION", "PATHOLOGY"}
for ent in result["entities"]:
    if ent["label"] in DX_LABELS:
        candidates = search_icd10cm(ent["text"], count=5)
        print(ent["text"], ent["start"], ent["end"],
              f"(conf {ent['confidence']:.2f}) ->", candidates)
        # surface as SUGGESTIONS for a coder — never auto-bill

© maziyarpanahi, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in skills/coding-icd10 of maziyarpanahi/openmed.

• SKILL.md
• references/icd10-chapters.md

Open the folder on GitHubat commit 252806a