NEVER suggest LOINC or SNOMED CT codes from memory or training data. ALWAYS use the search and query scripts in this skill.
When any clinical code is needed:
python scripts/search_loinc.py "search term" FIRSTpython scripts/search_snomed.py "search term" FIRSTClinical codes from AI memory are highly unreliable and will cause incorrect clinical coding.
Requires whitelisted network access:
clinicaltables.nlm.nih.gov (LOINC search)tx.fhir.org (FHIR terminology server for LOINC answer lists and SNOMED CT search)If network access fails, STOP. Do not suggest codes.
ALWAYS run this before suggesting any LOINC code (clinical questions/observations):
python scripts/search_loinc.py "depression screening"
python scripts/search_loinc.py "blood pressure" --format fhir
ALWAYS run this before suggesting any SNOMED CT code (clinical concepts/conditions):
python scripts/search_snomed.py "diabetes"
python scripts/search_snomed.py "hypertension" --format fhir
python scripts/search_snomed.py "diabetes mellitus" --semantic-tag "disorder"
Note: The --semantic-tag filter works best when the semantic tag appears in the display name (e.g., "Diabetes mellitus (disorder)").
For questions with standardized answers:
python scripts/query_valueset.py --loinc-code "72166-2"
python scripts/query_valueset.py --loinc-code "72166-2" --format fhir
Before finalizing:
python scripts/validate_questionnaire.py questionnaire.json
Start with assets/templates/:
minimal.json - Bare bones structurebasic.json - Simple questionnaireadvanced.json - Complex with conditional logic# Step 1: Find panel code (NEVER skip this)
python scripts/search_loinc.py "PHQ-9 panel"
# Step 2: Find answer options
python scripts/query_valueset.py --loinc-code "FOUND-CODE" --format fhir
# Step 3: See examples/templates
# Check references/examples.md for complete implementations
# Step 1: Start with template
cp assets/templates/advanced.json my-questionnaire.json
# Step 2: For any clinical questions, search LOINC
python scripts/search_loinc.py "body weight"
# Step 3: Add answer options if available
python scripts/query_valueset.py --loinc-code "FOUND-CODE"
# Step 4: For custom questions without LOINC results, use inline answerOptions
# (no coding system needed - just code + display)
# Step 5: Validate
python scripts/validate_questionnaire.py my-questionnaire.json
When LOINC search returns no suitable answer list, use inline answerOption with system-less valueCoding by default. This is the simplest, spec-compliant approach for custom answer lists:
{
"linkId": "sleep-quality",
"type": "choice",
"text": "How would you rate your sleep quality?",
"answerOption": [
{"valueCoding": {"code": "good", "display": "Good"}},
{"valueCoding": {"code": "fair", "display": "Fair"}},
{"valueCoding": {"code": "poor", "display": "Poor"}}
]
}
Do NOT invent a coding system URI. Omitting system is valid FHIR and signals that these are local, questionnaire-scoped codes.
If the user explicitly requests reusable codes that can be shared across questionnaires, use the Welshare namespace (http://codes.welshare.app) via the helper script:
python scripts/create_custom_codesystem.py --interactive
This creates a CodeSystem + ValueSet pair. To convert an inline answer list to the reusable format, add "system": "http://codes.welshare.app/CodeSystem/ to each valueCoding and optionally reference the ValueSet via answerValueSet. See references/loinc_guide.md for details.
enableWhen to show/hide questions"repeats": true for medications, allergies, etc.query_valueset.py --loinc-code "CODE" for LOINC-backed answer listsanswerOption with valueCoding (no system) for non-standardized choicesSee references/examples.md for complete working examples.
python scripts/search_loinc.py "blood pressure"
python scripts/search_loinc.py "depression" --limit 10 --format fhir
python scripts/search_snomed.py "diabetes"
python scripts/search_snomed.py "hypertension" --limit 10 --format fhir
python scripts/search_snomed.py "asthma" --format table
python scripts/search_snomed.py "diabetes mellitus" --semantic-tag "disorder"
Formats: json (default), table, fhir
Semantic tags (when present in results): disorder, finding, procedure, body structure, substance, organism
Note: Semantic tag filtering only works when tags are included in the display name from the terminology server.
python scripts/query_valueset.py --loinc-code "72166-2"
python scripts/query_valueset.py --loinc-code "72166-2" --format fhir
python scripts/query_valueset.py --search "smoking"
Alternative servers (if tx.fhir.org fails):
--server https://hapi.fhir.org/baseR4--server https://r4.ontoserver.csiro.au/fhirpython scripts/validate_questionnaire.py questionnaire.json
python scripts/validate_questionnaire.py questionnaire.json --verbose
python scripts/extract_loinc_codes.py questionnaire.json
python scripts/extract_loinc_codes.py questionnaire.json --validate
python scripts/create_custom_codesystem.py --interactive
Only use when the user explicitly requests reusable codes across questionnaires. Uses the Welshare namespace: http://codes.welshare.app. Default for custom answers is inline answerOption without a coding system.
--server flagreferences/fhir_questionnaire_spec.md for requirementsanswerOption with system-less valueCoding (code + display only). Do NOT fall back to a custom coding system unless the user explicitly requests itWe've assembled deep knowledge for you to consult on specific topics. Checkout the index file on See REFERENCE.md and drill down the knowledge path for highly detailed instructions on modelling questionnaires.
共 1 个版本