nimbleway/agent-skills/healthcare-providers-verify

Healthcare Providers Verify

Validate practitioner credentials against the NPI registry and authoritative sources, powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).

Instructions

Step 0: Preflight + WSA Discovery

Sibling handoff check: Before running full preflight, check if healthcare-providers-extract or healthcare-providers-enrich ran earlier in this session by following the Sibling Handoff pattern from references/nimble-playbook.md. If same-day output exists, skip CLI check and profile load, and reuse WSA Layer 1/3 inventory. Only re-run Layer 2 if the verification focus changed.

Otherwise, run full preflight from references/nimble-playbook.md (5 simultaneous Bash calls: date calc, today, CLI check, profile load, index.md load).

Also simultaneously — run WSA discovery and setup:

• mkdir -p ~/.nimble/memory/{reports,healthcare-providers-verify/checkpoints}
• ls ~/.nimble/memory/healthcare-providers-verify/checkpoints/ 2>/dev/null
• Run Layer 1 (vertical) and Layer 3 (general tools) WSA discovery from

references/wsa-reference.md. Layer 2 (session-specific) runs after Step 1 when you know the user's specialty and verification focus.

Classify discovered agents into verification categories and validate with nimble extract:templates get per references/wsa-reference.md.

From the preflight results:

• CLI missing or API key unset -> references/profile-and-onboarding.md, stop
• Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
• Profile exists -> note it for context. Determine mode using smart date windowing

from references/nimble-playbook.md:

• Full mode: first run OR last run > 14 days ago
• Quick refresh: last run < 14 days ago (re-verify only previously

Unverified/Flagged practitioners)

• Same-day repeat: if last_runs.healthcare-providers-verify is today, check

for existing report at ~/.nimble/memory/reports/healthcare-providers-verify-*[today].md. If found, ask: "Already ran today. Run again for fresh data?"

• No profile -> that's fine. This skill doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Input + Starting Questions

Chained-from-sibling shortcut: Check for same-day extract or enrich output:

ls ~/.nimble/memory/reports/healthcare-providers-extract-*$(date +%Y-%m-%d).md 2>/dev/null
ls ~/.nimble/memory/reports/healthcare-providers-enrich-*$(date +%Y-%m-%d).md 2>/dev/null

If a same-day report exists, parse the {slug} and load the provider data (providers.json or enriched.json). This gives you names, credentials, specialties, and locations — skip parsing and go directly to Step 2.

Parse $ARGUMENTS for input type using the Input Parsing Pattern from references/nimble-playbook.md. Key routing:

• Sibling output detected (providers.json/enriched.json) -> proceed to Step 2
• CSV/Sheet/pasted data detected -> proceed to Step 2
• Unclear -> ask (counts as 1 of max 2 prompts)

If input is clear, confirm and ask one shaping question (plain text, not AskUserQuestion):

"Found N practitioners to verify. Quick questions:

1. What should I verify? (credentials, specialty, active status, practice address — or all)

2. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)"

If input is ambiguous, use AskUserQuestion (counts as 1 of max 2 prompts):

What practitioner data should I verify?

- Paste provider data directly (name + credentials + location, one per line)

- Provide a CSV file path or Google Sheet URL

