Source: https://github.com/aipoch/medical-research-skills
Medical Unit Converter
Convert laboratory values between clinical units with formula transparency and reference range context. Supports glucose, cholesterol, creatinine, and hemoglobin.
When to Use
- Converting glucose, cholesterol, creatinine, or hemoglobin lab values between unit systems
- Verifying unit conversions for clinical documentation or research
- Batch-converting lab result tables between mg/dL and mmol/L conventions
- Providing reference ranges alongside converted values
Workflow
- Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.
- Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.
- Use the packaged script path or the documented reasoning path with only the inputs that are actually available.
- Return a structured result that separates assumptions, deliverables, risks, and unresolved items.
- If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
Supported Conversions
| Analyte |
From |
To |
Factor |
Reference Range (target unit) |
| Glucose |
mg/dL |
mmol/L |
0.0555 |
3.9–5.6 mmol/L (fasting) |
| Glucose |
mmol/L |
mg/dL |
18.018 |
70–100 mg/dL (fasting) |
| Cholesterol |
mg/dL |
mmol/L |
0.02586 |
< 5.2 mmol/L (desirable) |
| Cholesterol |
mmol/L |
mg/dL |
38.67 |
< 200 mg/dL (desirable) |
| Creatinine |
mg/dL |
μmol/L |
88.4 |
62–115 μmol/L (male) |
| Creatinine |
μmol/L |
mg/dL |
0.01131 |
0.7–1.3 mg/dL (male) |
| Hemoglobin |
g/dL |
g/L |
10 |
130–175 g/L (male) |
| Hemoglobin |
g/L |
g/dL |
0.1 |
13–17.5 g/dL (male) |
Input Parameters
| Parameter |
Type |
Required |
Description |
--value, -v |
float |
Yes |
Numeric value to convert |
--from-unit |
str |
Yes |
Source unit (e.g., mg_dl, mmol_l, umol_l, g_dl, g_l) |
--to-unit |
str |
Yes |
Target unit |
--analyte, -a |
str |
No |
Analyte name for reference range lookup (e.g., glucose, cholesterol, creatinine, hemoglobin) |
Output Format
{
"converted_value": 5.55,
"formula": "100 × 0.0555",
"from_unit": "mg_dl",
"to_unit": "mmol_l",
"analyte": "glucose",
"reference_range": "3.9–5.6 mmol/L (fasting glucose)"
}
Quick Check
python -m py_compile scripts/main.py
python scripts/main.py --value 100 --from-unit mg_dl --to-unit mmol_l --analyte glucose
Implementation Notes (for script developer)
The script must:
- Parse CLI args — use argparse with
--value, --from-unit, --to-unit, --analyte. Pass parsed args to conv.convert(). Do not hardcode demo values in main().
- CONVERSIONS dict — include all 8 conversion pairs above, each with
factor and reference_range fields. Keys must be (analyte, from_unit, to_unit) tuples or equivalent nested structure.
- convert() method — return a dict with
converted_value, formula, from_unit, to_unit, analyte, reference_range.
- Unsupported pair — if the unit pair is not in CONVERSIONS, print the supported conversions list and exit with code 1.
- Fallback Partial result — when an unsupported unit pair is requested, always populate the
Partial result field in the Fallback Template with: "Manual formula not available for this unit pair".
Input Validation
This skill accepts: numeric laboratory values with a source unit and target unit for conversion between recognized clinical measurement systems.
If the request does not involve converting a specific numeric lab value between units — for example, asking to interpret clinical results, diagnose conditions, or convert non-laboratory quantities — do not proceed. Instead respond:
"medical-unit-converter is designed to convert medical laboratory values between unit systems. Your request appears to be outside this scope. Please provide a numeric value with source and target units, or use a more appropriate tool for your task."
Error Handling
- If
--value, --from-unit, or --to-unit is missing, state exactly which fields are missing and request only those.
- If the unit pair is not supported, list the supported conversions and stop.
- If
--value is not a valid number, reject with: Error: --value must be a numeric value.
- If the task goes outside the documented scope, stop instead of guessing or silently widening the assignment.
- If
scripts/main.py fails, report the failure point and provide the manual conversion formula as fallback.
- Do not fabricate conversion factors or reference ranges.
Fallback Template
When execution fails or inputs are incomplete, respond with this structure:
FALLBACK REPORT
───────────────────────────────────────
Objective : [restate the conversion goal]
Blocked by : [exact missing input or error]
Partial result : [manual formula if conversion factor is known; "Manual formula not available for this unit pair" if unsupported]
Next step : [minimum action needed to unblock]
───────────────────────────────────────
Response Template
- Objective
- Inputs Received
- Assumptions
- Workflow
- Deliverable
- Risks and Limits
- Next Checks
Prerequisites
No additional Python packages required beyond the standard library.
1---2name: medical-unit-converter3description: Convert medical laboratory values between units (mg/dL to mmol/L, etc.) with formula transparency and clinical reference ranges. Supports glucose, cholesterol, creatinine, and hemoglobin conversions.4license: MIT5---6> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
7
8# Medical Unit Converter
9
10Convert laboratory values between clinical units with formula transparency and reference range context. Supports glucose, cholesterol, creatinine, and hemoglobin.
11
12## When to Use
13
14- Converting glucose, cholesterol, creatinine, or hemoglobin lab values between unit systems
15- Verifying unit conversions for clinical documentation or research
16- Batch-converting lab result tables between mg/dL and mmol/L conventions
17- Providing reference ranges alongside converted values
18
19## Workflow
20
211. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.
222. Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.
233. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.
244. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.
255. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
26
27## Supported Conversions
28
29| Analyte | From | To | Factor | Reference Range (target unit) |
30|---------|------|----|--------|-------------------------------|
31| Glucose | mg/dL | mmol/L | 0.0555 | 3.9–5.6 mmol/L (fasting) |
32| Glucose | mmol/L | mg/dL | 18.018 | 70–100 mg/dL (fasting) |
33| Cholesterol | mg/dL | mmol/L | 0.02586 | < 5.2 mmol/L (desirable) |
34| Cholesterol | mmol/L | mg/dL | 38.67 | < 200 mg/dL (desirable) |
35| Creatinine | mg/dL | μmol/L | 88.4 | 62–115 μmol/L (male) |
36| Creatinine | μmol/L | mg/dL | 0.01131 | 0.7–1.3 mg/dL (male) |
37| Hemoglobin | g/dL | g/L | 10 | 130–175 g/L (male) |
38| Hemoglobin | g/L | g/dL | 0.1 | 13–17.5 g/dL (male) |
39
40## Input Parameters
41
42| Parameter | Type | Required | Description |
43|-----------|------|----------|-------------|
44| `--value`, `-v` | float | Yes | Numeric value to convert |
45| `--from-unit` | str | Yes | Source unit (e.g., `mg_dl`, `mmol_l`, `umol_l`, `g_dl`, `g_l`) |
46| `--to-unit` | str | Yes | Target unit |
47| `--analyte`, `-a` | str | No | Analyte name for reference range lookup (e.g., `glucose`, `cholesterol`, `creatinine`, `hemoglobin`) |
48
49## Output Format
50
51```json
52{
53 "converted_value": 5.55,
54 "formula": "100 × 0.0555",
55 "from_unit": "mg_dl",
56 "to_unit": "mmol_l",
57 "analyte": "glucose",
58 "reference_range": "3.9–5.6 mmol/L (fasting glucose)"
59}
60```
61
62## Quick Check
63
64```bash
65python -m py_compile scripts/main.py
66python scripts/main.py --value 100 --from-unit mg_dl --to-unit mmol_l --analyte glucose
67```
68
69## Implementation Notes (for script developer)
70
71The script must:
72
731. **Parse CLI args** — use argparse with `--value`, `--from-unit`, `--to-unit`, `--analyte`. Pass parsed args to `conv.convert()`. Do not hardcode demo values in `main()`.
742. **CONVERSIONS dict** — include all 8 conversion pairs above, each with `factor` and `reference_range` fields. Keys must be `(analyte, from_unit, to_unit)` tuples or equivalent nested structure.
753. **convert() method** — return a dict with `converted_value`, `formula`, `from_unit`, `to_unit`, `analyte`, `reference_range`.
764. **Unsupported pair** — if the unit pair is not in CONVERSIONS, print the supported conversions list and exit with code 1.
775. **Fallback Partial result** — when an unsupported unit pair is requested, always populate the `Partial result` field in the Fallback Template with: `"Manual formula not available for this unit pair"`.
78
79## Input Validation
80
81This skill accepts: numeric laboratory values with a source unit and target unit for conversion between recognized clinical measurement systems.
82
83If the request does not involve converting a specific numeric lab value between units — for example, asking to interpret clinical results, diagnose conditions, or convert non-laboratory quantities — do not proceed. Instead respond:
84
85> "medical-unit-converter is designed to convert medical laboratory values between unit systems. Your request appears to be outside this scope. Please provide a numeric value with source and target units, or use a more appropriate tool for your task."
86
87## Error Handling
88
89- If `--value`, `--from-unit`, or `--to-unit` is missing, state exactly which fields are missing and request only those.
90- If the unit pair is not supported, list the supported conversions and stop.
91- If `--value` is not a valid number, reject with: `Error: --value must be a numeric value.`
92- If the task goes outside the documented scope, stop instead of guessing or silently widening the assignment.
93- If `scripts/main.py` fails, report the failure point and provide the manual conversion formula as fallback.
94- Do not fabricate conversion factors or reference ranges.
95
96## Fallback Template
97
98When execution fails or inputs are incomplete, respond with this structure:
99
100```
101FALLBACK REPORT
102───────────────────────────────────────
103Objective : [restate the conversion goal]
104Blocked by : [exact missing input or error]
105Partial result : [manual formula if conversion factor is known; "Manual formula not available for this unit pair" if unsupported]
106Next step : [minimum action needed to unblock]
107───────────────────────────────────────
108```
109
110## Response Template
111
1121. Objective
1132. Inputs Received
1143. Assumptions
1154. Workflow
1165. Deliverable
1176. Risks and Limits
1187. Next Checks
119
120## Prerequisites
121
122No additional Python packages required beyond the standard library.
gabrielmoreira