How to use the gbrain Advisor agent skill (gbrain-advisor)

What is an agent skill, and what does gbrain-advisor do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the agent loads the skill, it follows those instructions for matching requests.

The gbrain-advisor skill tells the agent to run gbrain advisor and check the brain for version updates, pending migrations, stalled jobs, low embedding coverage, setup problems and uninstalled brain skills. The agent then summarizes the most important items, shows the exact fix command, and asks before doing anything.

• Read-only: the advisor computes a ranked list from existing brain state and does not change anything.
• Findings are ranked as critical, warn or info.
• Fixes run only after you approve them.

Install the gbrain-advisor skill

Download the ZIP for the skill from the plugin page, then choose one of the options below.

For Claude Code, unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder to make it available only in that project.

In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

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

Check the requirements before you start

The skill needs the gbrain CLI installed and configured with access to your brain database. Without that, the advisor cannot read brain state.

The weekly checkup also needs the cron-scheduler skill. The skill references shared convention files (brain-first.md and agent-operator-protocol.md) and the db-repair skill for failure cases, so keep those available alongside it.

• gbrain CLI installed and configured with brain database access (required)
• cron-scheduler skill (only for the optional weekly checkup)
• Shared convention files brain-first.md and agent-operator-protocol.md
• db-repair skill for when the brain cannot be reached

Run the advisor with natural requests

You do not need to remember a command. Ask the agent in plain words, and the skill is triggered by phrases such as the ones below. The agent runs the advisor and returns the findings.

Under the hood the skill runs the advisor in JSON mode. The exit code is a severity gate: 0 means clean, 1 means warn and 2 means critical.

• "What should I do to get more out of gbrain?"
• "Is my brain set up right?"
• "gbrain advisor"
• "Advise me on my brain."
• "Weekly brain checkup."

Review findings and approve fixes

Each finding has a severity, a one-line title explaining why it matters, and a fix command. The agent reads the highest severity first and summarizes the top one to three items, leading with any critical item such as pending migrations.

For each item the agent shows the fix command and asks whether to run it. Only findings that include a dispatch_id can be applied through the advisor's --apply option, and only after you confirm. Findings without a dispatch_id must be run by the agent using their fix command after you agree.

• Critical: act on it first (for example, pending migrations).
• Warn: worth fixing soon, such as a newer gbrain version being available.
• Info: a gentle nudge, not a blocker.

Set up a weekly checkup

To get a regular reminder, install a weekly job through the cron-scheduler skill. The job prompt is kept short: it tells the agent to read this skill and run the advisor. A suggested slot is Monday 09:00 in your local time, outside quiet hours.

The advisor keeps a local run history, so each reminder can focus on what is new since the last run instead of repeating every item. Because the advisor is read-only, a job that fires twice is harmless.

• Schedule: weekly, Monday 09:00 local time as an example
• Job prompt: read skills/gbrain-advisor/SKILL.md, run gbrain advisor --json, ping me with new or critical items, and ask before fixing

Safety notes: scripts and network

This skill runs scripts, because it executes the gbrain CLI. It does not use the network, according to its listing. The advisor only reads gbrain state.

The skill is designed to require explicit approval for every fix. Fixes run as a structured argument list rather than through a shell, and --apply is local only. Never approve a fix you do not understand, and review the command shown before saying yes.

• Runs scripts: yes (gbrain CLI)
• Uses network: no
• Fixes need your explicit yes
• Backup status: once a month, the advisor also reports knowledge repos that have no git remote; relay any warning