> ## Content Index
> Fetch the complete content index at: https://claudefox.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# ex-USSR Kinship Research: an evidence-first genealogy skill for Claude Code and Codex
- URL: https://claudefox.com/ex-ussr-kinship-research/
- Published: 2026-11-16T03:25:33.000Z
- Updated: 2026-11-16T03:34:09.000Z
- Description: ex-USSR Kinship Research is a free, MIT-licensed agent skill that makes Claude Code or Codex research family history across the former USSR from church, civil and military archives, logging every source and labelling each claim by evidence strength.
- Author: hupicake
- Tags: Tools

ex-USSR Kinship Research (GitHub: DenisSergeevitch/ex-ussr-kinship-research) is a free, MIT-licensed agent skill that turns Codex, Claude Code or another Agent Skills runtime into a cautious family-history researcher for the former Soviet Union and the Russian Empire. It reads church books, civil, military and repression files, but its core idea is bookkeeping: every find is logged with its origin, every claim gets an evidence status, and the report says what is proven and what is not. Denis Shiryaev created the repo on October 25, 2026; it had 2,543 stars and 252 forks as of November 16, 2026.

## Quick facts

- What it is: a skill folder (SKILL.md, reference guides, templates, Python helpers), not an app.
- Coverage: all 15 former Soviet republics, plus guides for regions such as Bessarabia, Galicia and the 1944 Chechen deportation.
- Language: instructions in Russian; the agent replies in your language. The README exists in 19 languages.
- Version: 1.46.0 (November 15, 2026), the latest of 43 GitHub releases between October 25 and November 15, none pre-release and none with attached release assets.
- Price: free, MIT. Some archives it points to need an account or paid access.

## How to install

With Node.js, the optional third-party Skills CLI installs it for the agent you pick (current project by default, -g for all projects):

```
npx skills add https://github.com/DenisSergeevitch/ex-ussr-kinship-research
```

Or clone it straight 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, place the folder in .claude/skills/ inside that repository. With 43 releases in three weeks the instructions change often; the skill has the agent check the repository once at the start of a case and ask before updating.

## First setup

Describe a family question in plain language, such as who a great-grandmother's parents were. The agent records a case intake (question, known facts, who may be alive, what is off-limits) and then works on its own instead of stopping at each step.

Keep case files outside the skill's checkout. The README's helpers create a case, fingerprint each scan and audit the registers:

```
python scripts/init_case.py --case-dir ~/kinship-cases/my-case --research-question "Who were Maria's parents?" --subject-label "Maria"
python scripts/hash_artifact.py ~/kinship-cases/my-case/scans/marriage-1902.jpg
python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-case
```

Sites such as FamilySearch need you to sign in yourself; until then those routes are marked blocked. The default deliverable is an HTML report with a family tree in the header. PDF only on explicit request; trees export as local GEDCOM 5.5.1 UTF-8 by default, or GEDCOM 7\. Installing tree apps, configuring MCP and syncing external trees are outside its scope.

## What stands out

Statuses instead of percentages. Each claim is marked hypothesis, single-source, corroborated, strongly-corroborated, contradicted or unresolved. Corroborated needs at least two independent evidence chains; even a strong original stays single-source until confirmed.

Copies do not count twice. Mirrors, indexes and retellings of one record share an independence\_group. Several transcriptions of the same image, by people, models or OCR, also stay one chain and cannot raise a claim's status. The audit script counts a group only when a cited artifact belongs to it.

Namesakes stay apart. Same-name people keep separate IDs until parents, godparents, an exact date, a house number or a military unit tells them apart.

Places as they were. Every event is resolved to the province, parish or registry that existed on that date, with name-variant matrices across Russian, Ukrainian, Polish, Romanian, German and Yiddish spellings.

