Familysearch

Search and analyze family history using the FamilySearch API or offline GEDCOM files for genealogy, ancestors, family trees, and historical records.

Security Scan

The skill's code, instructions, and requirements align with its genealogy purpose (FamilySearch API + GEDCOM parsing); nothing in the files indicates unexpected credential access or hidden network endpoints.

Purpose & Capability

Name/description match the included scripts and SKILL.md. The Python scripts implement FamilySearch API calls and an offline GEDCOM parser, which are appropriate for the stated genealogy functionality.

Instruction Scope

SKILL.md instructs only FamilySearch OAuth token storage/retrieval and GEDCOM file usage. The runtime instructions and scripts operate on the FamilySearch API endpoints and user-supplied GEDCOM files; they do not attempt to read arbitrary system files or call unexpected external endpoints.

Install Mechanism

No install spec; this is instruction-plus-script only. No external downloads or package installs are requested, so nothing is written to disk beyond running the included scripts.

Credentials

No required environment vars are declared in the registry metadata. The SKILL.md documents an optional FAMILYSEARCH_TOKEN env var and macOS Keychain storage for tokens, and the script checks FAMILYSEARCH_TOKEN (and keychain as a fallback). This is proportionate to API mode. Minor inconsistency: SKILL.md mentions storing an app key and token; the included script only attempts to fetch the token from the environment or macOS Keychain (it does not perform a client-secret exchange locally).

Persistence & Privilege

Skill is not force-included (always: false) and does not request elevated platform privileges or modify other skills. It can be invoked by the agent, which is expected behavior for skills.

Assessment

This skill appears to do what it claims: call FamilySearch APIs (when you provide an OAuth token) and parse GEDCOM files you point it at. Before installing or running it, consider: (1) only provide a FAMILYSEARCH_TOKEN if you trust the skill and want live API lookups — the token will be used to call api.familysearch.org; (2) GEDCOM mode reads local files you specify, so don't point it at sensitive non-gedcom files; (3) the script uses the macOS 'security' tool as a convenience to read Keychain entries if available — it only tries that when no env var is set; (4) inspect the included scripts yourself (they are small and plain Python) if you have doubts. If you do not want the skill to access live FamilySearch data, simply use it in offline GEDCOM mode without setting FAMILYSEARCH_TOKEN.

FamilySearch Genealogy Skill

Two modes of operation:

1. Live API (primary) — Query FamilySearch directly for person search, pedigree, descendants, historical records
2. Offline GEDCOM — Parse exported .ged files for local exploration, narratives, and statistics

Mode 1: FamilySearch API (Primary)

Prerequisites

1. FamilySearch Account — Free at https://www.familysearch.org
2. Developer App Key — Register at https://www.familysearch.org/developers/
3. OAuth 2.0 Access Token — Via authentication flow below

Store credentials:

Option A — Environment variable (all platforms):

export FAMILYSEARCH_TOKEN="<TOKEN>"

Option B — macOS Keychain:

security add-generic-password -a "familysearch-app-key" -s "openclaw-familysearch" -w "<APP_KEY>"
security add-generic-password -a "familysearch-token" -s "openclaw-familysearch-token" -w "<TOKEN>"

The script checks FAMILYSEARCH_TOKEN env var first, then falls back to macOS Keychain.

Authentication

OAuth 2.0 Authorization Code flow:

1. Direct user to: https://ident.familysearch.org/cis-web/oauth2/v3/authorization?response_type=code&client_id={APP_KEY}&redirect_uri={REDIRECT_URI}
2. User logs in, grants access
3. Exchange code for token:

curl -X POST "https://ident.familysearch.org/cis-web/oauth2/v3/token" \
  -d "grant_type=authorization_code&code={AUTH_CODE}&client_id={APP_KEY}"

4. Store returned access_token in Keychain

Sandbox for testing: https://integration.familysearch.org / https://api-integ.familysearch.org

API Usage

python scripts/familysearch.py <command> [args]

Command	Description
search --given John --surname Lewis --birth-place Oregon	Search persons in Family Tree
person <PID>	Get person details
ancestry <PID> --generations 4	Ascending pedigree (1-8 generations)
descendants <PID> --generations 2	Descending tree
parents <PID>	Get parents
spouses <PID>	Get spouses
children <PID>	Get children

Search parameters: --given, --surname, --birth-date, --birth-place, --death-date, --death-place, --sex

Results use GEDCOM X format (JSON). Key fields: persons[].id, persons[].display.name, .birthDate, .birthPlace, .deathDate, .deathPlace.

Ahnentafel numbering in ancestry: 1=subject, 2=father, 3=mother, 4=paternal grandfather, etc.

Mode 2: Offline GEDCOM Files

For exported .ged files from FamilySearch, Ancestry, MyHeritage, etc. No API key needed — pure offline.

Getting a GEDCOM File

FamilySearch: familysearch.org → Family Tree → Tools → Export GEDCOM

Usage

python scripts/gedcom_query.py <gedcom_file> <command> [args...]

Command	Description
search <name>	Fuzzy name search — returns matches with IDs
person <id_or_name>	Full profile: birth, death, parents, spouses, children
ancestors <id_or_name> [depth]	Pedigree chart up (default: 4 generations)
descendants <id_or_name> [depth]	Pedigree chart down (default: 3 generations)
story <id_or_name>	Narrative biography paragraph
timeline <id_or_name>	Chronological life events
stats	Tree summary: counts, surnames, birth decades, completeness
find-date <year>	Find people born/died in a given year
common-ancestor <name1> <name2>	Find closest common ancestor

id_or_name: GEDCOM ID (e.g., I001) or partial name (fuzzy, case-insensitive).

Narrative Genealogy

Beyond data retrieval, this skill supports narrative genealogy — connecting facts to stories:

• Note occupations, migrations, life events when exploring a tree
• Cross-reference API/GEDCOM data with stories the user shares conversationally
• Build family narratives that explain why — not just dates and names
• Flag research opportunities: missing records, undocumented branches, conflicting dates
• Use story command (GEDCOM mode) for auto-generated biographical narratives

Agent Workflow

1. User asks about family history → Check if they have a FamilySearch account (API) or GEDCOM file (offline)
2. API mode: Search by name → get person ID → explore ancestry/descendants/relationships
3. GEDCOM mode: Load file → search → explore
4. Either mode: Combine structured data with user's oral history for richer narratives
5. Cross-reference: Use API to find records that fill gaps in GEDCOM data

Rate Limits & Best Practices

• FamilySearch API is free but rate-limited — cache results locally
• Never store FamilySearch usernames/passwords — OAuth tokens only
• Tokens expire; re-authenticate on 401 responses
• GEDCOM parser handles files up to ~100K individuals
• File encoding: auto-detects UTF-8 (with BOM), UTF-8, latin-1