agentleFS
charliehzmcharliehzm/medharness/.claude/skills/phi-desensitize/SKILL.md

phi-desensitize

Skill85 starsChanged 6 months agoApache-2.0View on GitHub

Use this skill before any prompt, log message, error trace, test fixture, or external API call that may include patient health information (PHI) or personal identifying information (PII) in a medical-data SaaS context. Replaces sensitive tokens with reversible synthetic substitutes, emits a desensitize map (encrypted), and produces a residual-risk report. Mandatory pre-stage before any L3/L4 data ever enters a model context window. Chinese trigger examples: "脱敏", "PHI 脱敏", "数据脱敏", "去标识化", "patient_id 替换", "把这段日志脱敏", "把样例匿名化". Do NOT use as a one-way redactor when the workflow needs round-trip mapping; do NOT use for fully synthetic data that contains no real source values (use test-data-generation instead). Success = every L3/L4 token in input is replaced, output passes mcp-phi-detector with zero hits, reversal map is encrypted with KMS-managed key, and residual-risk report is empty or explicitly approved.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If rule says PHI but classifier disagrees: still desensitize (false positive is cheap)

    line 89
  2. Very specific:

    If classifier says PHI but rule didn't: desensitize + log to residual_risk_report (for rule library update)

    line 90

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PHI Desensitize

The single most important runtime gate in the entire AI Coding system: no L3/L4 token should ever enter a model context window without first passing through this skill.

Core mental model

Desensitization is not redaction. Redaction destroys information; desensitization replaces it with reversible placeholders so the downstream LLM can still reason about structure and relationships, while the operator can reverse the mapping on a vetted output in a controlled environment.

"Patient 张三 (ID 110101199001011234) seen 2026-03-12"
   ↓ desensitize
"Patient {{PT_A1}} (ID {{ID_B7}}) seen {{DATE_C3}}"
   ↓ LLM reasons, produces analysis referencing {{PT_A1}}
   ↓ controlled reversal in approved environment
"Patient 张三 (ID 110101199001011234) seen 2026-03-12 — diagnosis: ..."

What this skill produces

For each invocation:

  1. desensitized_payload — sanitized text / JSON / fixture
  2. <source>.desensitize_map.json.enc — encrypted reversal map (AES-256-GCM, key from KMS)
  3. residual_risk_report.md — listing any tokens the classifier was uncertain about

When NOT to use this skill

Skip for:

  • Already fully synthetic data (use test-data-generation instead)
  • Purely L1 / public content (no PHI possible)
  • One-way logging where reversal is never needed (use simple redaction)
  • Encryption / hashing at storage layer (that's data-at-rest concern, different domain)

Active context bundle

Always load first

  1. This SKILL.md
  2. reference/hipaa-18-identifiers.md — the canonical PHI taxonomy
  3. reference/cn-personal-info-catalog.md — 公安部 / 健康医疗数据安全指南 PII categories
  4. reference/detection-rules.md — regex + ML classifier combination strategy

Load on demand

  • reference/free-text-strategy.md — for unstructured notes / discharge summaries
  • reference/structured-data-strategy.md — for JSON / CSV / Parquet payloads
  • reference/reversal-protocol.md — when reversal is needed in approved environment

Detection strategy (dual-pass)

Pass 1 — Rule layer (deterministic, high recall)

  • CN-ID regex: \d{17}[\dXx] after Luhn-like check digit
  • CN-phone regex: 1[3-9]\d{9}
  • CN-name heuristic: 2-4 CJK chars in subject position of sentence
  • Birth date: \d{4}[-/年]\d{1,2}[-/月]\d{1,2} — combined with name proximity bumps tier
  • Medical record number: pattern depends on hospital; load org-specific patterns from reference/org-mrn-patterns.md
  • 18 HIPAA identifiers: see reference

Pass 2 — Classifier layer (high precision)

  • Local fine-tuned BERT or Qwen-1.8B running CPU
  • Confirms / rejects Pass 1 candidates
  • Catches free-text PHI missed by regex (e.g. "the man whose wife works at Tongji")

Pass 3 — Disagreement resolution

  • If rule says PHI but classifier disagrees: still desensitize (false positive is cheap)
  • If classifier says PHI but rule didn't: desensitize + log to residual_risk_report (for rule library update)

Substitution scheme

Each detected token → {{TYPE_SHORTID}} where:

  • TYPE ∈ {PT (patient), ID (identifier), DR (doctor), HS (hospital), DT (date), AD (address), PH (phone), MR (medical record), DX (diagnosis sometimes), TX (treatment sometimes)}
  • SHORTID is a 2-char base32 from a per-session HMAC of the original value, so the same input within a session gets a stable placeholder (preserves relationships)

The map stores {placeholder: original} and gets encrypted before being written to disk.

Reversal protocol (controlled)

Reversal is opt-in and audited:

  1. Reversal can only happen inside the project's .controlled/ directory (mounted read-only outside dev environment)
  2. Reversal requires:
    • Active developer session with Data Steward signoff
    • The .desensitize_map.json.enc from the same change
    • KMS access (logged centrally)
  3. Reversed output is treated as L4 immediately upon reversal — no copying to other locations

Hard gate checklist

  • Every L3/L4 token in the source has been replaced
  • Output passes mcp-phi-detector with zero hits (hooked at UserPromptSubmit, double-check)
  • Desensitize map encrypted with KMS-managed key (no plaintext map on disk)
  • Residual risk report empty OR every entry has owner ack
  • If used inside a Skill chain, the desensitized payload is what flows downstream — never the original

Common failure modes

  1. Half-desensitized fixtures: dev manually replaced names but forgot phone numbers. Mitigation: always run both passes, never trust manual cleanup.
  2. Map leakage: developer puts the unencrypted map in repo. Mitigation: hook PreToolUse to deny Write(*.desensitize_map.json) (no .enc suffix).
  3. Cross-change collisions: same patient appears in two changes, placeholders differ — that's fine and intentional (no cross-change linkability). Don't try to "harmonize" across changes.
  4. Free-text re-identification: "the 38-year-old male diabetic seen in Shanghai United on 2026-03-12" — even with name removed, this is identifying. Detection must consider co-occurrence. The classifier layer is your defense; rule layer alone is insufficient.
  5. Date shifting confusion: for time-series analysis, simply masking dates breaks reasoning. Use date shifting: add a per-patient random offset that preserves intervals. Document the shift in the map.

Integration points

  • At Hook layer: UserPromptSubmit runs mcp-phi-detector as a tripwire; if it fires AFTER this skill, something is wrong (regression or new vector)
  • At MCP layer: mcp-desensitize exposes this skill's logic as a callable tool so non-conversation flows (CI, batch jobs, MCP-using sub-agents) can use it programmatically
  • At SOP layer: invoked before any prompt in Steps 5 (mock data), 6 (apply), 8 (review), 9 (mocking test) that touches L3/L4

Output handoff

Returns:

  • Desensitized payload (use as-is downstream)
  • Path to encrypted map (for controlled reversal later)
  • Residual risk report (must be empty or signed off)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.