Skip to content
Conduit

skill

gedcom-agent-skill

Agent skill + zero-dependency Perl CLI (ged) to read, validate, repair and safely edit GEDCOM family-tree files

lukeramsden/gedcom-agent-skillcommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/lukeramsden/gedcom-agent-skill itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 23, 2026

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
statscounts, 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
doctorenvironment 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.

↑↓ navigate openesc close