- Or describe what you have (e.g., "a list of 50 ophthalmologists I need to

verify against the NPI registry")

Skip questions the user already answered in their initial message.

Step 2: Analyze Input Data

Parse the input into structured records. For each practitioner, identify:

• Claimed fields — name, credentials, specialty, state/city, practice name
• Verification targets — which claims to check based on user's focus

Minimum required fields: Name + at least one of (credentials, state, specialty). If a practitioner has only a name with no other identifiers, flag it: "Cannot verify [name] — need at least a state, credential, or specialty to search."

Build a verification plan summary:

"Analyzing N practitioners for verification:

- Names: N/N present

- Credentials claimed: N/N

- Specialty claimed: N/N

- State/location: N/N

Starting NPI verification..."

Run Layer 2 WSA discovery now that you know the specialty:

nimble extract:templates list --limit 50  # filter items for "[specialty]"
nimble extract:templates list --limit 50  # filter items for "[registry-user-mentioned]"

See references/wsa-reference.md for session-specific discovery.

Step 3: NPI Registry Lookup

Prefer the NPPES API — it returns structured JSON in one call instead of search + extract (two calls). Build the query URL from the practitioner's fields:

nimble extract --url "https://npiregistry.cms.hhs.gov/api/?version=2.1&first_name=[First]&last_name=[Last]&state=[ST]&limit=5" --format markdown

Add &taxonomy_description=[Specialty] if the specialty is known and specific enough. The API returns NPI number, status, credentials, taxonomy codes, addresses, and enumeration dates — everything needed for verification in a single call.

Fallback to web search if the NPPES API returns zero results or errors:

nimble search --query "[Name] [Credential] [State] NPI registry" --max-results 5 --search-depth lite

Then extract the top result from an NPI source (see source priority below).

Source priority (enforce in sub-agent prompts):

1. NPPES API (npiregistry.cms.hhs.gov/api/) — preferred, structured JSON
2. npidb.org/doctors/ — clean structured data, good fallback
3. nppes.cms.hhs.gov (provider-view pages) — official CMS source
4. Skip all others (healthline, hmedata, vitals, etc.) — inconsistent formatting

Tell sub-agents: "Only extract from NPPES API, npidb.org, or nppes.cms.hhs.gov. Ignore other NPI aggregator sites."

Search budget per provider: Max 3 search queries + 1 extraction per practitioner. If no NPI match after 3 attempts, mark as Unverified and move on. Tell sub-agents: "Do not run more than 4 nimble commands per provider. Mark as Unverified if no match by then."

For 10+ practitioners, use sub-agents (see Sub-Agent Strategy below).

Key fields from NPI records — see references/npi-verification-patterns.md for the full list: NPI number, status, credentials, taxonomy/specialty, enumeration date, last updated, practice address.

Checkpoint enforcement: After each sub-agent returns its batch results, the main context MUST write the checkpoint before spawning the next step or presenting results:

1. Receive sub-agent results
2. Write checkpoint: echo '[results]' > ~/.nimble/memory/healthcare-providers-verify/checkpoints/{slug}/batch-{n}.json
3. Continue to next step

Do NOT skip this — if the run fails between steps, the user loses all progress.

Step 4: Cross-Reference and Verify

For each practitioner, compare claimed data against extracted NPI data. Follow the verification logic in references/npi-verification-patterns.md:

1. Name matching — normalize both names and determine match level (Strong,

Likely, Weak, No Match) per the name matching rules in the reference

1. Credential matching — compare claimed credentials against NPI record
2. Specialty matching — compare claimed specialty against NPI taxonomy using

the taxonomy matching strategy in the reference

1. Address matching — compare claimed state/city against NPI practice address
2. Status check — verify NPI status is Active

Assign verification status per practitioner based on the totality of evidence:

• Verified — all claims match NPI record
• Partially Verified — NPI found, minor discrepancies
• Unverified — no NPI match found or unable to disambiguate
• Flagged — active mismatches requiring human review

See references/npi-verification-patterns.md for the detailed criteria for each status and the mismatch severity levels (Critical vs Warning).

Step 5: WSA Supplementary Verification (Optional)

If the user requested regulatory verification beyond NPI lookup, or if Step 5 left practitioners as Unverified that might benefit from additional sources:

Run verification-phase WSAs discovered in Step 0. See references/wsa-reference.md for the verification phase mapping, agent evaluation, and fallback chains.

Practice confirmation: For Unverified practitioners, try confirming their practice exists via practice-level WSAs or web search:

nimble search --query "[practice-name] [city] [state]" --max-results 5 --search-depth lite

Regulatory verification: For practitioners the user wants regulatory checks on:

nimble search --query "[name] [credentials] clinical trials OR FDA OR board certification" --max-results 5 --search-depth lite

Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication pattern from references/nimble-playbook.md. Skill-specific dedup rules are in references/provider-extraction-patterns.md.

NPI dedup check: After all sub-agents return, scan for duplicate NPI numbers across batches. If two different providers mapped to the same NPI, flag both as "Flagged — possible NPI collision, requires human review." This catches data entry errors and name confusion in the source provider list.

Verification-specific scoring: The verification status (Verified / Partially Verified / Unverified / Flagged) replaces confidence scoring for this skill. Each status includes a confidence qualifier:

• High confidence — 2+ NPI sources corroborate, strong name match
• Medium confidence — single NPI source, likely name match
• Low confidence — weak name match, partial field matches

Step 7: Output

Present results as a verification report — showing status per practitioner with specific mismatch details. Group by verification status, include a "What This Means" section at the end.

# Provider Verification: [N] Practitioners Checked
*[Date] | [V] Verified, [PV] Partially Verified, [U] Unverified, [F] Flagged*
 
## TL;DR
Verified [V] of [T] practitioners against the NPI registry. [F] flagged for
review: [brief description of critical issues]. [U] could not be verified —
[common reason].
 
## Verification Results
 
| # | Name | Claimed | NPI Status | Verification | Issues | Source |
|---|------|---------|------------|-------------|--------|--------|
| 1 | Dr. Jane Smith | MD, Retinal Surgery, TX | Active (NPI 1234567890) | Verified | — | [NPI](url) |
| 2 | Dr. John Doe | OD, Ophthalmology, CA | Active (NPI 0987654321) | Partially Verified | Subspecialty differs | [NPI](url) |
| 3 | Dr. Alex Chen | MD, Dentistry, NY | Not Found | Unverified | No NPI match | [NPPES query](api-url) |
| 4 | Dr. Pat Lee | DO, Cardiology, FL | Deactivated | Flagged | NPI deactivated 2024-01 | [NPI](url) |
 
## Flagged Practitioners (Requires Human Review)
 
### Dr. Pat Lee
**Claimed:** DO, Cardiology, FL
**NPI Record:** NPI 1122334455 — **Deactivated** (01/15/2024)
**Issues:**
-CRITICAL: NPI status is Deactivated since January 2024
-Credential matches (DO confirmed)
-Specialty matches (Cardiovascular Disease taxonomy)
**Source:** [NPI Record](url)
**Action needed:** Confirm if provider has re-registered or if this is a
different individual.
 
[Repeat per flagged practitioner]
 
## Unverified Practitioners
 
[List practitioners where no NPI match was found, with search queries attempted]