ex-ussr-kinship-research README

项目的 README,来自 github.com/DenisSergeevitch/ex-ussr-kinship-research。合并为一个 markdown 文件:README.md。

ex-USSR Kinship Research

ex-USSR Kinship Research cover

Languages: English / Русский / Беларуская / Қазақша / Українська / Polski / Deutsch / Română / Eesti / Latviešu / Lietuvių / ქართული / Հայերեն / Azərbaycanca / Кыргызча / Тоҷикӣ / Türkmençe / O‘zbekcha / 日本語

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.

Coverage includes all 15 former Soviet republics: Russia, Ukraine, Belarus, Moldova, Estonia, Latvia, Lithuania, Georgia, Armenia, Azerbaijan, Kazakhstan, Kyrgyzstan, Tajikistan, Turkmenistan and Uzbekistan. Archives are chosen by the event's historical jurisdiction and current record custodian; a regional example does not replace local research.

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

Release history: changelog.

Install

With Node.js installed, you can use the optional Skills CLI:

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

The CLI lets you choose your agent and installs into the current project by default; add -g for a personal installation across projects. See its documentation for current Node.js requirements.

Alternatively, clone the repository directly 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. Most scripts need only Python 3 and the standard library. The optional scan_montage.py helper needs Pillow; build_pdf.py needs a Chromium-based browser.

Use

Describe the family question. The agent works from available information and continues while questions or access requests await a reply. For example:

Keep private case data outside the skill's Git checkout. From the skill folder:

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   # SHA-256 for every saved artifact
python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-case             # check registers before the final report

init_case.py refuses to create a case inside the skill folder, including with --force. Git ignores common legacy case-folder names as an additional safeguard; check staged files before contributing, especially if moving an existing case.

The agent prepares a complete HTML report, for example my-case/report.html, using assets/report.template.html or its existing tools. The default editorial layout puts a family tree in the header, with relationship evidence one click away, readable multilingual system-font fallbacks, and layouts for small screens and print. The tree follows the available evidence; missing relatives do not delay the report. Open it directly in a browser or share the HTML with its local images. Short answers may remain text or Markdown; an explicitly requested format takes precedence. A family-facing report does not imply PDF.

Only when you explicitly request PDF, the agent can export the same HTML:

python scripts/build_pdf.py --html ~/kinship-cases/my-case/report.html --out ~/kinship-cases/my-case/report.pdf

This optional export needs Chrome, Chromium or Edge installed (or CHROME_PATH). With --png-dir it also renders pages to PNG for review if pypdfium2 is available. HTML delivery needs no PDF renderer.

For PDF export, use static HTML with local or embedded images. The exporter rejects active HTML and network image sources; source links remain clickable. A failed render preserves any existing output PDF.

Family trees in GEDCOM

GEDCOM is a standard format for exchanging genealogical data between programs. When you ask the agent to build or export a tree, it prepares a local .ged file with source citations and evidence notes. The default is GEDCOM 5.5.1 in UTF-8 for compatibility; use another supported version, such as GEDCOM 7, when you or your chosen program require it.

An existing tree is research input and a set of leads, not proof of its relationships. The agent preserves the original file and keeps unresolved claims, unsupported details, evidence registers and the search log in the case folder. Exports follow the evaluated evidence and do not overwrite your files.

You choose the software. Installing tree applications, configuring MCP connections and automatically synchronizing external trees are outside the skill's scope. See the GEDCOM workflow.

Repository layout

SKILL.md                         main instructions (workflow, hard rules, language policy)
references/
  source-strategy.md             source hierarchy, query patterns, catalogs, archive requests
  correspondence.md              recipients, mail integration, authorized sending and replies
  government-portals.md          civil-registration services and request delivery routes
  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, one CAPTCHA attempt and 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
  changelog.md                   release history
  photo-search.md                finding, identifying, dating and storing photos
  habsburg-galicia-bukovina.md   Galicia and Bukovina under the Habsburgs and after
  chechnya-deportation.md        Chechen families: 1944 deportation, special settlement, names and renamed villages
  germany-forced-labour.md       Forced labourers in Germany 1941-1945: Arolsen Archives and German civil registers

  bessarabia-moldova.md          Bessarabia, Moldova, MASSR and the Dniester borderland
  familysearch-indexes.md       targeted browser research, permitted local snapshots and coverage
  familysearch-mcp.md           connected tools, structured reads, scoped writes and verification
  ww1-search.md                 GWAR WWI person/locality search and source-image locators
  gedcom.md                     portable family-tree exports with sources and evidence notes
