Skip to content
Back to search

agentic-genealogy

MarketplaceWorks with Claude CodeGitHub

Unofficial community skills for family-history research with Claude Code: sessions, searches, evidence, transcription, agent waves, family graph

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pavel-kravchenko--agentic-genealogy/badge.svg)](/listings/pavel-kravchenko--agentic-genealogy)

HTML

<a href="/listings/pavel-kravchenko--agentic-genealogy"><img src="/api/listings/pavel-kravchenko--agentic-genealogy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Claude Code and Python 3.9 or later. Clone this repository into a folder named `agentic-genealogy`, then install the skills ([`docs/setup.md`](docs/setup.md) has the details):

claude plugin marketplace add ./agentic-genealogy
claude plugin install genealogy@agentic-genealogy

For one session without installing: `claude --plugin-dir ./agentic-genealogy/plugins/genealogy`.

The tools can be tried on the invented family. From the repository folder:

python3 tools/graph/check_graph.py --persons examples/sample-family/persons.json --links examples/sample-family/links.json

It reports 0 errors, 2 findings and 8 field states; the two findings are contradictions placed in the sample on purpose.

To start your own project, ask Claude in an empty folder: "Set up a family-history project here". It builds the project skeleton (an entry file, a journal, five ledgers and a folder tree) and asks for the family's own rules, such as how living people appear. Before the first search, read [`docs/resources/README.md`](docs/resources/README.md), the guide for your region and [Access and responsibility](#access-and-responsibility) below.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "agentic-genealogy",
  3. "description": "Unofficial community skills for family-history research with Claude Code: sessions, searches, evidence, transcription, agent waves, family graph",
  4. "owner": {
  5. "name": "agentic-genealogy contributors"
  6. },
  7. "plugins": [
  8. {
  9. "name": "genealogy",
  10. "source": "./plugins/genealogy",
  11. "description": "Research discipline for agentic genealogy: ledgers, block-versus-zero searches, identification rules, transcription, incoming material, agent waves, family graph, privacy check"
  12. }
  13. ]
  14. }
