The Heartwood GPS skill

A short, downloadable guide that teaches a connected AI assistant to research the way a professional genealogist would — state the question, plan the sources, log every search, and stay explicit about what's still unconfirmed — instead of improvising. Entirely optional: Connect your AI works exactly the same without it, and this page assumes you've already done that.

What it is

The skill wires the Genealogical Proof Standard (GPS) and Evidence Explained's Source → Information → Evidence → conclusion layering to Heartwood's own MCP verbs — reasonably exhaustive search, complete and accurate citation, correlation of evidence, resolution of conflicts, and a soundly written conclusion. Every verb it names is a real, shipped Heartwood tool, prompt, or resource; nothing in it promises a capability the app doesn't back. It states an orientation-first workflow (never re-derive the state of a long investigation by re-reading records — open with a state summary instead), a capture-as-you-go discipline (the research log is a byproduct, not a separate chore), and named-up-front rules about what the engine will refuse an agent — a closed research question, a proof argument built on a pending assertion, and the handful of writes that are always human-only.

No lock-in. Every verb the skill names is independently callable and independently documented in Heartwood's MCP catalog — none of it exists only inside this file, and no tool's behavior changes based on whether you're using it. You can ignore, edit, fork, or replace it entirely and still reach every Heartwood capability by reading the tool catalog directly. If you already run a different research method, use it instead.

Get it

The skill is one plain-text file: heartwood-gps-skill.md. There's nothing to install beyond dropping that file where your assistant reads instructions from — see your assistant below.

Wire it into your assistant

The one method that works with any assistant, verified because it needs nothing assistant-specific: open the file above and paste its contents into your session (or point your assistant at its URL) before you start researching. That's a per-session step. The tabs below are the standing, do-it-once alternative for the assistants "Connect your AI" already covers — written up from each vendor's own docs on custom instructions/ project files, except Claude Code, which we've verified directly (it's the tool this skill file's own format targets). Treat the vendor's docs link as the final word if anything looks off.

Claude Desktop

Claude's apps support uploading a skill file directly (Settings → Capabilities → Skills on a plan that includes Skills) — upload heartwood-gps-skill.md there and it applies to every conversation. We haven't verified this ourselves end to end, so if the menu doesn't match, use the universal paste-at-session- start method above instead, or see Claude's Skills documentation.

Claude Code

Claude Code loads a skill from a SKILL.md file under a skills/ directory it discovers automatically — this is the one client below we've verified directly, since it's the format the downloaded file already ships in. Save it as:

.claude/skills/heartwood-gps/SKILL.md      # this project only
~/.claude/skills/heartwood-gps/SKILL.md    # every project

No restart needed — Claude Code picks up a new skill file the next time it looks for one. Claude Code's skills documentation.

ChatGPT & Codex

Neither has a dedicated "skill file" slot the way Claude Code does. The closest standing equivalent is custom instructions (ChatGPT: Settings → Personalization) or an AGENTS.md/.codex/instructions.md project file Codex reads automatically — paste the skill's contents into whichever your workflow already uses. We haven't verified either path ourselves; the universal paste-at-session- start method above always works as a fallback.

Gemini CLI

Gemini CLI reads a GEMINI.md context file from your project root (or ~/.gemini/GEMINI.md for every project) automatically at session start — paste the skill's contents in there, under its own heading. We haven't verified this ourselves; see Gemini CLI's context-file documentation if anything looks off.

Any other assistant

Look for that assistant's own standing instructions mechanism — custom instructions, a project/memory file, or an uploadable skill — and drop the file's contents in there the way you would any other reference material. If it has none, the universal paste-at-session-start method above works everywhere, every time.

The MCP verbs it drives

Every verb the skill references is documented in the MCP reference — project.state.get and the resume-investigation prompt for orientation, settled.list for what not to re-derive, research.log.capture for the research log, proof.argument.record for the one human-reviewed write in the workflow, and the rest of the question/plan/log/ capture verbs in between.