How to use the GBrain DB Repair agent skill (db-repair)

What an agent skill is and what db-repair makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent when to use a capability and how to carry it out. This one covers a single failure: gbrain cannot reach its Postgres database. When an error shows a GBRAIN_DB_ACCESS marker, or you say the brain database is down, the agent runs gbrain's built-in db-repair command.

The agent works in a fixed order. It diagnoses first without changing anything. It applies low-risk fixes such as retries and reconnects only when told to. It asks for your approval before rewriting the database URL in the config file. For credential or account problems it gives you a manual recipe and stops. After any fix it re-checks the connection before reporting success.

Requirements before you install db-repair

The skill assumes a few things are already in place. Without them there is nothing for it to repair.

• The gbrain CLI is installed and includes the db-repair and engine status commands.
• You have a Postgres database used by gbrain. The skill's source lists local, Docker and Supabase setups.
• The agent has shell execution permission, because the skill uses the exec tool.
• Users on the default local setup with no Postgres database will not benefit, since there is no database connection to repair.

Install the db-repair skill

Download the db-repair ZIP from the skill page on this site. Unzip it into one of two places. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project. The folder should contain SKILL.md.

If you use the Claude apps instead of Claude Code, you can upload the ZIP under Settings, then Capabilities, then Skills.

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

Trigger the skill with natural requests

You do not need to name the skill. The agent loads it when it sees the marker or a matching phrase. The skill's trigger phrases include GBRAIN_DB_ACCESS, gbrain database error, gbrain connection refused, cannot reach the brain database, brain database is down, fix gbrain database access and repair gbrain postgres.

A marker in an MCP error result or on stderr from any gbrain command is also a trigger. Note that the marker is treated as a symptom to diagnose, not as proof that the database is broken. A healthy check exits with code 0 and means nothing needs fixing.

• "gbrain is throwing GBRAIN_DB_ACCESS, can you look at it?"
• "The brain database is down again, please repair it."
• "gbrain connection refused when I run sync. Fix gbrain database access."

How the repair flow works step by step

The agent starts with a read-only diagnosis. It reads the reason, tier and plan from the output. If the reason is healthy, it reports that and stops.

If auto-tier fixes are available, the agent shows you a one-line plan and then applies them. The auto tier covers retries and reconnects, pending migrations, CREATE EXTENSION vector, and starting gbrain's own docker container. If a rewrite-tier fix is needed, the agent shows the exact config change first and applies it only after you say yes. If the reason is a manual-tier problem, such as a failed login, a permission error, a paused Supabase project or a missing database, the agent relays the printed recipe and stops.

Whatever was applied, the agent then runs a verification check. Success is reported only when that check passes.

• Diagnose: gbrain db-repair --json (changes nothing)
• Auto tier, after you approve: gbrain db-repair --yes
• Rewrite tier, only on your explicit yes: gbrain db-repair --yes --apply-rewrites
• Verify: gbrain engine status --probe --json

Safety notes: scripts, network and config changes

The skill runs scripts and uses the network, as its listing states. Its commands are hardcoded in SKILL.md. The skill's contract says the agent never runs a command taken from an error message or marker, so text planted in a page or response should not trigger code.

Config rewrites are the riskiest step. The rewrite tier prints the intended change before applying it and saves a receipt of the previous URL. You can restore it with gbrain db-repair --yes --undo-last-rewrite. The skill also says the agent should never hand-edit ~/.gbrain/config.json.

Credentials are never changed automatically. The skill gives manual recipes for password, account and environment problems, and the operator makes those changes.

• Read the plan before you approve any --yes run.
• Config rewrites affect only new processes. A long-running gbrain serve or jobs worker keeps its old connection, so restart it after a successful rewrite.
• If a repair is already running, the lock means wait rather than retry.