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

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 agent get

per

references/wsa-reference.md

From the preflight results:

CLI missing or API key unset ->
```
references/profile-and-onboarding.md
```
, stop
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:

bash

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

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:

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

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:

bash

nimble agent list --limit 50 --search "[specialty]"
nimble agent list --limit 50 --search "[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:

bash

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:

bash

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):

NPPES API (
```
npiregistry.cms.hhs.gov/api/
```
) — preferred, structured JSON
```
npidb.org/doctors/
```
— clean structured data, good fallback
```
nppes.cms.hhs.gov
```
(provider-view pages) — official CMS source
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:

Receive sub-agent results

Write checkpoint:

echo '[results]' > ~/.nimble/memory/healthcare-providers-verify/checkpoints/{slug}/batch-{n}.json

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

Name matching — normalize both names and determine match level (Strong, Likely, Weak, No Match) per the name matching rules in the reference
Credential matching — compare claimed credentials against NPI record
Specialty matching — compare claimed specialty against NPI taxonomy using the taxonomy matching strategy in the reference
Address matching — compare claimed state/city against NPI practice address
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:

bash

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

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

bash

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.

markdown

# 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]

## Verification Summary
- **Verified:** [V] practitioners — all claims confirmed
- **Partially Verified:** [PV] — minor discrepancies noted
- **Unverified:** [U] — no NPI match (common names, missing identifiers)
- **Flagged:** [F] — critical issues requiring review

## Sources
[Clickable URL for every NPI lookup page used, grouped by practitioner]

## What This Means
[Actionable interpretation: which practitioners are safe to include in your
directory, which need follow-up, what the verification rate tells you about
your data quality. Suggest next steps for unverified/flagged records.]

Source links are mandatory. Every verification finding must trace back to a source URL.

Step 8: Save to Memory

Make all Write calls simultaneously:

Report ->

~/.nimble/memory/reports/healthcare-providers-verify-{slug}-{date}.md

Verification data ->

~/.nimble/memory/healthcare-providers-verify/{slug}/verified.json

Profile -> update

last_runs.healthcare-providers-verify

~/.nimble/business-profile.json

(only if profile exists)

Follow the wiki update pattern from
```
references/memory-and-distribution.md
```
: update
```
index.md
```
rows for all affected entity files, append a
```
log.md
```
entry for this run.
Clean up checkpoint (complete run) or keep (partial run)

Update sibling artifacts: If

providers.json

enriched.json

exists for this slug under

~/.nimble/memory/

, merge NPI numbers and verification status into those files. Generate a verified CSV export at

~/.nimble/memory/healthcare-providers-verify/{slug}/verified-{date}.csv

with all verification columns (NPI, NPI Status, NPI Taxonomy, Verification Status). Offer this export path in Step 9 so the user can copy it where needed.

Step 9: Share, Distribute & Follow-ups

Always offer distribution — do not skip. Follow

references/memory-and-distribution.md

for connector detection and sharing flow.

Notion: full verification report as a dated subpage. Slack: TL;DR with verification counts and flagged items only.

Follow-ups:

"Tell me more about Dr. X" -> show full verification detail
"Export as CSV" -> generate CSV with verification statuses
"Re-verify flagged only" -> re-run NPI search for Flagged/Unverified only
"What should I do about the flagged ones?" -> actionable next steps per issue

Sibling skill suggestions:

Next steps:
Run
healthcare-providers-extract
on unverified providers' practice URLs to get fresh data
Run
healthcare-providers-enrich
to fill gaps in verified providers' records
Run
market-finder
to find additional practices in this area

Sub-Agent Strategy

For batch verification (10+ practitioners), use

nimble-researcher

agents (

agents/nimble-researcher.md

) to parallelize NPI lookups and extraction.

Follow the sub-agent spawning rules from

references/nimble-playbook.md

(bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn pattern: One agent per batch of 5 practitioners. Each agent runs Steps 3-4 for its assigned practitioners and returns verification records. Tell each agent to use

nimble extract-batch

for its NPI result URLs where possible — one batch call per agent is faster than sequential calls.

Small batch optimization: If fewer than 10 practitioners, run directly from the main context instead of spawning agents.

Fallback: If any agent fails, run those verifications directly from the main context. Never leave gaps in the output.

Error Handling

See

references/nimble-playbook.md

for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

No NPI results for practitioner: "Couldn't find an NPI record for [name] in [state]. The name may be too common, or the provider may practice under a different name. Want me to try with additional context (practice name, NPI number)?"
Multiple NPI matches: "Found multiple NPI records for [name] in [state]. Can you confirm which one? [list top 3 with NPI numbers and specialties]"
NPI page extraction returned garbage: "The NPI lookup page appears to be JavaScript-rendered. Retrying with browser rendering..." (auto-retry with
```
--render
```
per the shared pattern)
CSV/Sheet parse error: "Couldn't parse the input file. Expected columns with practitioner names and at least one identifier (state, specialty, or credentials). Can you paste the data directly instead?"
Insufficient data for verification: "Cannot verify [N] practitioners — they have only a name with no state, credential, or specialty. Add identifiers or remove them from the list."

healthcare-providers-verify

NPX Install

Tags

SKILL.md Content

Healthcare Providers Verify

Instructions

Step 0: Preflight + WSA Discovery

Step 1: Parse Input + Starting Questions

Step 2: Analyze Input Data

Step 3: NPI Registry Lookup

Step 4: Cross-Reference and Verify

Step 5: WSA Supplementary Verification (Optional)

Step 6: Deduplication & Confidence Scoring

Step 7: Output

Step 8: Save to Memory

Step 9: Share, Distribute & Follow-ups

Sub-Agent Strategy

Error Handling