NetworkSim - Provider Network Intelligence & Analytics Skill

NetworkSim - Provider Network Intelligence & Analytics

Overview

NetworkSim queries real NPPES provider data (8.9M records), CMS facility data (60K+ facilities), and quality metrics. Unlike synthetic generation, it uses actual registered providers to enable:

Provider Discovery: Search by specialty, location, credentials, quality
Network Analysis: Assess adequacy against CMS MA, NCQA, Medicaid standards
Healthcare Access: Identify deserts via access gaps, health needs, vulnerability
Cross-Product Integration: Provide real providers for PatientSim, MemberSim, TrialSim

Quick Reference

| I want to... | Use This Skill | Key Triggers | |--------------|----------------|--------------| | Provider Search | | | | Find providers by specialty | query/provider-search.md | "find cardiologists", "search for PCPs", "providers in" | | Search hospitals/facilities | query/facility-search.md | "hospitals in", "find nursing homes", "clinics near" | | Find pharmacies | query/pharmacy-search.md | "pharmacies in", "retail pharmacy", "specialty pharmacy" | | Validation & Roster | | | | Validate an NPI | query/npi-validation.md | "is NPI valid", "validate NPI", "check NPI" | | Generate network roster | query/network-roster.md | "create roster", "export providers", "network list" | | Density & Coverage | | | | Calculate provider density | query/provider-density.md | "providers per 100K", "density analysis", "HRSA benchmark" | | Assess network coverage | query/coverage-analysis.md | "network coverage", "geographic coverage", "specialty gaps" | | Quality Metrics | | | | Filter by hospital quality | query/hospital-quality-search.md | "4-star hospitals", "high quality", "CMS ratings" | | Filter by physician credentials | query/physician-quality-search.md | "MD only", "board certified", "credentials" | | Advanced Analytics | | | | Assess network adequacy | analytics/network-adequacy-analysis.md | "adequacy assessment", "CMS standards", "NCQA requirements" | | Identify healthcare deserts | analytics/healthcare-deserts.md | "healthcare deserts", "underserved areas", "access gaps" | | Synthetic Generation | | | | Generate synthetic provider | synthetic/synthetic-provider.md | "generate a provider", "create physician" | | Generate synthetic facility | synthetic/synthetic-facility.md | "generate hospital", "create facility" | | Generate synthetic pharmacy | synthetic/synthetic-pharmacy.md | "generate pharmacy", "create pharmacy" | | Generate synthetic network | synthetic/synthetic-network.md | "generate network", "create provider network" | | Generate synthetic plan | synthetic/synthetic-plan.md | "generate plan", "create health plan" | | Integration | | | | Assign provider to encounter | integration/provider-for-encounter.md | "provider for patient", "attending physician" | | Determine network status | integration/network-for-member.md | "in-network check", "network status" | | Route prescription | integration/pharmacy-for-rx.md | "pharmacy for prescription", "dispense at" |

Trigger Phrases

Provider/Facility: "find [specialty] in [location]", "hospitals in [state]", "nursing homes near", "pharmacies in"
Validation/Roster: "validate NPI", "is NPI valid", "create roster", "export providers"
Density/Coverage: "providers per 100K", "density in [county]", "HRSA benchmark"
Quality: "4-star hospitals", "MD/DO only", "board certified"
Adequacy: "CMS adequacy standards", "NCQA coverage", "provider ratio", "time/distance"
Deserts/Access: "healthcare deserts", "underserved counties", "access gaps", "shortage areas"

Skill Inventory

Query Skills (9 skills)

| Skill | File | Lines | Purpose | |-------|------|-------|---------| | Provider Search | query/provider-search.md | 450 | Search 8.9M providers by specialty, location | | Facility Search | query/facility-search.md | 380 | Search hospitals, nursing homes, clinics | | Pharmacy Search | query/pharmacy-search.md | 320 | Search retail, specialty, mail pharmacies | | NPI Validation | query/npi-validation.md | 280 | Validate NPIs with Luhn checksums | | Network Roster | query/network-roster.md | 350 | Generate rosters in CSV/JSON/Excel | | Provider Density | query/provider-density.md | 400 | Calculate density vs HRSA benchmarks | | Coverage Analysis | query/coverage-analysis.md | 380 | Assess geographic/specialty coverage | | Hospital Quality | query/hospital-quality-search.md | 320 | Filter by CMS star ratings | | Physician Quality | query/physician-quality-search.md | 290 | Filter by credentials (MD/DO/NP/PA) |

Analytics Skills (2 skills)

| Skill | File | Lines | Purpose | |-------|------|-------|---------| | Network Adequacy | analytics/network-adequacy-analysis.md | 653 | CMS/NCQA regulatory compliance | | Healthcare Deserts | analytics/healthcare-deserts.md | 757 | Access + health needs + vulnerability |

