Skip to content
Get packs

Guide · Agent skill

How to use the Migrate Notes into GBrain agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The migrate skill is a set of instructions that an AI agent (such as Claude) follows when you ask it to move your notes or wiki into GBrain. It covers Obsidian, Notion, Logseq, plain markdown, CSV, JSON and Roam sources. This guide explains what the skill does, how to install it, how to phrase a request that triggers it, and what to check before and after an import.

Migrate Notes into GBraingarrytan/gbrain · MIT

Quick start

  1. 1Install GBrain and the skill. Install the gbrain command-line tool, then place the migrate skill folder in ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
  2. 2Initialize your brain. For company repository imports, make sure a GBrain brain is initialized on a trusted host. Personal imports need GBrain available with access to your source files.
  3. 3Ask for the migration. Use a request such as "import from obsidian" or "import from notion" and give the path to your source files.
  4. 4Review the sample. Let the agent import 5-10 files and read them back. Check that titles, tags and links look right before continuing.
  5. 5Approve and run the bulk import. Approve the preview if one is shown. The agent then imports the full directory without modifying your source files.
  6. 6Run the health check. Compare page counts, check for orphans and missing embeddings, and run a test search. Keyword search works even if embeddings are not yet created.

What is an agent skill, and what does migrate make the agent do?

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for one kind of task. When a request matches the skill, the agent reads those instructions and follows them. The migrate skill is named migrate and belongs to the garrytan/gbrain project under plugin/skills/migrate. It is licensed MIT.

When you ask the agent to move your notes into GBrain, the skill tells it to check the source format first, test on a small sample of 5-10 files, import the rest, and verify the results by reading pages back. It also converts links such as Obsidian wikilinks and Logseq block references into GBrain links, and runs a health check afterward. The skill states that source files are never modified or deleted; migration is additive only.

Install the migrate skill from the ZIP or the Claude apps

Option 1: download the ZIP of the skill from this page and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

Before you start, make sure GBrain is installed with the gbrain command-line tool and that you have access to your source files. For company repository imports, a GBrain brain must already be initialized on a trusted host.

  • Personal use: ~/.claude/skills/
  • Single project: .claude/skills/ inside the project
  • Claude apps: Settings → Capabilities → Skills

Trigger the skill with a natural request

The skill is triggered by phrases such as "migrate from", "import from obsidian", "import from notion", "connect our company brain", "connect our existing company brain" and "import an existing company brain". You do not need to use the exact words, but including one of these phrases makes the match more likely.

Name the source and the destination in your request. The agent will ask you to confirm details such as the source format and the file location.

  • "Import from Obsidian: my vault is at ~/Notes/Vault"
  • "Import from Notion. I exported it as Markdown & CSV."
  • "Connect our existing company brain from the Git checkout at ~/company-repo"

Supported sources and how each is handled

The skill lists seven source types. Obsidian is imported as a markdown directory, with [[wikilinks]] converted to GBrain links and #tags becoming GBrain tags. Notion exports (Markdown & CSV) have their UUIDs stripped from filenames for clean slugs. Logseq block references are converted to page links. CSV rows become pages, with a chosen column used as the slug and another as the notes. JSON keys are mapped to page fields, and Roam JSON exports have their block structure converted to pages.

  • Obsidian: markdown plus [[wikilinks]]; attachments such as images and PDFs are noted but handled separately
  • Notion: export via Settings > Export > Markdown & CSV
  • Logseq: markdown with ((block refs))
  • Plain markdown: any .md directory is imported directly
  • CSV: for contact or CRM lists, each row becomes a page
  • JSON and Roam JSON: keys and block structure are mapped to pages

Run the sample test and bulk import

The skill requires a sample test before any bulk import. The agent imports 5-10 files, reads them back from GBrain and checks them. Only after that does it import the full directory. For Obsidian, the skill includes a preview command for linking notes before you commit the changes.

If the sample looks wrong, the skill's guidance is to fix the mapping before importing more, because cleaning up many bad pages is costly.

gbrain extract links --source db --dry-run | head -20 # preview gbrain extract links --source db # commit

Verify the migration and build links

After any migration, the skill asks the agent to compare the GBrain page count with the source, check health for orphans and missing embeddings, export pages for round-trip checks, spot-check 5-10 pages, and run a search. Cross-references from the source system are converted to GBrain links so the knowledge graph is preserved.

For an existing company Git repository, the skill uses a separate workflow. It begins with a demo, inspects the committed checkout, asks for operator approval of a connect preview, and reports a durable receipt. Only a COMPLETE result means the pipeline verified.

  • Page count compared with source
  • Health check for orphans and missing embeddings
  • Spot-check and search test
  • Company repositories: operator approval before the connect step is rerun with --yes

What people use it for

  • Moving an Obsidian vault with wikilinks and tags into GBrain as searchable pages
  • Importing a Notion export after stripping UUIDs from filenames
  • Turning a Logseq graph with block references into linked pages
  • Loading a CSV contact or CRM export so each row is a searchable page
  • Connecting an existing company Git repository to a GBrain instance on a trusted host

Frequently asked questions

Is the migrate skill free to use?

The skill is published under the MIT licence in the garrytan/gbrain project. The source does not state any price, so check the project for its terms of use. The skill itself does not name any API keys.

What do I need to run the migrate skill?

You need GBrain installed with the gbrain command-line tool and access to your source files, such as an Obsidian vault, Notion export, CSV, JSON, Roam export or Git checkout. Company repository imports also need an initialized GBrain brain on a trusted host and operator approval for the connect preview.

Will migrate delete or change my original notes?

No. The skill states that source data is never modified or deleted and that migration is additive only. Company repository imports also never fix source files or commit changes automatically.

Which note apps does the skill support?

It supports Obsidian, Notion, Logseq, plain markdown, CSV, JSON and Roam. It only targets GBrain tools such as put_page, search and sync_brain, so it does not work directly with other note apps.

Why does search only find keywords after my import?

The skill says missing embeddings after an import are expected, and backfill may be blocked by the source profile. Until embeddings exist, search runs keyword-only.

How do I install the migrate skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you run GBrain and want an agent to move an Obsidian vault, Notion export, Logseq graph or CSV/JSON export into it with a sample test, link conversion and verification. Pick something else if you do not use GBrain, want direct integration with other note apps, or plan to import sensitive private data without reviewing it first.

Download the skill