{"id":"3b507951-f385-4d49-a711-063e85403152","slug":"gedcom-agent-skill","kind":"skill","name":"gedcom-agent-skill","summary":"Agent skill + zero-dependency Perl CLI (ged) to read, validate, repair and safely edit GEDCOM family-tree files","owner":"lukeramsden","repoUrl":"https://github.com/lukeramsden/gedcom-agent-skill","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-09-02T14:39:14.000Z","addedAt":"2026-10-21T11:33:54.470Z","logoUrl":"https://avatars.githubusercontent.com/u/13789719?u=03cbdcc76cf1ff64c5f0d5cf9d441ab5a4640fad&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","files-documents"],"tags":["claude-code","family-tree","gedcom","genealogy","perl"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T22:45:10.129Z","sample":false,"url":"https://conduits.dev/tools/gedcom-agent-skill","language":"Perl","transports":["stdio"],"install":{"npm":"gedcom-agent-skill"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# GEDCOM Agent Skill\n\nGive coding agents a safe, scriptable way to read, validate and edit GEDCOM\nfamily-tree files (`.ged`, versions 5.5 / 5.5.1 / 7.0).\n\nThe skill ships `ged`, a single-file Perl 5 CLI that uses only core modules.\nIt runs on the `/usr/bin/perl` that comes with every macOS and virtually\nevery Linux - nothing to install, no Xcode command line tools, no Python, no\nCPAN, no npm packages at runtime.\n\n## Why\n\nGEDCOM is a line-oriented text format with cross-references that must stay\nconsistent in both directions (`FAMC`<->`CHIL`, `FAMS`<->`HUSB`/`WIFE`).\nHand-editing with `sed` or ad-hoc scripts silently corrupts trees: stray\n`@`, duplicate child lines, one-sided links. `ged` makes the safe path the\neasy path:\n\n- **Validates before and after every edit.** Mutating commands refuse to run\n  on a file that has errors and never write a change that would introduce\n  one. Writes are atomic.\n- **Reciprocal links are automatic.** `link`, `new-indi --famc`, `new-fam\n  --child`, `add` all write both sides.\n- **Preserves what it does not touch** - encoding (UTF-8, UTF-16, ANSEL/\n  ASCII passthrough), BOM, CRLF/LF, tag order, extension tags. Untouched\n  files round-trip byte-for-byte.\n- **Repairs mechanical damage.** `ged repair` fixes malformed pointers,\n  duplicate links and missing reciprocals; nothing speculative.\n- **Rich validation.** Dangling pointers, cycles, sex/role mismatch, dates\n  that are not GEDCOM grammar, non-standard tags, implausible chronology\n  (children born before parents, after a parent's death, etc.).\n- **Query and export.** Ancestors, descendants, relationship path between\n  two people, family sheet, source citations, stats; export to JSON, CSV,\n  Graphviz DOT or Markdown. `--json` on every query.\n\n## Requirements\n\n- Perl 5.14+ (macOS ships 5.34; Debian/Ubuntu/Fedora/Alpine all include\n  perl or `perl-base`). Core modules only: `Encode`, `Getopt::Long`,\n  `File::Temp`, `List::Util`, `JSON::PP`.\n\nThat is the whole list.\n\n## Install\n\nAs a [pi](https://github.com/earendil-works/pi-coding-agent) package (also puts `ged` on your PATH via npm):\n\n```bash\npi install npm:gedcom-agent-skill\n```\n\nWith the Skills CLI:\n\n```bash\nnpx skills add lukeramsden/gedcom-agent-skill@gedcom\n```\n\nInstall globally for all supported agents:\n\n```bash\nnpx skills add lukeramsden/gedcom-agent-skill@gedcom -g -a '*' -y\n```\n\nList the skills available in this repository without installing:\n\n```bash\nnpx skills add lukeramsden/gedcom-agent-skill --list\n```\n\nOr just copy `skills/gedcom/ged` anywhere on your `PATH`.\n\n## Quick start\n\n```bash\ncd skills/gedcom\n./ged doctor tree.ged                  # environment + file health\n./ged check tree.ged                   # validate; exit 1 on errors\n./ged repair tree.ged                  # fix mechanical breakage\n./ged stats tree.ged\n./ged find tree.ged 'ramsden'\n./ged family tree.ged I12\n./ged ancestors tree.ged I1 --depth 6\n./ged path tree.ged I1 I57             # how are these two related?\n\n./ged new-indi tree.ged --name 'Ellen /Cubbin/' --sex F --birth 'ABT 1808' \\\n                        --birth-place 'Isle of Man' --famc F9\n./ged new-fam  tree.ged --husb I12 --wife I58 --marriage 1830-05-12\n./ged set      tree.ged I58 DEAT.DATE 1871-02-01\n./ged set      tree.ged I58 SOUR @S3@ && ./ged set tree.ged I58 SOUR.PAGE 'RG10/3921 f.44'\n./ged export   tree.ged dot | dot -Tsvg -o tree.svg\n```\n\nPoint at a file with `-f FILE`, a `FILE.ged` argument, `$GED_FILE`, or by\nhaving exactly one `.ged` in the working directory.\n\n## Commands\n\n| Inspect | |\n|---|---|\n| `check [--strict] [--verbose]` | validate structure, pointers, reciprocity, chronology, tags, dates |\n| `stats` | counts, surnames, places, year range, unlinked people |\n| `list [indi\\|fam\\|sour\\|repo\\|note\\|obje\\|all]` | one line per record; `--surname`, `--limit` |\n| `find <regex> [--all]` | search names (or every field) |\n| `show <xref>...` | raw record block(s) |\n| `family <xref>` | parents, siblings, spouses, children, events, notes |\n| `ancestors <xref>` / `descendants <xref>` | indented trees; `--depth N` |\n| `path <xref> <xref>` | shortest relationship chain |\n| `sources [<xref>...]` | source citations with page and quality |\n| `next-id [TYPE...]` | next free xref, honouring the file's prefix and zero-padding scheme |\n| `export [json\\|json-raw\\|csv\\|dot\\|md]` | to stdout |\n| `diff <a.ged> <b.ged>` | record-level differences |\n| `doctor` | environment and file health |\n\n| Create | |\n|---|---|\n| `init <new.ged>` | empty GEDCOM 5.5.1, UTF-8 |\n| `new-indi --name 'Given /Surname/' ...` | person, with events, occupations, notes, citations, links |\n| `new-fam --husb I --wife I --child I ...` | family, links written both ways |\n| `new-sour --title T ...` | source record |\n| `add [FILE\\|-]` | raw GEDCOM record(s) with `@NEW@` placeholders |\n\n| Edit | |\n|---|---|\n| `set <xref> <TAG.PATH> <value>` | e.g. `BIRT.DATE`, `OCCU[2]`, `SOUR.PAGE`; `--append` |\n| `unset <xref> <TAG.PATH>` | remove a substructure |\n| `link` / `unlink child\\|spouse <indi> <fam>` | reciprocal lineage links |\n| `remove <xref>...` | delete records and scrub links; `--force` for other references |\n| `rename <old> <new>` | change an xref everywhere |\n| `repair [--force]` | malformed pointers, duplicate links, missing reciprocals |\n| `fmt [--check] [--lf\\|--crlf]` | normalise line endings and CONC/CONT wrapping |\n\nDates accept ISO (`1850-03-12`, `1850-03`, `1850`) and are converted to\nGEDCOM (`12 MAR 1850`); GEDCOM qualifiers (`ABT`, `BEF`, `BET ... AND ...`)\npass through.\n\n## Tests\n\n```bash\n/bin/bash tests/run.sh\n```\n\nEighty-odd end-to-end assertions using only `/bin/bash` 3.2 and\n`/usr/bin/perl`, the same constraints as the tool.\n\n## Repository layout\n\n```text\nskills/\n└── gedcom/\n    ├── SKILL.md                        # agent-facing instructions and command reference\n    ├── ged                             # the CLI (Perl 5 core only, executable)\n    └── reference/\n        └── gedcom-cheatsheet.md        # tag reference and record templates\nexamples/sample.ged                     # small valid tree to try commands on\ntests/run.sh                            # end-to-end tests\n```\n\n## License\n\nMIT. See [NOTICE](NOTICE) for trademark attribution.\n\n## Releasing\n\n```bash\nnpm version patch|minor|major && git push --follow-tags\n```\n\nThe `v*` tag triggers `.github/workflows/publish.yml`, which runs the tests\nand publishes to npm with OIDC trusted publishing and provenance.\n"}