ex-USSR Kinship Research

An evidence-first genealogy skill for AI agents (Codex, Claude Code and other Agent Skills runtimes). It turns an agent into a careful family-history researcher for the former USSR, the Soviet Union and the Russian Empire. The agent reads church books and civil records, military, deportation and repression files, and unindexed archive scans. It keeps every find traceable, separates records from interpretation and says plainly what is proven and what is not.

The skill's instructions are written in Russian, but the agent talks to you in your language: English, Ukrainian, Russian, Polish, German and so on. It quotes sources in their original spelling with a translation, and builds search queries in the languages of the records.

What it does

• Case intake and scope. One research question, known facts, who may be alive, what is off-limits.
• Reproducible registers. Persons, artifacts, claims, relationships and a full search log (CSV), plus a final report template.
• Historical jurisdiction model. It resolves every event to the state, province, district, parish or civil registry as of the event date, not today's map.
• Name-variant matrices. Pre-reform Russian, Ukrainian, Polish, Romanian, German and Yiddish forms, patronymics, maiden names and transliterations.
• Source strategy. Originals first, then official catalogs, indexes, published document collections, and only then trees and forums as leads.
• Evidence protocol. Claims get explainable statuses, not percentages: hypothesis, single-source, corroborated, strongly-corroborated, contradicted, unresolved. Copies and mirrors of one record share an independence_group, so they never count as independent proof.
• Identity resolution. Namesakes stay separate person_ids until distinguishing evidence appears: house number, parents, godparents, exact birth date or military unit.
• Audit script. It checks referential integrity and flags weak corroboration before you write conclusions. An independence group counts only when a cited artifact belongs to it, so corroboration cannot be declared into existence. It also checks the final report: every cited ID must exist in the registers and every status must match them. A summary shows what is still uncorroborated or marked illegible.
• Final report. Every relationship is laid out edge by edge, with contradictions, failed searches and concrete next steps.

Field lessons (new in 1.1.0)

Version 1.1.0 adds references/field-lessons.md, distilled from a real multi-week research case. Personal data from that case is not included.

• Unindexed scans. Most ex-USSR church books on FamilySearch are images only. The file shows how to find the right film (including archive-reference-to-film mapping), map it, skim the key column and zoom on candidates. It also covers what to log.
• Reading cues that link records.
  • An exact birth date in a marriage register can match a baptism day for day.
  • House numbers persist for decades.
  • Stillbirths are listed among births.
  • Patronymic formulas: Ukrainian possessive forms, Romanian fiul lui / n., Church Slavonic, German.
  • Clerk name swaps, such as Grigorie and Gheorghe.
• Marginal annotations. Later Soviet-era notes on old registers show when a certificate was issued, which is evidence that the person or their family was alive and requesting documents.
• Repression and deportation records.
  • Published document collections and their typical contents.
  • How rehabilitation books group people.
  • How to read a "basis" column such as a 25-year sentence.
  • Why a family is linked to a deportation operation, not to the local incident used to justify it.
  • How to draft an archive request.
• Military databases. WWII loss records (survivors are absent), "surname nests" built from birthplace clusters, and which portals put up CAPTCHAs. Austro-Hungarian WWI casualty lists help for Galicia and Bukovina.
• Places that no longer exist. Liquidated hamlets, redrawn districts, and the difference between "born in" and "grew up in". Also archives in occupied or war-damaged areas.
• Family materials as sources. Passports, oral-history recordings with timestamps, and the user's own notes, all tagged by source type.
• Browser technique. Deep-zoom tile crops, composite column views for fast skimming, keeping long jobs in their own tab, polite crawling and retries.
• Knowing when to stop. When public sources are exhausted, the agent says so once, prepares questions for living relatives and request drafts for archives, and does not invent or loop.

Also in 1.1.0:

• The agent replies in the user's language; the intake template defaults to requested_output_language: auto.
• The skill description is bilingual, so it triggers for English-speaking users too.
• CAPTCHAs are handed to a human. The agent never solves or bypasses them, and the user signs in to sites themselves.
• More seed sources, each with a reliability class and role.
• New eval cases: language matching, unindexed scans, house-number identity, birthplace conflicts, exhausted sources, repression lists.

Install

Clone the repository into your agent's skills folder:

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

# Claude Code (personal skills)
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

For a single project, put the folder in .claude/skills/ inside the repository. The scripts need only Python 3 and the standard library.

Use

Just describe the family question; the skill triggers on genealogy requests. For example:

• "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 are the same person and build the evidence chain."
• "Find the parish and the right FamilySearch film for a village in Podolia in the 1890s and read the births for the surname X."

The agent will set up a case folder:

python scripts/init_case.py --case-dir ./my-case --research-question "Who were Maria's parents?" --subject-label "Maria"
python scripts/hash_artifact.py ./scans/marriage-1902.jpg     # SHA-256 for every saved artifact
python scripts/audit_evidence.py --case-dir ./my-case          # check registers before the final report

Repository layout

SKILL.md                         main instructions (workflow, hard rules, language policy)
references/
  source-strategy.md             source hierarchy, query patterns, catalogs, archive requests
  evidence-protocol.md           artifact assessment, statuses, identity resolution, conflicts
  ex-ussr-locale-guide.md        jurisdictions, name variants, calendars, record types by period
  browser-and-captcha.md         browsing, sign-in, CAPTCHA hand-off, rate limits
  privacy-and-safety.md          living people, minors, DNA, sensitive findings
  seed-sources.md                curated starting resources with reliability classes
  field-lessons.md               practical lessons from a real case (new in 1.1.0)
assets/                          case intake, CSV registers, final report template
scripts/                         init_case.py, hash_artifact.py, audit_evidence.py
evals/discovery-and-logic.yaml   trigger and reasoning test cases
tests/                           unit tests for audit_evidence.py (python3 -m unittest discover -s tests)

Responsible use

• Family history, not surveillance. The skill refuses to look up current addresses, phones or accounts of living people, and it minimizes their data in reports.
• No bypassing. No CAPTCHA solving, no paywall, geo-block or rate-limit evasion, no leaked databases. Sign-ins are done by the user.
• No uploads of your documents or DNA data to third-party services without your explicit consent.
• Sensitive findings (deportation, repression, adoption, DNA surprises) are reported neutrally and only as far as the question requires.
• Archive access rules change. Always check the current official procedure before sending a request; the skill only drafts requests, it does not send them.

Contributing

New sources are welcome. Add them to references/seed-sources.md with these fields: owner, jurisdiction, collection type, originals or index, stable IDs, access, restrictions, typical errors, date last checked. Please keep personal data out of examples.

License

MIT © 2026 Denis Shiryaev.

Maintained by Denis Shiryaev (@DenisSergeevitch).