Evidence-First ex-USSR Genealogy Research with AI Agents

What is ex-USSR Kinship Research?

ex-USSR Kinship Research is an evidence-first genealogy skill for AI agents such as Codex and Claude Code. It helps investigate family-history questions involving the former USSR, the Soviet Union and the Russian Empire while keeping records, interpretations and unresolved questions clearly separated.

The skill is designed for church books, civil registers, military databases, deportation and repression files, published document collections and unindexed archive scans. Instead of producing an unsupported family tree, it records where each finding came from, distinguishes independent evidence from duplicate copies and explains what has or has not been proven.

The internal instructions are written in Russian, but the agent responds in the user's language. It can quote names and passages in their original spelling, provide translations and construct searches in languages appropriate to the records, including Russian, Ukrainian, Polish, Romanian, German and Yiddish forms.

Key features

• Structured case intake: Defines one research question, known facts, potentially living people and any topics that are off-limits.
• Reproducible registers: Maintains CSV records for people, artifacts, claims, relationships and searches, alongside a final report template.
• Historical jurisdictions: Resolves an event according to the state, province, district, parish or civil registry that existed at the event date rather than relying on the modern map.
• Name-variant analysis: Accounts for patronymics, maiden names, transliterations and historical forms across several regional languages.
• Source hierarchy: Prioritizes original records, official catalogs and indexes before treating online trees or forums as leads.
• Explicit evidence states: Labels claims as hypothesis, single-source, corroborated, strongly-corroborated, contradicted or unresolved.
• Identity resolution: Keeps possible namesakes under separate person_id values until details such as parents, house number, exact birth date, godparents or military unit connect them.
• Evidence auditing: Checks referential integrity and warns about weak corroboration before a final report is written.
• Responsible boundaries: Protects living people, requires human handling of sign-ins and CAPTCHAs, and prohibits bypassing paywalls, rate limits or access controls.

Prerequisites

You need Git, Python 3 and a supported Agent Skills runtime. The included scripts use only Python's standard library, so no additional Python packages are required.

Choose the installation location that matches your agent. Codex uses ~/.codex/skills/, while personal Claude Code skills use ~/.claude/skills/. Claude Code can also load the skill from a project's .claude/skills/ directory.

Install the skill

Install for Codex

git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-research

Install as a personal Claude Code skill

git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

Install for one Claude Code project

Clone or copy the repository into .claude/skills/ex-ussr-kinship-research inside the project repository. This keeps the skill associated with that project instead of making it available across all your projects.

The source repository is available at GitHub.

Start a research case

The simplest way to begin is to state one concrete family-history question. Include known names, approximate dates, places, record scans and uncertainties, but avoid assuming that unverified family stories are facts.

Example requests include:

• My great-grandfather was exiled to Kazakhstan in the 1930s. Help me find his parents in church records.
• Here are scans of a marriage certificate and a soldier card. Check whether they refer to the same person and build the evidence chain.
• Find the parish and the correct FamilySearch film for a village in Podolia in the 1890s, then inspect the births for this surname.

The agent should conduct an intake before broad searching. A useful request specifies the primary question, known facts, potentially living people, restrictions and desired output language. The default language setting is automatic, so the agent should normally answer in the same language used by the researcher.

Create the case workspace

From the skill repository, initialize a case directory with the included script:

python scripts/init_case.py --case-dir ./my-case --research-question "Who were Maria's parents?" --subject-label "Maria"

This establishes the structured workspace used to track people, artifacts, claims, relationships and searches. Keep one focused research question per case so the resulting evidence trail remains understandable.

Register and hash artifacts

Saved scans and documents should remain identifiable even if filenames change or duplicate copies appear. Generate a SHA-256 hash for each artifact:

python scripts/hash_artifact.py ./scans/marriage-1902.jpg

Record the artifact in the case registers with its source information. A downloaded image, a crop and a mirror of the same underlying record are not automatically independent evidence. Related copies should share an independence_group so they cannot be counted as separate proof.

Follow an evidence-first workflow

1. Define the target claim. Convert the broad family question into a claim that records could support or contradict, such as identifying Maria's parents.
2. Resolve the historical place. Determine the jurisdiction at the date of the event, including the relevant state, district, parish or civil registry.
3. Build name variants. Prepare likely spellings, patronymics, maiden names and transliterations in the languages used by local record keepers.
4. Search stronger sources first. Prefer original records, then official catalogs, indexes and published document collections. Treat user-contributed trees and forum posts as leads rather than proof.
5. Log successful and failed searches. Record where you searched, the query or film inspected and the result. Negative findings prevent repeated work and clarify which public sources have been exhausted.
6. Create claims from evidence. Link every factual assertion to its supporting artifacts and assign an explainable status.
7. Resolve identities cautiously. Do not merge people merely because they share a name and village.
8. Audit before reporting. Run the audit script and address weak links, missing references and improperly counted corroboration.

