generating-synthetic-surrogates

Replace detected PHI with realistic, type-matched fake values in OpenMed so clinical notes stay readable and parseable instead of full of [REDACTED] markers. Use when the user wants surrogate names, MRNs, addresses, or dates rather than opaque masks, needs consistent fake identities across a document, must keep notes natural for downstream NLP, or wants to register a custom surrogate generator or provider. Covers deidentify(method="replace", consistent=True, seed=..., locale=...), register_label_generator, register_clinical_provider, and Anonymizer/AnonymizerConfig. Pairs with OpenMed deidentifying-clinical-text and configuring-privacy-policies.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-crafted, actionable skill body with executable examples, a clear validated workflow, and strong sectioning. The main improvement room is making the final verification step inline rather than deferred to a sibling skill, and potentially offloading the standards/API reference detail into a bundled file.

Suggestions

Inline a concrete verification snippet in the Workflow's Verify step (e.g. a collision check command or auditing call) rather than only referencing the auditing-deidentification-runs skill, to close the validation checkpoint.

Consider moving the 'Standards & references' list and the full custom-provider API detail into a bundled references file, keeping SKILL.md a tighter overview with one-level-deep pointers.

Tighten the explanatory paragraph after the Quick start code block — the consistent=True/seed rationale is partly restated in the table and Workflow, so a single concise mention would reduce redundancy.

Dimension	Reasoning	Score
Conciseness	Lean, well-sectioned body that assumes Claude's competence — no padding about what PHI or Faker is — with only minor explanatory passages (e.g. the consistent=True paragraph) that could be trimmed slightly; sits above the 'mostly efficient' anchor but not perfectly lean.	4 / 5
Actionability	Fully executable, copy-paste-ready Quick start with expected output, plus a complete custom-providers block showing real signatures (register_label_generator, AnonymizerConfig.custom_providers) and a direct surrogate() call covering the common cases.	5 / 5
Workflow Clarity	A clear six-step Workflow sequence with an explicit Verify checkpoint (step 6) for a batch/de-identification operation, satisfying the destructive/batch validation requirement; the verify step points outward to auditing-deidentification-runs rather than giving an inline command, a minor gap keeping it below 5.	4 / 5
Progressive Disclosure	Well-organized into clear sections (When to use, Quick start, comparison table, Custom providers, Workflow, Hand-off, Edge cases, Standards) with clearly signaled sibling-skill references and external links; no bundle files exist, and a little of the inline standards/API detail could be split out, so it is just below the ideal one-level-deep structure.	4 / 5
	Total	17 / 20 Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly states what the skill does and when to use it, with concrete API references and explicit trigger phrases. It is well-differentiated from sibling de-identification skills, with only minor room for broader natural-language trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Replace detected PHI with realistic, type-matched fake values', 'register a custom surrogate generator or provider' — and enumerates specific API surfaces (deidentify, register_label_generator, register_clinical_provider, Anonymizer/AnonymizerConfig), giving comprehensive coverage.	5 / 5
Completeness	Explicitly answers both 'what' ('Replace detected PHI with realistic, type-matched fake values in OpenMed so clinical notes stay readable and parseable') and 'when' via a concrete 'Use when the user wants...' clause with multiple trigger phrases.	5 / 5
Trigger Term Quality	Strong natural keywords ('surrogate names, MRNs, addresses, or dates', 'consistent fake identities', 'downstream NLP', 'custom surrogate generator') with good synonym coverage; a few lay terms a non-expert might say are absent, so it sits just below the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Clear niche (OpenMed surrogate replacement) differentiated from masking ('rather than opaque masks') and explicitly paired with sibling skills deidentifying-clinical-text and configuring-privacy-policies; minor overlap risk with those closely related de-id skills keeps it just below 5.	4 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: maziyarpanahi/openmed
Path: skills/generating-synthetic-surrogates/SKILL.md
Commit: 80da98c

Reviewed: about 24 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.