Skip to content
Get packs

Guide · Agent skill

How to use the Brain Health Maintenance agent skill (maintain)

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

The maintain skill is an agent skill for GBrain, a personal knowledge base made of markdown pages and the links between them. It teaches an AI agent to audit that brain for quality problems such as stale pages, orphan pages, dead links, missing cross-references and citation format errors, then report counts per category with a fix for each. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs before you run it.

Brain Health Maintenancegarrytan/gbrain · MIT

Quick start

  1. 1Confirm GBrain is installed. Make sure the gbrain CLI is installed and configured with a brain before installing the skill.
  2. 2Download the skill ZIP. Download the maintain skill ZIP from this page.
  3. 3Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  4. 4Ask for a health check. Request a brain health check in plain language. The agent reads the dashboard and reports counts per dimension.
  5. 5Review the preview. If you want a score target, review the remediation plan and its repair steps and cost before agreeing.
  6. 6Apply with a cost cap. Run the remediation with an agreed plan hash and a --max-usd cap, then re-check the score.

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

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to handle a specific kind of task. The agent loads the instructions when a request matches the skill.

The maintain skill is for an existing GBrain install, not general writing. It walks the agent through health checks: stale pages where the compiled truth is older than the latest timeline entry, orphan pages with zero inbound links, dead links, missing cross-references, back-link enforcement and citation format validation. It can also run extraction commands that build a link graph and timeline from your markdown, and a preview-then-apply path that pushes the brain's health score toward a target you choose.

  • Reports counts per dimension, with a specific fix action for each issue found
  • Runs gbrain extraction commands to build links and timeline entries
  • Previews a remediation plan before applying any change

Install the maintain skill

Download the skill ZIP from this page. The skill ships as a single file, SKILL.md.

Option A (Claude Code, personal): unzip the download into ~/.claude/skills/ so the folder sits there as a skill directory containing SKILL.md.

Option B (Claude Code, one project): unzip it into the project's .claude/skills/ folder so it applies only to that project.

Option C (Claude apps): upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Check the requirements before you trigger it

The skill depends on the GBrain CLI (gbrain) installed and configured with a brain. Without a GBrain installation the commands would fail or do nothing useful.

Scopes matter. get_health needs an admin-scope token. With only read scope, the skill falls back to get_brain_health, which returns only some bands (write capacity, write failures, ghost pages, unsearchable chunks). The skill will name the dimensions it cannot cover and ask for an admin token or for gbrain doctor --json run on the brain host.

Embedding steps need an embedding provider API key. Without one the score is capped at 60. Remediation can trigger paid model or API usage, capped by --max-usd.

  • GBrain CLI (gbrain) installed and configured with a brain
  • Admin-scope token for get_health, or read-scope access for get_brain_health
  • An embedding provider API key for embedding steps
  • Possible paid usage during remediation, limited by --max-usd

Trigger the skill with natural requests

You do not need a command. Ask the agent in plain language. The skill responds to requests such as checking brain health, checking backlinks, running maintenance, finding orphan or stale pages, extracting links, building the link graph, or populating the timeline.

For a full audit, ask for a dimension-by-dimension walk. For a score target, say so explicitly, for example getting the brain to 90/100. The skill will preview before it changes anything.

  • "Run a brain health check and count issues per dimension."
  • "Find orphan pages and suggest which ones should get links."
  • "Check for stale pages and tell me which compiled truths need rewriting."
  • "Build the link graph from my brain folder."
  • "Get my brain to 90/100, but show me the plan first."

Run the preview-then-apply remediation path

When you want the score pushed toward a target, the skill starts with a preview. It lists job steps in dependency order, with estimated seconds and cost, plus repair steps that need your agreement. Nothing is applied until you agree, and the plan hash from the preview binds that approval.

Repair steps run only when you include the --include-repairs flag. Without it they are listed as skipped. The --max-usd flag is a cumulative cost cap across the run and any resume: a paid step that would exceed it is not started, while free steps still run.

gbrain doctor --remediation-plan --json gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --target-score 90 --max-usd 5

Read the findings and when to use the manual walk

When the target is unreachable, for example an empty brain with no entity pages (graph coverage caps at 70) or a missing embedding key (caps at 60), job steps stop and list what is missing rather than looping. Each finding is classified as cleared, pending, consent_required, operator_required or unsupported.

Use the per-dimension walk when you want a manual audit, when you are investigating why the score is stuck below the remediation ceiling, or when a dimension needs human judgment. Manual extraction is run with gbrain extract links --dir ~/brain and gbrain extract timeline --dir ~/brain, used when link count or timeline entry count is zero or low.

gbrain extract links --dir ~/brain gbrain extract timeline --dir ~/brain

What people use it for

  • Periodic cleanup of dead links and orphan pages in a developer's GBrain knowledge base
  • Finding stale pages whose compiled truth lags behind newer timeline evidence
  • Diagnosing why the brain's health score is stuck below a target
  • Building a link graph and timeline from markdown after importing many notes
  • Running a read-only audit on a brain where only read-scope access is available

Frequently asked questions

How do I install the maintain agent skill?

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

What do I need before using the maintain skill?

You need the GBrain CLI installed and configured with a brain, an admin-scope token for get_health (or read scope for get_brain_health), and an embedding provider API key for embedding steps. Remediation may trigger paid usage, which --max-usd caps.

Is the maintain skill free?

The skill is licensed under MIT. Separately, remediation can use paid model or API steps, so set a --max-usd cap and review the plan first.

Does the skill run scripts or use the network?

Yes on both counts. The skill runs gbrain commands and uses the network, including for embedding and model steps, so review the plan before applying changes.

Can I use maintain without a GBrain installation?

No. The skill depends on gbrain commands and its database, so without a GBrain install the commands would fail or do nothing useful.

What if my health score is stuck below my target?

Run the remediation preview, check whether the target is reachable (an empty brain caps graph coverage at 70, and a missing embedding key caps the score at 60), and use the per-dimension walk to see what is blocking it.

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 maintain if you run a GBrain knowledge base and want periodic audits of links, stale content and score targets with a preview before anything changes. Skip it if you do not have a GBrain install, or if the brain's write ownership is contested, since the skill itself says ownership repairs need separate approval and should be reported rather than forced.

Download the skill