GEDCOM Agent Skill

Give coding agents a safe, scriptable way to read, validate and edit GEDCOM family-tree files (.ged, versions 5.5 / 5.5.1 / 7.0).

The skill ships ged, a single-file Perl 5 CLI that uses only core modules. It runs on the /usr/bin/perl that comes with every macOS and virtually every Linux - nothing to install, no Xcode command line tools, no Python, no CPAN, no npm packages at runtime.

Why

GEDCOM is a line-oriented text format with cross-references that must stay consistent in both directions (FAMC<->CHIL, FAMS<->HUSB/WIFE). Hand-editing with sed or ad-hoc scripts silently corrupts trees: stray @, duplicate child lines, one-sided links. ged makes the safe path the easy path:

• Validates before and after every edit. Mutating commands refuse to run on a file that has errors and never write a change that would introduce one. Writes are atomic.
• Reciprocal links are automatic. link, new-indi --famc, new-fam --child, add all write both sides.
• Preserves what it does not touch - encoding (UTF-8, UTF-16, ANSEL/ ASCII passthrough), BOM, CRLF/LF, tag order, extension tags. Untouched files round-trip byte-for-byte.
• Repairs mechanical damage. ged repair fixes malformed pointers, duplicate links and missing reciprocals; nothing speculative.
• Rich validation. Dangling pointers, cycles, sex/role mismatch, dates that are not GEDCOM grammar, non-standard tags, implausible chronology (children born before parents, after a parent's death, etc.).
• Query and export. Ancestors, descendants, relationship path between two people, family sheet, source citations, stats; export to JSON, CSV, Graphviz DOT or Markdown. --json on every query.

Requirements

• Perl 5.14+ (macOS ships 5.34; Debian/Ubuntu/Fedora/Alpine all include perl or perl-base). Core modules only: Encode, Getopt::Long, File::Temp, List::Util, JSON::PP.

That is the whole list.

Install

As a pi package (also puts ged on your PATH via npm):

pi install npm:gedcom-agent-skill

With the Skills CLI:

npx skills add lukeramsden/gedcom-agent-skill@gedcom

Install globally for all supported agents:

npx skills add lukeramsden/gedcom-agent-skill@gedcom -g -a '*' -y

List the skills available in this repository without installing:

npx skills add lukeramsden/gedcom-agent-skill --list

Or just copy skills/gedcom/ged anywhere on your PATH.

Quick start

cd skills/gedcom
./ged doctor tree.ged                  # environment + file health
./ged check tree.ged                   # validate; exit 1 on errors
./ged repair tree.ged                  # fix mechanical breakage
./ged stats tree.ged
./ged find tree.ged 'ramsden'
./ged family tree.ged I12
./ged ancestors tree.ged I1 --depth 6
./ged path tree.ged I1 I57             # how are these two related?

./ged new-indi tree.ged --name 'Ellen /Cubbin/' --sex F --birth 'ABT 1808' \
                        --birth-place 'Isle of Man' --famc F9
./ged new-fam  tree.ged --husb I12 --wife I58 --marriage 1830-05-12
./ged set      tree.ged I58 DEAT.DATE 1871-02-01
./ged set      tree.ged I58 SOUR @S3@ && ./ged set tree.ged I58 SOUR.PAGE 'RG10/3921 f.44'
./ged export   tree.ged dot | dot -Tsvg -o tree.svg

Point at a file with -f FILE, a FILE.ged argument, $GED_FILE, or by having exactly one .ged in the working directory.

Commands

| Inspect | | |---|---| | check [--strict] [--verbose] | validate structure, pointers, reciprocity, chronology, tags, dates | | stats | counts, surnames, places, year range, unlinked people | | list [indi\|fam\|sour\|repo\|note\|obje\|all] | one line per record; --surname, --limit | | find <regex> [--all] | search names (or every field) | | show <xref>... | raw record block(s) | | family <xref> | parents, siblings, spouses, children, events, notes | | ancestors <xref> / descendants <xref> | indented trees; --depth N | | path <xref> <xref> | shortest relationship chain | | sources [<xref>...] | source citations with page and quality | | next-id [TYPE...] | next free xref, honouring the file's prefix and zero-padding scheme | | export [json\|json-raw\|csv\|dot\|md] | to stdout | | diff <a.ged> <b.ged> | record-level differences | | doctor | environment and file health |

| Create | | |---|---| | init <new.ged> | empty GEDCOM 5.5.1, UTF-8 | | new-indi --name 'Given /Surname/' ... | person, with events, occupations, notes, citations, links | | new-fam --husb I --wife I --child I ... | family, links written both ways | | new-sour --title T ... | source record | | add [FILE\|-] | raw GEDCOM record(s) with @NEW@ placeholders |

| Edit | | |---|---| | set <xref> <TAG.PATH> <value> | e.g. BIRT.DATE, OCCU[2], SOUR.PAGE; --append | | unset <xref> <TAG.PATH> | remove a substructure | | link / unlink child\|spouse <indi> <fam> | reciprocal lineage links | | remove <xref>... | delete records and scrub links; --force for other references | | rename <old> <new> | change an xref everywhere | | repair [--force] | malformed pointers, duplicate links, missing reciprocals | | fmt [--check] [--lf\|--crlf] | normalise line endings and CONC/CONT wrapping |

Dates accept ISO (1850-03-12, 1850-03, 1850) and are converted to GEDCOM (12 MAR 1850); GEDCOM qualifiers (ABT, BEF, BET ... AND ...) pass through.

Tests

/bin/bash tests/run.sh

Eighty-odd end-to-end assertions using only /bin/bash 3.2 and /usr/bin/perl, the same constraints as the tool.

Repository layout

skills/
└── gedcom/
    ├── SKILL.md                        # agent-facing instructions and command reference
    ├── ged                             # the CLI (Perl 5 core only, executable)
    └── reference/
        └── gedcom-cheatsheet.md        # tag reference and record templates
examples/sample.ged                     # small valid tree to try commands on
tests/run.sh                            # end-to-end tests

License

MIT. See NOTICE for trademark attribution.

Releasing

npm version patch|minor|major && git push --follow-tags

The v* tag triggers .github/workflows/publish.yml, which runs the tests and publishes to npm with OIDC trusted publishing and provenance.