Synthetic Skills (6 skills)

| Skill | File | Lines | Purpose | |-------|------|-------|---------| | Synthetic Provider | synthetic/synthetic-provider.md | 400 | Generate providers with valid NPI format | | Synthetic Facility | synthetic/synthetic-facility.md | 350 | Generate hospitals, ASCs, clinics | | Synthetic Pharmacy | synthetic/synthetic-pharmacy.md | 320 | Generate pharmacies with NCPDP IDs | | Synthetic Network | synthetic/synthetic-network.md | 450 | Generate complete network configurations | | Synthetic Plan | synthetic/synthetic-plan.md | 380 | Generate health plan structures | | Synthetic Pharmacy Benefit | synthetic/synthetic-pharmacy-benefit.md | 350 | Generate PBM configurations |

Integration Skills (5 skills)

| Skill | File | Lines | Purpose | |-------|------|-------|---------| | Provider for Encounter | integration/provider-for-encounter.md | 280 | Assign providers to PatientSim | | Network for Member | integration/network-for-member.md | 300 | Network status for MemberSim | | Pharmacy for Rx | integration/pharmacy-for-rx.md | 260 | Pharmacy routing for RxMemberSim | | Formulary for Rx | integration/formulary-for-rx.md | 290 | Formulary checks for RxMemberSim | | Benefit for Claim | integration/benefit-for-claim.md | 270 | Benefit lookup for MemberSim |

Reference Skills (7 skills)

| Skill | File | Purpose | |-------|------|---------| | Network Types | reference/network-types.md | HMO, PPO, EPO, POS structures | | Plan Structures | reference/plan-structures.md | Cost sharing, benefit design | | Pharmacy Benefits | reference/pharmacy-benefit-concepts.md | PBM, formulary, tiers | | Network Adequacy | reference/network-adequacy.md | CMS/NCQA standards | | PBM Operations | reference/pbm-operations.md | Claims processing, rebates | | Specialty Pharmacy | reference/specialty-pharmacy.md | Limited distribution, hubs | | Utilization Management | reference/utilization-management.md | PA, step therapy, QL |

Pattern Skills (5 skills)

| Skill | File | Purpose | |-------|------|---------| | HMO Network | patterns/hmo-network-pattern.md | Closed network, gatekeeper model | | PPO Network | patterns/ppo-network-pattern.md | Open access, tiered cost sharing | | Tiered Network | patterns/tiered-network-pattern.md | Quality-based tier assignment | | Specialty Distribution | patterns/specialty-distribution-pattern.md | Specialty mix by geography | | Pharmacy Benefit | patterns/pharmacy-benefit-patterns.md | PBM network configurations |

Output Types

ProviderSearchResult

Provider records from NPPES database:

{
  "npi": "1234567890",
  "entity_type": "individual",
  "name": {
    "last": "Johnson",
    "first": "Sarah",
    "credential": "MD, FACC"
  },
  "taxonomy": {
    "code": "207RC0000X",
    "classification": "Internal Medicine",
    "specialization": "Cardiovascular Disease"
  },
  "practice_location": {
    "address": "123 Medical Center Dr",
    "city": "Houston",
    "state": "TX",
    "zip": "77030",
    "county_fips": "48201"
  },
  "enumeration_date": "2015-03-15",
  "last_update": "2024-11-01"
}

AdequacyAssessment

Key fields: geography (type, code, name), standard (CMS_MA/NCQA), metrics.pcp_ratio (actual, required, status), metrics.specialist_coverage (13 specialties), overall_status (COMPLIANT/NON_COMPLIANT).

HealthcareDesert

Key fields: geography (fips, county, state), desert_type, severity (critical/high/moderate), scores (access_gap, health_burden, social_vulnerability, composite 0-1), intervention_priority (1=highest).

NetworkRoster

Key fields: roster_id, criteria (specialty, geography, quality_filter), summary (total_providers, by_taxonomy), export_formats (csv, json, xlsx).

Data Sources

Provider Data (network.providers)

| Attribute | Value | |-----------|-------| | Source | NPPES (National Plan and Provider Enumeration System) | | Records | 8,925,672 | | Update Frequency | Monthly CMS releases | | Coverage | All active US healthcare providers with NPIs | | County FIPS | 97.77% coverage (3,213 of 3,286 counties) |

Key Columns: npi, entity_type_code, last_name, first_name, credential, taxonomy_1-4, practice_state, practice_city, practice_zip, county_fips

Additional Tables

| Table | Source | Records | Key Content | |-------|--------|---------|-------------| | network.facilities | CMS POS file | 77,302 | Hospitals (01), SNFs (05), HHAs (07), Hospice (13) | | network.hospital_quality | CMS Hospital Compare | 5,421 | Star ratings (1-5), mortality, readmission, safety | | network.physician_quality | CMS Physician Compare | 1,478,309 | Quality measures, Medicare participation | | network.ahrf_county | HRSA AHRF | 3,235 | Provider counts, hospital beds, health workforce |