Audit the evidence

Before generating conclusions, run:

python scripts/audit_evidence.py --case-dir ./my-case

The audit checks the registers for referential integrity and flags weak corroboration. Use its findings to correct the case data or mark claims as unresolved. The goal is not to force every question into a confident answer, but to ensure that each conclusion accurately reflects the available evidence.

Working with unindexed scans

Many ex-USSR church books on FamilySearch are image-only collections. Searching by surname may therefore return nothing even when the relevant entry exists. The project's field lessons recommend locating the correct film, mapping archive references to film identifiers, finding the relevant volume or section, skimming the key column and zooming in on candidates.

Log the film, image range, record type and pages inspected. When practical, focused crops or composite column views can make long registers easier to review. Browser work should remain polite: respect rate limits, use retries appropriately and leave lengthy scanning tasks in a dedicated tab.

Look for linking details

Names alone are often insufficient. Stronger identity clues may include an exact birth date repeated in a marriage record, a persistent house number, matching parents or godparents, or a military unit. The field guide also covers stillbirth entries, historical patronymic formulas and clerk substitutions such as Grigorie and Gheorghe.

Marginal Soviet-era annotations on older registers can also matter. A later note that a certificate was issued may show that the person or family was alive and requesting documentation at that later date.

Advanced research tips

Separate birthplace from residence

Do not treat “born in” and “grew up in” as interchangeable. Villages may have been renamed, transferred between districts or liquidated entirely. Build the place history around the event date and document modern equivalents separately.

Use surname clusters carefully

Military databases can reveal groups of people with the same surname and birthplace, sometimes described as surname nests. These clusters are useful for generating hypotheses, but they do not establish kinship by themselves. WWII loss databases also tend to omit survivors, so absence is not proof that a person did not serve.

Interpret repression and deportation sources in context

Published collections and rehabilitation books can contain sentencing, family and administrative details. Read columns such as the legal basis carefully. A local incident cited in a file may not be the same as the broader deportation operation affecting the family. When public records are insufficient, the skill can draft an archive request, but it does not send that request.

Treat family materials as sources

Passports, oral-history recordings and the researcher's notes can be included as evidence when correctly labeled by source type. Add timestamps for recorded interviews and preserve the distinction between what a relative directly witnessed, what they heard from someone else and what the researcher inferred.

Stop when public evidence is exhausted

A responsible agent should not repeat the same searches indefinitely or fill gaps with invented details. Once accessible sources are exhausted, summarize what was checked, prepare focused questions for living relatives and draft requests for relevant archives.

Privacy and access rules

• Do not use the skill to find current addresses, telephone numbers or online accounts belonging to living people.
• Minimize personal information about living people and minors in reports.
• Do not upload private documents or DNA data to third-party services without explicit consent.
• Let the user complete site sign-ins and CAPTCHAs. The agent must never solve or bypass a CAPTCHA.
• Do not evade paywalls, geo-blocks, rate limits or other access controls, and do not use leaked databases.
• Report sensitive discoveries involving repression, deportation, adoption or DNA surprises neutrally and only to the extent required by the research question.
• Verify current archive procedures before submitting a request because access rules can change.

Understand the repository

SKILL.md contains the core workflow, hard rules and language policy. The references/ directory provides source strategy, evidence rules, locale guidance, browser practices, privacy guidance, curated seed sources and practical field lessons. The assets/ directory holds case templates, while scripts/ contains the initialization, hashing and audit utilities.

Contributors can add sources to references/seed-sources.md. Entries should identify the owner, jurisdiction, collection type, whether the resource contains originals or an index, stable identifiers, access conditions, restrictions, typical errors and the date last checked. Examples must not expose personal data.

Conclusion

ex-USSR Kinship Research turns an AI agent into a structured research assistant rather than an automatic family-tree generator. Its main value is traceability: each person, artifact, claim, relationship and search can be reviewed, while uncertainty and contradictions remain visible. By combining historical jurisdictions, multilingual name variants, cautious identity resolution and a final audit, you can produce family-history conclusions that are reproducible and honest about their limits.

The project is maintained by Denis Shiryaev and distributed under the MIT License.