extracting-sdoh

Extracts social determinants of health (SDOH) — housing instability, food insecurity, unemployment, transportation barriers, social isolation, financial strain — from clinical narrative and maps the spans to ICD-10-CM Z-codes (Z55–Z65). Use after running OpenMed NER when the user wants SDOH surfacing, Z-code suggestion, health-equity analytics, or to recover SDOH that is documented in free text but not coded. Pairs with OpenMed analyze_text output. Standards: ICD-10-CM Z55–Z65, Gravity Project value sets, n2c2 2022 SDOH track. Trigger keywords: SDOH, social determinants, Z-codes, housing, food insecurity, health equity, Gravity Project.

Quality

93%

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

86%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.

A well-structured, actionable skill body with executable code, a clearly sequenced workflow that includes a human-confirmation checkpoint, and proper progressive disclosure to a real reference file. The only notable weakness is mild motivational padding in the opening paragraph.

Suggestions

Trim the opening paragraph's SDOH definition and motivational statistics ('80% of health outcomes', '~2% coded') to a single sentence so the body leads with the task, not the rationale.

Tighten the workflow by making the validation feedback loop explicit (e.g., 'If negation/temporality resolution rejects a span, drop it and re-map remaining spans') rather than relying on the separate Edge cases section.

Consider moving the Z-code families table into references/sdoh_zcode_map.md alongside the full lookup, keeping only a one-line pointer in the body to further reduce duplicate content.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with executable quick-start code and tight workflow steps, but the opening paragraph explains what SDOH are ('the conditions in which people live, work, and age') and includes motivational statistics ('80% of health outcomes', '~2%') that could be trimmed; not a 5 because not every token earns its place.	4 / 5
Actionability	Quick-start provides copy-paste-ready, executable Python (openmed.deidentify, analyze_text, span→Z-code mapping) with the entity output shape documented, and the workflow gives concrete function names and label lists covering the common cases.	5 / 5
Workflow Clarity	Five clearly sequenced steps with an explicit human-confirmation checkpoint ('Stage for confirmation... Do not auto-bill') and edge-case error guidance (negation, hypotheticals), but it is a hand-off rather than a validate→fix→retry loop, so it falls short of the checklist/feedback-loop anchor.	4 / 5
Progressive Disclosure	Clear overview sections with the heavy label→code lookup offloaded to a real, self-contained, one-level-deep reference (references/sdoh_zcode_map.md) that is explicitly linked; navigation is easy and content is appropriately split.	5 / 5
	Total	18 / 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.

A highly specific, third-person description that explicitly answers both what and when, lists concrete actions and domains, and provides a rich set of natural trigger keywords. It is concise yet comprehensive with minimal conflict risk.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('Extracts social determinants of health', 'maps the spans to ICD-10-CM Z-codes') and enumerates six specific SDOH domains plus the Z55–Z65 range, giving comprehensive coverage.	5 / 5
Completeness	Clearly states what ('Extracts... maps the spans to ICD-10-CM Z-codes') and an explicit when ('Use after running OpenMed NER when the user wants SDOH surfacing, Z-code suggestion, health-equity analytics, or to recover SDOH... not coded') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Explicit 'Trigger keywords: SDOH, social determinants, Z-codes, housing, food insecurity, health equity, Gravity Project' plus synonyms (SDOH / social determinants) and natural phrases users would say; file extensions are N/A for this domain.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (SDOH extraction + Z-code mapping paired with OpenMed NER) with distinct triggers and standards references, minimizing overlap with other 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/extracting-sdoh/SKILL.md
Commit: 80da98c

Reviewed: about 24 hours 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.