README.md · README · 210 lines
  1. <p align="center">
  2. <img src="assets/logo.svg" width="620" alt="agentic genealogy: a method for family history research with AI agents">
  3. </p>
  4. <p align="center">
  5. <a href="docs/approach.md">Approach</a> ·
  6. <a href="docs/setup.md">Setup</a> ·
  7. <a href="docs/method/">Method</a> ·
  8. <a href="docs/resources/README.md">Resources</a> ·
  9. <a href="docs/errors-and-solutions.md">Errors and solutions</a> ·
  10. <a href="CONTRIBUTING.md">Contributing</a>
  11. </p>
  12. Working notes, Claude Code skills and small offline tools for family-history research with AI agents. They
  13. come from one family's project in 2026, with ancestors in the former Russian Empire and USSR, and are shared
  14. so that other researchers can use them, correct them and add what they have learned.
  15. An agent is useful in this work: it reads the finding aids that archives publish, tries many spellings of one
  16. village, transcribes a register line by line and keeps a ledger. Two of its mistakes are hard to see. An empty
  17. answer from a site that refused the request reads like "no such person", and a record with the right name
  18. reads like the right person. Most of the rules collected here guard against these two.
  19. ## What is here
  20. <p align="center">
  21. <img src="assets/structure.svg" width="100%" alt="The four parts of the repository: docs (the method and the guides), plugins/genealogy (ten skills for Claude Code), tools (offline Python tools), examples/sample-family (an invented family)">
  22. </p>
  23. | Path | What it is |
  24. |---|---|
  25. | [`docs/approach.md`](docs/approach.md) | the method in two pages: six principles and the working loop |
  26. | [`docs/setup.md`](docs/setup.md) | software, installing the skills, project layout, limits we ran into |
  27. | [`docs/method/`](docs/method/) | ten guides: evidence rules, reading indexes and OCR, block versus zero, invalid zeros and false trails, transcription, the family graph and GEDCOM, incoming material, agent waves, document builds, the ledger of dead ends |
  28. | [`docs/resources/`](docs/resources/) | thirteen guides to archives and databases, by country (Russia, Belarus, Ukraine, Estonia, Latvia, Poland, Lithuania, Czechia, Germany) and by topic (war and losses, repression, full-text archives, libraries, genealogy services), with an index: what each source holds, how it was reached, how it signals a refusal, its traps |
  29. | [`docs/errors-and-solutions.md`](docs/errors-and-solutions.md) | a catalogue of about two hundred errors: symptom, cause, fix |
  30. | [`plugins/genealogy/`](plugins/genealogy/) | a Claude Code plugin with ten skills, the project templates and a brief template for agent waves |
  31. | [`tools/`](tools/) | nine offline Python tools that work on files you already have: image strips for handwriting, audio transcription, source coverage, a tolerant search over OCR text, graph checks, duplicate merging, GEDCOM in and out, a privacy scanner |
  32. | [`examples/sample-family/`](examples/sample-family/) | an invented family of 19 persons and 30 links to run the tools on |
  33. ## Getting started
  34. You need Claude Code and Python 3.9 or later. Clone this repository into a folder named `agentic-genealogy`,
  35. then install the skills ([`docs/setup.md`](docs/setup.md) has the details):
  36. ```bash
  37. claude plugin marketplace add ./agentic-genealogy
  38. claude plugin install genealogy@agentic-genealogy
  39. ```
  40. For one session without installing: `claude --plugin-dir ./agentic-genealogy/plugins/genealogy`.
  41. The tools can be tried on the invented family. From the repository folder:
  42. ```bash
  43. python3 tools/graph/check_graph.py --persons examples/sample-family/persons.json --links examples/sample-family/links.json
  44. ```
  45. It reports 0 errors, 2 findings and 8 field states; the two findings are contradictions placed in the sample
  46. on purpose.
  47. To start your own project, ask Claude in an empty folder: "Set up a family-history project here". It builds
  48. the project skeleton (an entry file, a journal, five ledgers and a folder tree) and asks for the family's own
  49. rules, such as how living people appear. Before the first search, read
  50. [`docs/resources/README.md`](docs/resources/README.md), the guide for your region and
  51. [Access and responsibility](#access-and-responsibility) below.
  52. ## The main rules
  53. <p align="center">
  54. <img src="assets/outcomes.svg" width="100%" alt="Three outcomes of a search. Result: a record is found. True zero: the search is proven to have run and found nothing. Block: a refusal that looks like nothing found; the agent stops and a person decides">
  55. </p>
  56. 1. **A search has three outcomes: a result, a true zero and a block.** A block usually looks like a zero. A zero
  57. counts when the search is proven to have run, and it closes one record genre in one corpus under the
  58. spellings tried. [`block-vs-zero.md`](docs/method/block-vs-zero.md),
  59. [`invalid-zeros-and-false-trails.md`](docs/method/invalid-zeros-and-false-trails.md)
  60. 2. **A name is not an identifier.** The same given name, patronymic and surname recur in one village. Identity
  61. needs a document, or household, parish and confession agreeing; until then two records stay two persons
  62. with a weak link. [`evidence-rules.md`](docs/method/evidence-rules.md)
  63. 3. **The files are the memory.** Sessions and agents share only the project folder. An entry file, a journal
  64. and five ledgers (facts, dead ends, open questions, sources, know-how) hold the state. A session reads the
  65. entry file, the journal, the dead ends and the open questions before it searches, and writes all of them as
  66. the work goes. [`approach.md`](docs/approach.md), [`dead-ends.md`](docs/method/dead-ends.md)
  67. 4. **The agent prepares, a person decides.** A new document gets an analysis that changes nothing and ends with
  68. the question "enter it?". What is said about the living, what is published and what is sent to a stranger
  69. are a person's decisions. [`incoming-material.md`](docs/method/incoming-material.md)
  70. An example with invented names. The question is the baptism of Ivan Primerov, born about 1874 in the village
  71. of Primerovka. An answer in the shape these rules ask for:
  72. > **Before searching.** The ledger of dead ends already holds a closed search for this parish, 1870-1880,
  73. > under two spellings. Three spellings are new: Примеров, Примерав, Primerow.
  74. >
  75. > **First source: result.** One entry in 1874, read from the image. The name and the year fit, but the entry
  76. > names a father we have no document for, so this is not yet proven to be our Ivan.
  77. >
  78. > **Second source: true zero.** The control query returned records, so the search ran. This closes baptisms
  79. > for 1870-1880 in this one index under these three spellings.
  80. >
  81. > **Third source: block.** A login form in place of a result list. It goes on the researcher's list, for their
  82. > own browser.
  83. >
  84. > **Nothing has been changed.** Enter the 1874 entry as a separate person, with a possible link to our Ivan?
  85. ## How the work runs
  86. <p align="center">
  87. <img src="assets/loop.svg" width="100%" alt="The working loop in eight steps: read the ledgers; pick a lead; place and spellings; search where the site's terms allow and prove the search ran; read the image; analysis without edits, where a person decides; scripted entry; update the ledgers and commit">
  88. </p>
  89. Every session reads the ledgers before it searches and writes them as it goes. The agent prepares the analysis
  90. and asks; what a document changes in the family record is decided by a person (step 6). An accepted entry is
  91. made by a script, with a snapshot before it and checks after it. When many independent leads exist, the search
  92. step fans out into a wave of agents, each with its own site and its own report file. The loop is described in
  93. [`docs/approach.md`](docs/approach.md).
  94. ## Who can reach a source
  95. <p align="center">
  96. <img src="assets/reach.svg" width="100%" alt="Four reach classes. Open page: a public page reached without a login; check the site's terms before an agent reads it. Own browser: used by the researcher in person. Human only: a captcha, a payment, a letter or a visit. Dead: gone, or no longer the institution's site">
  97. </p>
  98. Sites in the resource guides carry one of these four classes, or a dated note where a site gave no answer.
  99. A class records how a site was reached in 2026. What the site's terms of use allow is for you to check before
  100. an agent reads anything (see [Access and responsibility](#access-and-responsibility)).
  101. ## Skills and guides
  102. Each procedure is a skill that Claude loads when its situation arises, and a guide that explains why the
  103. rule exists.
  104. | When | Skill | Guide |
  105. |---|---|---|
  106. | starting a project | `setting-up-a-project` | [`setup.md`](docs/setup.md) |
  107. | beginning, resuming or closing a session | `starting-a-research-session` | [`approach.md`](docs/approach.md), [`dead-ends.md`](docs/method/dead-ends.md) |
  108. | searching a database, a catalogue or an index | `searching-a-source` | [`block-vs-zero.md`](docs/method/block-vs-zero.md), [`reading-indexes-and-ocr.md`](docs/method/reading-indexes-and-ocr.md) |
  109. | deciding whether two records are one person | `identifying-people` | [`evidence-rules.md`](docs/method/evidence-rules.md) |
  110. | reading a handwritten record or a recording | `reading-old-records` | [`transcription.md`](docs/method/transcription.md) |
  111. | a new document or a relative's statement arrives | `taking-in-new-material` | [`incoming-material.md`](docs/method/incoming-material.md) |
  112. | changing the family graph, importing or exporting GEDCOM | `maintaining-the-family-graph` | [`family-graph-and-gedcom.md`](docs/method/family-graph-and-gedcom.md) |
  113. | sending several agents out in parallel | `running-a-research-wave` | [`agent-waves.md`](docs/method/agent-waves.md) |
  114. | writing to an archive or to a person | `writing-to-archives-and-people` | [`needs-a-human.md`](docs/resources/needs-a-human.md) |
  115. | before anything leaves the private project | `checking-privacy-before-sharing` | [`tools/privacy/`](tools/privacy/) |
  116. | building a book or a report from the project | | [`document-builds.md`](docs/method/document-builds.md) |
  117. ## What stays with the researcher
  118. - **Logins, captchas and paywalls.** These steps go on a list for a person, with a clear hand-over.
  119. - **Who an ancestor is.** The agent lays out the evidence and says what is proven and what is open.
  120. - **Letters to relatives.** The researcher writes them, in their own words and saying that AI helped; the
  121. agent supplies the facts and the questions.
  122. - **Each site's terms of use.** They are checked site by site before an agent reads anything.
  123. - **What is published.** What is said about the living and what leaves the project are a person's decisions.
  124. ## Contributing
  125. These notes describe sites as they were seen from one network in 2026, and they cover the regions one family
  126. needed. They get better with other people's observations. What helps most:
  127. - a dated correction to a site's behaviour: it moved, closed, changed its refusal page, added an index;
  128. - a guide for a region or an archive that is missing, in the same shape as the existing ones;
  129. - an error you ran into, as a row for the catalogue: symptom, cause, fix.
  130. The rules are in [`CONTRIBUTING.md`](CONTRIBUTING.md): invented names in examples, issues and pull requests;
  131. what a visitor sees on public pages and the official routes; observations with a month and a year.
  132. ## Access and responsibility
  133. Where a site's terms of use and robots rules allow it, an agent may read its public pages the way a visitor
  134. does: one site at a time, one request at a time, slowly, stopping at the first refusal and never retrying in
  135. a loop. Checking those terms, and the law that applies to you, is your responsibility; when in doubt, use
  136. the site yourself in your browser.
  137. Anything behind a login, a subscription or a captcha is used by the researcher personally, in their own
  138. browser. The guides describe what a visitor sees on public pages and the official routes: a written request,
  139. a library copy, a visit. Where a site refuses, the agent stops and the step passes to a person.
  140. A conversation with a relative is recorded only with the knowledge and consent of everyone who speaks in
  141. it. Before anything about living people leaves the private project, read the privacy skill named below.
  142. ## Good to know
  143. **The examples are invented.** They are composed illustrations: the patterns come from real work, and every
  144. surname, village and shelf mark in them is invented (the Primerov and Obraztsov families, the village of
  145. Primerovka, the Näidis and Paraugs families). Any resemblance to real persons is coincidental.
  146. **Sites change.** Every statement about a site's behaviour is a dated observation from 2026, with the month
  147. where the notes give one; for a site that gave no answer the guides give the official alternative. Treat the
  148. guides as a starting point, record your own dated observations in your project's `SOURCES.md`, and trust yours
  149. over ours.
  150. **Privacy.** If you publish anything derived from your own research, read
  151. [`checking-privacy-before-sharing`](plugins/genealogy/skills/checking-privacy-before-sharing/SKILL.md)
  152. first. This repository was prepared that way: examples written with an invented cast, and a deny-list
  153. built from the private data scanned against every file before publication.
  154. **Disclaimer.** This is an independent, unofficial project. The names and trademarks of the services and
  155. institutions it mentions belong to their owners. The material is provided as it is; the full terms are in
  156. [`DISCLAIMER.md`](DISCLAIMER.md).
  157. **Corrections and removal.** If you represent an institution, or you are a person affected by something
  158. written here, and you want a statement corrected or removed, open an issue in this repository and name the
  159. file and the passage. Every request is reviewed, and a passage that is inaccurate or a mention that is not
  160. wanted is corrected or removed. Keep personal data out of the issue itself; if the request needs it, say so in
  161. the issue and a private channel will be arranged.
  162. **Licence.** Everything under `tools/` and `examples/` (code, its README files, the schema) is under the MIT
  163. licence, see [`LICENSE`](LICENSE). Everything else (`docs/`, the skills and templates in `plugins/`, the
  164. graphics in `assets/`, this file) is under Creative Commons Attribution 4.0, see
  165. [`LICENSE-docs`](LICENSE-docs). The project templates may be copied into your own project without attribution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.