Skip to content
Get packs

Guide · Agent skill

How to use the Schema Author agent skill (gbrain)

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

The schema-author skill teaches an AI agent how to change the structure of a gbrain personal knowledge base, which is called its schema pack. Agent skills are instruction packages that an agent loads when a task matches them. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before letting it change anything.

Schema Authorgarrytan/gbrain · MIT

Quick start

  1. 1Install gbrain and the skill. Make sure the gbrain CLI with schema subcommands and your brain database are available, then unzip the skill ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Check the active pack. Ask the agent what schema pack is active, or run gbrain schema active --json, to see whether it is a bundled pack that needs forking.
  3. 3Assess coverage. Run gbrain schema stats --json and review the untyped pages with gbrain schema review-orphans --json to find folders worth a new type.
  4. 4Propose and add types. Use the detect or suggest output to choose candidates, then add them to a forked pack with gbrain schema add-type.
  5. 5Preview and apply the backfill. Run gbrain schema sync --json to see what would change, then gbrain schema sync --apply once the counts look right.
  6. 6Verify and commit. Check coverage with gbrain schema stats --json, test an expert type with gbrain whoknows, then commit the pack file if it is under version control.

What the schema-author skill makes the agent do

gbrain organises notes as typed pages, where each page can have a type such as a person, meeting or paper. The schema pack defines which types exist, their path prefixes and related settings. The schema-author skill lets the agent inspect that pack, find pages with no type, propose new types from the content already in your brain, and apply them.

The skill is for changing the rules, not filing individual notes. Filing a single new note is handled by the brain-taxonomist skill, and simple reads such as gbrain schema explain or gbrain whoknows can be run directly.

  • Check which schema pack is active and what types it declares
  • Find untyped pages and group them by shared folder paths
  • Propose candidate types, such as researcher or paper, from your corpus
  • Add, update or remove types, aliases, prefixes and link types
  • Backfill the type on existing pages after a dry run
  • Audit pack health and coverage

Install the schema-author skill

Download the ZIP for the skill from the page you are reading. Then choose one of two options.

For a personal setup, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal: unzip into ~/.claude/skills/
  • Single project: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The skill only works against a gbrain installation. It needs the gbrain CLI with its schema subcommands, and access to a gbrain brain database, because the sync and lint commands read and write it. If your agent uses MCP, the server must expose the schema_* tools.

The skill runs scripts, so review what it will execute. It does not use the network, according to the skill's own assessment.

  • gbrain CLI with schema subcommands installed
  • Access to a gbrain brain database
  • An MCP server exposing schema_* tools, only if you use MCP
  • Without gbrain, the commands and MCP tools have nothing to act on

How to trigger the skill with natural requests

You do not need to name commands. Describe the problem and the agent will match the request to the skill. Phrases the skill is written to respond to include adding a page type, saying your brain has untyped pages, or saying your schema is not matching your notes.

Examples of requests that fit: asking for a researcher type in your schema, telling the agent you have 4000 untyped pages under meetings/, asking it to propose types from what you have ingested, or asking it to make paper extractable. Requests like asking where one note should go, or who knows about a topic, belong to other tools.

  • "Add a researcher type to my schema"
  • "I have 4000 untyped pages under meetings/"
  • "Propose new types from what I've ingested"
  • "Set paper to be extractable"
  • "Sync the new types to backfill existing pages"

Walk through a typical change safely

The skill follows a fixed order. It first checks the active pack, then measures coverage, proposes types, applies them to a forked pack, validates, previews the backfill and verifies the result. If the active pack is a bundled one, the skill forks it first so the original is not changed.

Backfill is previewed with a dry run before any page is updated. The apply step updates existing pages in batches of 1000 rows and can be re-run safely, because a second run finds nothing left to backfill. Coverage should reach 95% or more afterwards.

  • Confirm the active pack and whether it is bundled
  • Read coverage and untyped pages
  • Fork a bundled pack, then add types one at a time
  • Run lint with the database option to catch mis-declared types
  • Preview the sync, then apply it
  • Verify coverage and test an expert-routed type with whoknows
gbrain schema active --json gbrain schema stats --json gbrain schema sync --json gbrain schema sync --apply gbrain schema stats --json

Keep pack changes under version control

If your pack is in source control, the skill can commit and push only the pack file. It uses gbrain git commit-push, which takes the checkout's writer lock, so it is safe when several agents share the checkout. If a push fails with a conflict, the skill is written to stop and ask you which version of pack.json should win rather than resolving it silently.

cd ~/.gbrain/schema-packs/mine gbrain git commit-push -m "schema: add researcher + paper types + authored link" -- pack.json

What people use it for

  • Organising a research folder of papers into a paper type linked to researcher pages
  • Turning thousands of untyped meeting notes under meetings/ into a queryable type
  • Adding custom types such as contract or deposition for legal or ops work
  • Auditing a schema pack to find prefixes that match no pages
  • Making a specialist type routable so gbrain whoknows can find experts on a topic

Frequently asked questions

What is the schema-author skill?

It is an agent skill that teaches an AI agent how to change the schema pack of a gbrain knowledge base. It can add page types, propose new ones from your content, backfill types on existing pages and audit coverage.

How do I install the schema-author skill?

Download the ZIP from the page, then unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Do I need gbrain to use this skill?

Yes. The skill only works against a gbrain installation, using its CLI schema subcommands and a gbrain brain database. Without gbrain, the commands and MCP tools have nothing to operate on.

Is the schema-author skill free and what is its licence?

The skill is listed under the MIT licence. This page does not state pricing beyond that, so check the repository for any details about gbrain itself.

Does the skill use the network?

According to the skill's assessment, it does not use the network. It does run scripts, so review what it executes before use.

Can the agent change my data without warning?

The skill is designed to preview changes. It runs a dry run of sync before --apply, and it works on a forked copy when the active pack is bundled. Review the dry-run counts before applying.

What should I use instead for filing a single note?

Use the brain-taxonomist skill to decide where one new note belongs. Schema-author changes the rules, while brain-taxonomist routes individual pages.

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

This skill is worth installing if you run a gbrain knowledge base with many untyped pages or custom domains such as research, legal or operations, and you want an agent to propose and apply a structure carefully. It is not useful if you do not run gbrain, or if you only need to file a single note or look up a type's settings.

Download the skill