Icd10 Cpt Coding Assistant

Automatically recommend ICD-10 diagnosis codes and CPT procedure codes from clinical notes. Trigger when: user provides clinical notes, patient encounter sum...

Security Scan

The skill is internally coherent for recommending ICD-10 and CPT codes from clinical notes — its files, README, and runtime instructions match its stated purpose — but you should review the included script for network or file-exfiltration behavior before use because it executes code locally on note files.

Purpose & Capability

Name/description match the packaged assets: SKILL.md documents ICD-10/CPT recommendations and the repository includes main.py plus multiple code/mapping/guideline reference files consistent with that purpose. No unrelated credentials, binaries, or odd install steps are requested.

Instruction Scope

Runtime instructions tell the agent/user to run scripts/main.py on an input clinical-note file and to write output; that behavior is appropriate for the stated purpose. However the instructions accept arbitrary input file paths (no enforced sandboxing is shown) and rely on the implementer/user to de-identify PHI. The SKILL.md contains a security checklist (mentions path validation/prompt injection protections) but does not show that those protections are implemented. I could not fully verify what scripts/main.py actually does from the SKILL.md alone.

Install Mechanism

No install spec or remote downloads are present (instruction-only skill plus packaged Python script and local reference files). Dependencies are declared in requirements.txt (small file present) — no high-risk external install URLs or extract steps in the registry metadata.

Credentials

The skill requests no environment variables, no credentials, and no config paths. That is proportionate for a local coding assistant. There are no hidden credential requirements declared in SKILL.md.

Persistence & Privilege

Flags show always:false and normal model invocation behavior. The skill does not request elevated or permanent presence and does not declare modifications to other skills or system-wide settings.

Assessment

This package appears to be what it claims: a local ICD-10/CPT recommendation tool. Before installing/using it in a production or PHI-containing environment: 1) Open and review scripts/main.py to confirm it performs no network calls, telemetry, or unexpected subprocess execution; 2) Inspect requirements.txt to verify third‑party libraries are trustworthy and up-to-date; 3) Test with de-identified or synthetic clinical notes first; 4) Verify the script validates input paths (no ../ traversal) and enforces sandboxed output locations; 5) Prefer to run inside a restricted environment (container/sandbox) and have all outputs audited by a qualified coder — the SKILL.md itself reminds users that human review is required. If you want, provide the contents of scripts/main.py and requirements.txt and I will review them for network I/O, credential usage, or other red flags (that would raise my confidence level).

A medical coding assistant that parses clinical notes and recommends appropriate ICD-10 diagnosis codes and CPT procedure codes with confidence scoring.

Overview

This skill analyzes clinical documentation to extract relevant medical information and map it to standardized coding systems:

• ICD-10-CM: International Classification of Diseases, 10th Revision, Clinical Modification (diagnosis codes)
• CPT: Current Procedural Terminology (procedure/service codes)

Technical Difficulty: HIGH ⚠️

⚠️ HUMAN REVIEW REQUIRED: Medical coding directly impacts billing, reimbursement, and clinical documentation. All recommendations must be verified by a certified medical coder or healthcare provider.

Usage

python scripts/main.py --input "clinical_note.txt" [--format json|text]

Or use programmatically:

from scripts.main import CodingAssistant

assistant = CodingAssistant()
result = assistant.analyze("Patient presents with acute bronchitis...")
print(result.icd10_codes)
print(result.cpt_codes)

Parameters

Parameter	Type	Default	Required	Description
--input, -i	string	-	Yes	Path to clinical note file
--format, -f	string	json	No	Output format (json, text)
--output, -o	string	stdout	No	Output file path
--confidence-threshold	float	0.7	No	Minimum confidence score (0.0-1.0)
--include-alternatives	flag	false	No	Include alternative code suggestions

Input Format

Accepts clinical notes in various formats:

• Free-text narrative
• SOAP notes (Subjective, Objective, Assessment, Plan)
• Discharge summaries
• Progress notes
• Procedure reports

Output Format

ICD-10 Recommendations

{
  "icd10_codes": [
    {
      "code": "J20.9",
      "description": "Acute bronchitis, unspecified",
      "confidence": 0.92,
      "evidence": ["cough for 5 days", "wheezing on exam"],
      "alternatives": ["J20.0", "J44.9"]
    }
  ]
}

CPT Recommendations

{
  "cpt_codes": [
    {
      "code": "99213",
      "description": "Office visit, established patient, moderate complexity",
      "confidence": 0.85,
      "evidence": ["detailed history", "low complexity decision making"],
      "time": "20 minutes"
    }
  ]
}

Confidence Scoring

• 0.90-1.00: High confidence - Clear documentation, unambiguous mapping
• 0.70-0.89: Medium confidence - Good documentation, some interpretation required
• 0.50-0.69: Low confidence - Incomplete documentation, multiple possibilities
• <0.50: Very low confidence - Insufficient information, manual review essential

Limitations

1. No Medical Advice: This tool does not provide clinical advice or diagnoses
2. Coding Complexity: Cannot handle all coding nuances (comorbidities, sequencing, modifiers)
3. Regional Variations: May not account for payer-specific coding requirements
4. Updates: Code sets may not reflect the latest annual updates

References

See references/ folder for:

• icd10_common_codes.json: Frequently used ICD-10 codes by specialty
• cpt_common_codes.json: Frequently used CPT codes by specialty
• coding_guidelines.md: General coding guidelines and conventions

Safety & Compliance

• HIPAA Awareness: Ensure de-identification of PHI before processing
• Audit Trail: Maintain records of automated recommendations for compliance
• Human Oversight: All codes must be reviewed and approved by qualified personnel

Dependencies

• Python 3.8+
• See requirements.txt for package dependencies

Risk Assessment

Risk Indicator	Assessment	Level
Code Execution	Python/R scripts executed locally	Medium
Network Access	No external API calls	Low
File System Access	Read input files, write output files	Medium
Instruction Tampering	Standard prompt guidelines	Low
Data Exposure	Output files saved to workspace	Low

Security Checklist

• No hardcoded credentials or API keys
• No unauthorized file system access (../)
• Output does not expose sensitive information
• Prompt injection protections in place
• Input file paths validated (no ../ traversal)
• Output directory restricted to workspace
• Script execution in sandboxed environment
• Error messages sanitized (no stack traces exposed)
• Dependencies audited

Prerequisites

# Python dependencies
pip install -r requirements.txt

Evaluation Criteria

Success Metrics

• Successfully executes main functionality
• Output meets quality standards
• Handles edge cases gracefully
• Performance is acceptable

Test Cases

1. Basic Functionality: Standard input → Expected output
2. Edge Case: Invalid input → Graceful error handling
3. Performance: Large dataset → Acceptable processing time

Lifecycle Status

• Current Stage: Draft
• Next Review Date: 2026-03-06
• Known Issues: None
• Planned Improvements:
  • Performance optimization
  • Additional feature support