A failed search is not a negative result. A CAPTCHA, a 401 from a viewer or an empty index is logged as blocked or unresolved, never as proof that a person or event did not exist. Contributors add dated observations like a FamilySearch viewer returning 401 on frames that had loaded before (PR #279, November 13).

## How it was built with Claude

In the full history fetched on November 16 (639 commits), the first commit, d7fbb03 on October 25 (skill v1.1.0), carries a Co-Authored-By line for Claude Opus 5.5; 63 commits in total carry such a Claude line, most of them in contributors' pull requests. Recent review merges are prepared on branches named codex/review-... and codex/maintenance-.... There is no CLAUDE.md; the rules live in SKILL.md, with evals and unit tests.

**Try it with your AI.** You can borrow the evidence-first method for your own family research without installing anything. Paste this into the AI assistant you already use:

```
I want to research my family history using an evidence-first method. I know you will
read what I paste here, but do not upload or send my documents, photos or DNA data to
any other service unless I confirm first.

First, ask me for one research question ([e.g. who were my great-grandmother's
parents]), the facts I know, and who may still be alive. Never look up current
addresses, phones or accounts of living people.

Then keep five tables as CSV text I can save in [a folder name of my choice]:
1. Artifacts: every document, scan or family story, with its origin and date seen.
2. Persons: one ID each. Do not merge same-name people until parents, an exact date or
   another distinguishing detail links them.
3. Relationships: each parent, child or spouse link with the claims behind it.
4. Claims: each fact with a status of hypothesis, single-source, corroborated,
   strongly-corroborated, contradicted or unresolved. Never mark anything corroborated
   without two independent chains of evidence. Copies, indexes and re-readings of the
   same record share one independence group and count once.
5. Search log: every search, including empty or blocked ones, which never prove someone
   did not exist.

Keep original spellings next to normalised forms. Record contradictions, never invent
missing details, and never turn family memory into documented fact.

If a site needs a login, payment or a CAPTCHA, show me the site and wait for my
confirmation; I will sign in myself. Never use CAPTCHA solvers, VPNs or proxies to get
around blocks or rate limits, never bulk-download from an archive, and follow each
site's terms. Before writing conclusions, show me the claims table and wait for my
confirmation.
```

## Known limits

- Living relatives. The privacy guide rules out current addresses, phones, accounts or document numbers of living people, web tracing of minors, and face recognition on photos of living people. Shareable reports replace living people with initials or IDs and check captions and file names for indirect identification. These are rules for the agent, not enforced locks, so check a shareable report yourself before sending it.
- What leaves your machine. The agent's browser reaches whatever archives a case needs, such as FamilySearch and regional archive viewers. The bundled gwar.py helper sends name or locality searches to gwar.mil.ru, the Russian WWI losses database, and for that connection only trusts two Russian certificate-authority files shipped in scripts/ca, not your system store; running it means accepting those certificates for that site. Documents, photos and DNA files should not go to new outside services without your explicit consent. (General note, not from the project: search terms go to the sites searched, and whatever the agent reads is processed by your model provider.)
- Archive terms of use. The agent must follow FamilySearch's terms, which require written permission for bulk retrieval, and keep only fragments a source permits. It may try one CAPTCHA through the normal page, then hands it to you; solvers, VPNs against geo-blocks, rate-limit evasion and paywall bypass are forbidden. GEDmatch's terms forbid scraping, and a contributor reported an account disabled after automated reading (PR #258). Check each archive's terms and current access rules before the agent works there.
- Accuracy. A model can misread old handwriting. The safeguards are procedural: claims stay single-source until independently confirmed, the audit flags weak corroboration and illegible items, and the rules forbid inventing missing details. The evidence protocol notes that a passing audit does not prove historical independence, so treat it as a register check and re-read key lines yourself.
- Letters and tree edits. With your authorization it can email archives through a connected mailbox and edit a FamilySearch tree through a connected MCP server; a connected mailbox alone does not authorize sending.
- Time and cost. By default the agent works autonomously in runs that can last hours. Archives can charge: per the seed-source list, Russia's federal remote-access system (GIS UIAD) had a free catalogue but charged 90 roubles an hour or 350 a day for viewing (price list read October 30), with sign-in through Gosuslugi.

## Problems and feedback

Issues and pull requests go to the GitHub repository. On November 16 the only open item was PR #284, about MyHeritage dropping Julian-marked dates. Contributors should keep personal data out of examples.

## FAQ

Can it prove a relationship automatically? No. Helpers such as gwar.py import finds as leads only; they never establish identity or kinship.

What does corroborated mean here? At least two independent evidence chains about the same person or event, with no unresolved material contradiction and a written reason why they are independent.

What do I need installed? Your agent and Python 3 for the helper scripts. Node.js only for the optional Skills CLI, Pillow only for the scan montage helper, and Chrome, Chromium or Edge only for PDF export.

Which agents does it work with? The README names Codex, Claude Code and other Agent Skills runtimes; the Skills CLI lets you choose the agent at install time.

Source: [GitHub: DenisSergeevitch/ex-ussr-kinship-research](https://github.com/DenisSergeevitch/ex-ussr-kinship-research?ref=claudefox.com), [ex-USSR Kinship Research README](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/README.md?ref=claudefox.com), [SKILL.md (agent instructions, v1.46.0)](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/SKILL.md?ref=claudefox.com), [Privacy and safety guide](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/privacy-and-safety.md?ref=claudefox.com), [Browser, sign-in and CAPTCHA guide](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/browser-and-captcha.md?ref=claudefox.com), [Evidence protocol](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/evidence-protocol.md?ref=claudefox.com), [FamilySearch indexes workflow](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/familysearch-indexes.md?ref=claudefox.com), [FamilySearch MCP workflow](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/familysearch-mcp.md?ref=claudefox.com), [gwar.py WWI search helper](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/scripts/gwar.py?ref=claudefox.com), [Seed sources catalogue](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/seed-sources.md?ref=claudefox.com), [Changelog](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/blob/main/references/changelog.md?ref=claudefox.com), [Releases](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/releases?ref=claudefox.com), [Commit history](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/commits/main?ref=claudefox.com), [Issues and pull requests](https://github.com/DenisSergeevitch/ex-ussr-kinship-research/issues?ref=claudefox.com), [Skills CLI (vercel-labs/skills)](https://github.com/vercel-labs/skills?ref=claudefox.com)

This story first appeared in the [claudefox daily briefing for November 16, 2026](https://claudefox.com/daily-2026-11-16/).