How to use the schema-unify agent skill (gbrain)

What the schema-unify skill makes the agent do

The skill is a step-by-step playbook for an agent managing a gbrain brain. It moves the brain from the gbrain-base pack to gbrain-base-v2, a taxonomy of 14 canonical types plus a note catch-all. The source describes this as collapsing 94 noisy page types into 15 canonical types with subtypes, alias rows and link rows.

Redirect-style pages become alias rows, and link-shaped pages become real links. Unknown types fall into note, and each retyped page keeps its original type in frontmatter.legacy_type so the change can be reversed. The skill is run-only: it changes how the brain's data is organised once you agree to the steps.

• Previews the migration with gbrain onboard --check --explain before writing anything
• Submits the unify-types job only when you agree to apply it
• Checks the result with onboard and schema stats afterwards
• Explains how to restore pages and revert the pack flip

How to install the schema-unify skill

Download the schema-unify ZIP from this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project.

You can also install it in the Claude apps by uploading the ZIP under Settings → Capabilities → Skills. The skill's package contains a single file, SKILL.md, which holds the instructions the agent follows.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What to ask the agent to trigger the skill

You do not need to name the skill. The skill fires when the agent sees the pack_upgrade_available or type_proliferation warnings from onboard, or when you ask a question about the canonical taxonomy or about cleaning up your page types.

Natural requests that match the skill's triggers include the phrases below. Asking what the canonical taxonomy looks like is a safe first request because it leads to a read-only check.

• 'Unify my types'
• 'Migrate to gbrain-base-v2'
• 'Clean up my page types'
• 'What does the canonical taxonomy look like?'
• 'Consolidate page types'

Check your brain and preview the changes

First confirm the brain is on gbrain-base and not already on v2. The skill reads the active pack identity with schema active. If it shows gbrain-base-v2, the migration is already done and the skill tells the agent to skip it.

Then run the preview. The --explain flag shows, per cluster, how many pages would be retyped, how many concept-redirect pages would become alias rows, how many edge-shaped pages would become links, and the catch-all rules for unknown types. Review it carefully. If the proposed changes look wrong, the skill says not to proceed and to file an issue or write a custom pack with adjusted mapping_rules.

• The discovery command uses jq to read the identity field from schema active output
• The preview runs the unify-types handler in dry-run mode

Apply the migration with the unify-types job

Applying is a separate, explicit step. The unify-types handler is protected, so autopilot never fires it. You or the agent must submit it. The apply flag defaults to false, so you must pass apply true or the job will report success without retyping anything.

On PGLite, which is the install default, or on any setup without a running worker or supervisor daemon, add --follow so the job runs inline. The persistent worker daemon is Postgres-only. Without --follow on PGLite the job waits in the queue and never runs. The source notes that a large brain can take around ten minutes.

• Phases: preflight, stats snapshot, the gbrain-unify db-lock, explicit retypes, catch-all retype, page-to-link rules, page-to-alias rules, final sync, pack flip, then verification
• You can watch a single job with jobs get, or the whole queue with jobs watch --follow on a worker-daemon run

Safety notes: scripts, network, managed brains and backups

The skill runs scripts through the gbrain CLI and does not use the network, according to its listing. The apply step rewrites page types across the whole brain, so the source's guidance is not to run it without a backup. Rollback depends on restore being available.

On managed brains with managed persistence on, applying is refused with writer_coordinator_required before anything changes. In that case, use only the preview. The one exception is when the preview shows nothing to retype, link or alias. Then the apply job only switches the active pack and may be submitted with your agreement.

Page-to-alias and page-to-link source pages are soft-deleted with a 72-hour TTL, so restore them inside that window.

• Not for brains already on gbrain-base-v2
• Not for managed brains where you only get the preview step
• Keep a backup before applying

Verify the result and roll back if needed

After applying, run onboard --check again and check that pack_upgrade_available, type_proliferation and dangling_aliases report ok. Then run schema stats to confirm the brain shows 16 or fewer distinct types.

Each retyped page keeps frontmatter.legacy_type. On Postgres or Supabase with direct database access, a SQL update can restore original types in bulk. On PGLite there is no SQL shell, so revert individual pages through the normal put_page or CLI surface. Restore soft-deleted pages with gbrain restore <slug>, and revert the pack flip with schema use gbrain-base.

• Search with --type article still works because media declares article as an alias
• Direct SQL against pages.type must use the canonical types after migration
• Search results get a small ranking boost for pages reached through slug_aliases, visible with search --explain