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.