assets/                          case intake, CSV registers, final report template,
                                 photos README template, research-state template, HTML report template (report.template.html)
scripts/                         init_case.py, hash_artifact.py, audit_evidence.py, build_pdf.py
                                 familysearch.py, gwar.py, register_search.py, scan_montage.py (needs Pillow)
                                 check_gedcom.py (optional GEDCOM lint), and shared local analysis modules
evals/discovery-and-logic.yaml   trigger and reasoning test cases
tests/                           unit tests (python3 -m unittest discover -s tests)

Responsible use

Contributing

New sources are welcome in references/seed-sources.md. Record verified owner, jurisdiction, collection, provenance, IDs, access, restrictions and check date where known; mark gaps instead of guessing. Keep personal data out of examples.

When a readable search log is present, the audit summary lists artifact IDs without a search-log reference. Use the list to check unlinked finds. User-supplied material may appear there without any action needed.

Source-search helpers use Python's standard library and the existing case registers. Run python3 -m unittest discover -s tests to check local parsing, GWAR checkpoints, access failures, unresolved coverage and evidence registration against synthetic data. FamilySearch discovery and targeted viewing use the existing lawful browser session; its Python helpers analyze saved fragments. Keep private research files outside this checkout.

License

MIT © 2026 Denis Shiryaev.


Maintained by Denis Shiryaev (@DenisSergeevitch).

Special thanks to Viktor for the conversations about using Claude for family-history research that helped inspire this skill.

ex-ussr-kinship-research (DenisSergeevitch/ex-ussr-kinship-research)

正在搜索数据库…

这是什么?这是一项以证据为先的家谱研究技能,能让 AI 编程智能体(Codex、Claude Code)成为谨慎的家族史研究者,专门研究前苏联和俄罗斯帝国的历史,解读教会登记簿、民事、军事、流放和镇压档案。
这是我要运行的应用,还是我的编程智能体使用的技能文件?这是一项智能体技能(Agent Skill):一个包含说明、登记表和 Python 脚本的文件夹。你把它放进智能体的技能目录后,Codex 或 Claude Code 会将其作为研究方法来遵循,而不是把它当作独立程序运行。
运行随附的脚本需要什么?只需 Python 3 和标准库;可选的 buildpdf.py 报告生成器还需要基于 Chromium 的浏览器,例如 Chrome、Chromium 或 Edge。
它会拒绝做哪些事?它不会查询在世者当前的住址、电话或账户,不会绕过验证码、付费墙、地域限制或速率限制,也从不自行发送档案查询请求,只起草请求内容。
它如何处理敏感的家族数据?对于流放、镇压、收养或 DNA 意外发现等敏感信息,它会客观中立地报告,且只披露问题所需的程度;未经明确同意,绝不会将你的文件或 DNA 数据上传给第三方。
它如何区分已证实的事实和猜测?它会为每项主张标注可解释的证据状态(假设、单一来源、相互印证、强相互印证、相互矛盾、未解决),并将同一记录的副本或镜像归为一组,因此它们永远不会被当作独立证据。
它涵盖哪些国家和语言?涵盖前苏联全部 15 个加盟共和国(俄罗斯、乌克兰、白俄罗斯、波罗的海国家、高加索和中亚地区),并提供改革前俄语、乌克兰语、波兰语、罗马尼亚语、德语和意第绪语的姓名变体对照表;其说明文件为俄文,但智能体会用你的语言回复。
它会把两个同名的人混为一谈吗?不会。同名者会被分别保留为不同的人物编号,直到出现可以区分的证据,例如门牌号、父母、教父母、确切的出生日期或所属部队。
最终输出是什么样的?输出一份报告,逐条列出每一种亲属关系,包括矛盾之处、失败的查询和具体的后续步骤;另附一个审核脚本,在你依赖结论之前检查登记表和报告的引用完整性。
大小
2.2 MB
星标
2.6K
时长
24天
提交 · 90 天