The ex-ussr-kinship-research repository passed 2,140 GitHub stars in late October 2026. It is not a fine-tuned model and not a hosted genealogy API. It is an agent skill — a large SKILL.md, reference manuals, CSV templates and Python audit tools — that tells Codex, Claude Code and similar runtimes how to research families across the former USSR without treating chat fluency as proof.
For builders, the interesting part is not the niche topic alone. It is one of the most complete evidence-first agent workflows on GitHub: reproducible registers, explicit claim statuses, independence groups for duplicate records, scripts that fail closed before you write conclusions, and optional FamilySearch and GWAR helpers that feed the same case folder.
TL;DR
| Piece | What it does |
|---|---|
SKILL.md | Intake, jurisdiction model, name variants, source strategy, evidence protocol |
references/ | Source hierarchy, correspondence, portals, privacy, WWI and GEDCOM guides |
assets/ | CSV register schemas and report.template.html |
scripts/ | init_case.py, hash_artifact.py, audit_evidence.py, build_pdf.py, search helpers |
| Default output | Browser-openable HTML report with clickable relationship evidence |
| License | MIT © 2026 Denis Shiryaev |
What problem it solves
Genealogy agents fail in predictable ways. They merge name collisions. They treat a copied forum tree as proof. They apply today's map to a 1910 birth. They quote a record once and call a parentage line confirmed.
The README opens with a different contract: the agent reads church books and civil records, military and deportation files, and unindexed scans; it keeps every find traceable; it separates records from interpretation; and it states plainly what is proven and what is not.
That lines up with a broader lesson in agent skills for coding: the skill is the accountability layer, not the model weights.
Evidence protocol in practice
The skill replaces fuzzy confidence with named statuses:
- hypothesis
- single-source
- corroborated
- strongly-corroborated
- contradicted
- unresolved
Records that are mirrors of the same artifact share an independence_group, so the agent cannot treat two copies as two independent witnesses. Identity resolution keeps separate person_id values for namesakes until distinguishing fields appear: house number, parents, godparents, exact birth date or military unit.
Before the agent writes a family conclusion, you run:
python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-case
The README says the audit checks referential integrity, flags weak corroboration, validates IDs in the working Markdown report when present, and summarizes what remains uncorroborated or illegible. That is closer to a data pipeline test than to a chat completion.
One highlighted card on a skills shelf suggests picking an evidence-first agent workflow
Historical jurisdiction and languages
Coverage spans all fifteen former Soviet republics. The skill resolves each event to the state, province, district, parish or civil registry as of the event date, not the modern border.
The instructions are written in Russian, but the agent is told to speak in your language — English, Ukrainian, Polish, German and others — while quoting sources in original spelling with translation. Search queries follow record languages, including pre-reform Russian, Ukrainian, Polish, Romanian, German and Yiddish variants.
That design matters for anyone building multilingual agent tools beyond genealogy. It is the same class of problem as routing Claude connector bugs through the correct locale and credential, except here the stakes are archival accuracy.
Install paths for Codex and Claude Code
The README documents three install routes:
Skills CLI:
npx skills add https://github.com/DenisSergeevitch/ex-ussr-kinship-research
Codex personal skills:
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
Case initialization must stay outside the git checkout:
python scripts/init_case.py --case-dir ~/kinship-cases/my-case \
--research-question "Who were Maria's parents?" \
--subject-label "Maria"
init_case.py refuses to create a case inside the skill folder, even with --force, because accidental commits of private scans are a real failure mode. That mirrors good hygiene for Claude Code settings — research data and credentials do not belong in the skill repo.
FamilySearch, GWAR and institutional mail
The skill does not pretend indexes replace originals. Its source strategy ranks originals first, then official catalogs, then published collections, then trees and forums as leads only.
Two optional modules matter for power users:
- FamilySearch targeted browser research saves permitted fragments with checksums; Python helpers search relatives and variants inside saved files. A connected FamilySearch MCP path is documented with scope and read-back rules.
- GWAR WWI search locates hospital, award and prisoner-of-war cards, compares settlement spellings, then chases the source image.
The skill can also draft institutional archive requests and, when you authorize it, send through supported mail integrations — logging outcomes as evidence, not as chat footnotes.
HTML reports and optional PDF
The default deliverable is report.html from assets/report.template.html, with a family tree header when evidence allows and relationship detail behind clicks. The README stresses that missing relatives do not block shipping a report; gaps stay visible.
PDF is deliberately secondary:
python scripts/build_pdf.py --html ~/kinship-cases/my-case/report.html \
--out ~/kinship-cases/my-case/report.pdf
That needs Chrome, Chromium or Edge (or CHROME_PATH). Static HTML with local images only; the exporter rejects active HTML and network image sources.
Safety and refused tasks
The Responsible use section is explicit:
- No lookup of living people's addresses, phones or accounts.
- No CAPTCHA solvers, paywall evasion or leaked databases; one CAPTCHA attempt through normal browser controls, then hand-off.
- No uploads of your documents or DNA to third parties without explicit consent.
- Neutral reporting on deportation, repression, adoption or DNA surprises.
Authorized correspondence requires explicit send permission; connecting a mailbox alone does not authorize outbound mail.
For teams wiring agents to real mail and archives, that policy boundary is as important as any MCP server hardening checklist — the skill documents rate limits and browser guidance in references/browser-and-captcha.md and references/privacy-and-safety.md.
Why developers star a genealogy skill
Three reasons show up in how the repo is built:
- Evals and tests.
evals/discovery-and-logic.yamlandpython3 -m unittest discover -s testssignal the author expects regressions, rare among trending SKILL.md drops. - Reference library depth. Dozens of markdown references (
chechnya-deportation.md,germany-forced-labour.md,familysearch-indexes.md) encode domain knowledge agents cannot hallucinate reliably. - Portable pattern. The evidence registers and audit script are reusable for non-genealogy research agents: legal discovery, incident timelines, or compliance investigations — anywhere "corroborated" must mean something testable.
It is not a replacement for deep-research skills that chase news articles. It is the opposite bias: slow evidence with named uncertainty.
Stacked research papers with a small branching diagram echo structured evidence notes in an agent genealogy case
Limits
- Access reality. Many archives are offline, paywalled or session-gated. The skill documents hand-offs; it cannot grant credentials.
- FamilySearch MCP variance. Connector capabilities differ by browser and account; the README tells the agent to verify actual read and write scope.
- Scope. GEDCOM export is supported; installing desktop tree apps or auto-syncing external trees is out of scope.
- Language load. USSR research is inherently multilingual; agents still need human review on transliteration edge cases.
Related reading
- What are agent skills?
- Andy Hall on AI audit agents and false alarms
- benjitaylor/skills Stageshow
- Floorplan codebase health skill
- Postman auto-installing Codex plugins
- Scenario Labs creative skills
Repository layout for contributors
The README maps more than a skill file. Under references/ you get jurisdiction guides (ex-ussr-locale-guide.md), Chechnya deportation workflows, Habsburg Galicia notes, forced-labour Germany routes through Arolsen, and per-country Moldova/Bessarabia explainers. The forced-labour reference covers workers taken to Germany from 1941 to 1945 and points researchers to the Arolsen Archives, the largest archive on victims and survivors of Nazi persecution, together with German civil registers. For many families, that is the only route to a missing relative's fate. That depth is why the star count is not mere curiosity traffic: diaspora researchers treat the repo as a living manual, and agent builders treat it as a template for domain-saturated skills.
seed-sources.md invites contributions with reliability classes — owner, jurisdiction, collection, provenance, access limits and check dates. That is the same metadata discipline teams want when they register MCP servers with credentials and data scopes.
Contributors run:
python3 -m unittest discover -s tests
before changing helpers. FamilySearch and GWAR paths include synthetic fixtures so parsers fail in CI instead of in a cousin's case folder.
Example prompts that fit the skill
The README suggests concrete intakes:
- tracing parents through 1930s Kazakhstan exile church and civil leads;
- reconciling marriage scans and soldier cards for one identity chain;
- locating a Podolia parish FamilySearch film and reading surname X births in the 1890s.
Each prompt assumes you will accept unresolved lines in the HTML tree. That expectation management is rare in consumer genealogy marketing, and it is exactly what keeps agents from over-merging people.
GEDCOM and desktop tools
When you request GEDCOM, the skill defaults to 5.5.1 UTF-8 unless you need 7.x for a specific program. The GEDCOM specifications page explains why: versions 5.5 and 5.5.1 are both still in use in the marketplace, while 7.0 is the newest released version. The skill keeps the widely used format as its default and moves to 7.x only on request. Importantly, an uploaded tree is input and leads, not proof: the agent preserves your original file, keeps unsupported claims visible, and exports only what the evidence registers justify.
Installing legacy desktop genealogy apps, wiring MCP sync, or auto-pushing edits to hosted trees stays out of scope — a boundary product teams should copy when they fear agents silently mutating external systems.
After you ship a case
Good next steps for practitioners:
- Archive SHA-256 hashes for every scan (
hash_artifact.py) before sharing HTML. - Re-run
audit_evidence.pyafter each new record batch. - Store correspondence PDFs as artifacts with independence groups when archives send duplicates.
- Review
references/privacy-and-safety.mdbefore sending family-facing links.
If you teach agentic coding workshops, this repo is a classroom example of structured uncertainty — more valuable than another demo that auto-approves every step.
Repository statistics and workflow details match the GitHub README on November 8, 2026.