Regulatory Standards

See reference/network-adequacy.md for full CMS MA ratios, time/distance tables, NCQA 13 essential specialties, ECP requirements, and HPSA/MUA definitions.

Quick reference:

CMS MA PCP ratio: 1:1,200 enrollees
HRSA HPSA threshold: <60 PCPs per 100K
NCQA requires coverage across 13 specialties
Time/distance varies by urban/suburban/rural designation

Database: healthsim.duckdb (1.7 GB), indexed on county_fips, taxonomy_1, practice_state

Cross-Product Integration

NetworkSim → PatientSim

Assign providers to clinical encounters:

-- Find cardiologist for heart failure patient
SELECT npi, first_name, last_name, credential
FROM network.providers
WHERE taxonomy_1 LIKE '207RC%'  -- Cardiovascular
  AND practice_state = 'TX'
  AND county_fips = '48201'     -- Harris County
LIMIT 1;

NetworkSim → MemberSim

Determine network status for claims:

-- Check if provider is in network
SELECT 
  CASE WHEN p.npi IS NOT NULL THEN 'IN_NETWORK' 
       ELSE 'OUT_OF_NETWORK' END as network_status
FROM network.providers p
WHERE p.npi = '1234567890';

NetworkSim + PopulationSim

Equity analysis combining provider access with vulnerability:

-- Provider access in vulnerable communities
SELECT 
    sv.county,
    sv.rpl_themes as svi_percentile,
    COUNT(DISTINCT p.npi) as provider_count,
    sv.e_totpop as population,
    ROUND(COUNT(DISTINCT p.npi) * 100000.0 / sv.e_totpop, 1) as per_100k
FROM population.svi_county sv
LEFT JOIN network.providers p ON sv.stcnty = p.county_fips
WHERE sv.rpl_themes > 0.75  -- Most vulnerable quartile
GROUP BY sv.county, sv.rpl_themes, sv.e_totpop
ORDER BY per_100k ASC;

Safety Guardrails

Real Data Disclaimer

NetworkSim queries real NPPES registry data (public CMS data, non-PHI). Every NPI is a real registered provider. Results reflect registry status only -- not accepting-patients, insurance participation, or clinical competence.

What NetworkSim Does NOT Do

No clinical advice: Never suggest a provider is "best" for a condition
No insurance verification: Network status is simulated, not real-time eligibility
No appointment scheduling: Registry data is not a booking system
No synthetic NPIs in real queries: Use synthetic/ skills only for test data

Code System References

| System | Used For | Example | |--------|----------|---------| | NUCC Taxonomy | Provider specialty classification | 207RC0000X = Cardiovascular Disease | | NPI | Provider identification (Luhn-validated) | 1234567890 | | County FIPS | Geographic scoping | 48201 = Harris County, TX | | CMS Certification Number | Facility identification | POS file facility IDs | | CBSA | Urban/rural classification | Metro, micro, rural designations | | HCPCS | Provider service codes | Level I (CPT) and Level II codes |

Cross-product code systems (via PatientSim/MemberSim/RxMemberSim integration): ICD-10 (diagnoses), CPT (procedures), LOINC (labs), SNOMED (clinical terms), RxNorm/NDC (medications). These are real standard codes -- linked patient data is synthetic/fictional.

Edge Cases

Missing county_fips: ~2.2% of records lack county FIPS; filter with WHERE county_fips IS NOT NULL for geographic queries
Deactivated NPIs: Check npi_deactivation_date IS NULL for active providers
Multi-taxonomy providers: Up to 15 taxonomies; taxonomy_1 is primary but check taxonomy_2-taxonomy_4 for dual-specialty searches
Organization vs Individual: entity_type_code = 1 (individual) vs 2 (organization); filter appropriately

Negative Examples (What NOT to Do)

Never give clinical advice based on provider data:

WRONG: "I recommend Dr. Smith for your heart condition" or "The patient needs a cardiologist"
RIGHT: "Here are cardiologists registered in Harris County per NPPES data. This is simulated test data for analytics, not a referral."

Always distinguish real reference data from synthetic/fictional entities:

WRONG: "Here is the patient's real provider" (implies real clinical relationship)
RIGHT: "NPI data is from the real NPPES registry (public CMS data). Patient/encounter data is synthetic/fictional -- not real patient information."

Never mix synthetic and real data without labeling:

WRONG: Return synthetic NPIs alongside real NPPES query results
RIGHT: Label synthetic providers (from synthetic/ skills) vs real providers (from network.providers)

Agent Skills: NetworkSim - Provider Network Intelligence & Analytics

Install this agent skill to your local

Skill Files