How to use the gbrain Company Brain Access agent skill

What the gbrain skill makes the agent do

The skill connects the agent to the gbrain CLI, which is set up as a thin client to your organization's central brain. The brain is the deep, indexed, cross-source memory: org docs, shared channel knowledge, and every agent's durable notes.

Before answering questions about people, projects, decisions, or history, the agent is instructed to search the brain first. When it produces conclusions with lasting value, it can save them back. Reads and writes are limited by the server: the agent only sees sources its client is entitled to, and it can only write under its permitted prefixes.

• Search the brain with hybrid semantic and keyword search
• Read a single page by its slug
• Write durable conclusions under the agent's own namespace and the channels it belongs to
• Link related pages together

Install the gbrain skill from the ZIP

Download the gbrain ZIP from this page and unzip it. The package contains three files: SKILL.md, tool.json, and provision-scopes.sh. SKILL.md holds the instructions the agent reads.

For a personal setup, place the unzipped folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps, you can upload the skill instead under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Connect the agent to your brain server

Before the skill works, the gbrain CLI must be installed and connected to your organization's brain server. Your organization issues the OAuth client ID and client secret through its secret handoff, either as a keychain entry or a one-time secret drop named gbrain.

Run the setup once per sandbox. If gbrain remote doctor already passes, you can skip it. Replace the brain.<org>.com placeholders with your organization's host and the credential values from the handoff.

Pass the client secret with --oauth-client-secret rather than the GBRAIN_REMOTE_CLIENT_SECRET environment variable. According to the skill, an env-sourced secret is not written to ~/.gbrain/config.json, so later commands fail with 'No client_secret available' once the variable goes out of scope. The flag saves it to the config file.

Do not run gbrain remote doctor. It needs admin scope, which a standard client does not have. Use gbrain whoami as the read-scope health check.

Search and read the brain

Reading is the safe, frequent operation. The skill says to do it liberally. Search works on meaning and keywords together, so you can ask in natural language. Use query with --json when the output is for agent consumption.

• gbrain search "who decided X and why" runs a hybrid semantic and keyword search
• gbrain get <slug> reads one page
• gbrain query "question" --json runs a search tuned for agents

Save durable knowledge to the brain

Writing is limited to durable knowledge. The skill says to save conclusions and facts, not chat transcripts. Write one page per entity, decision, or topic, and update an existing page instead of creating near-duplicates. Pages use Markdown with YAML frontmatter.

Writes go under your own namespace (for personal memory) or under a channel prefix you belong to. Writes outside those prefixes are rejected by the server. When you learn something relevant to a channel during personal work, the skill asks the agent to copy the conclusion to the channel with a '(said in <where>)' provenance note.

• Write conclusions and durable facts, not transcripts
• Update existing pages rather than appending near-duplicates
• Link from pages in your namespace to any readable page with gbrain link <from> <to>
• Add a '(said in <where>)' note when mirroring to a channel

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent to use it for questions about the organization, people, projects, decisions, or history, and for persisting knowledge beyond the current scope. Ask the way you would ask a colleague, and the agent should search the brain before it answers.

If results look wrong, for example authentication errors or empty results you did not expect, ask the agent to run gbrain whoami and report its output. That shows which client and scopes are in use.

• "Who owns the billing service, and when did we decide that?"
• "Search the brain for why we chose the current database."
• "Save the decision we just made in the eng channel as a brain page."
• "Check whether gbrain whoami still works."

Safety notes: scripts and network access

This skill runs scripts and uses the network. The CLI calls your organization's brain host, and provision-scopes.sh is included in the package. The operator requirements list bash, the gbrain CLI with admin access, and a roster file for running provision-scopes.sh. Those steps are for operators, not for ordinary users.

The server enforces read isolation and write fences, so the agent cannot read sources it lacks access to or write outside its prefixes. Still, treat the OAuth client secret as a credential and do not paste it into shared chats or public files. Review any script before you run it.

• Network access to https://brain.<org>.com is required
• The client secret must come from your organization's handoff
• Operator-only: provision-scopes.sh requires bash, admin CLI access, and a roster file
• Agent-written conclusions persisted to shared channels may spread unverified information, so review them

Tips for reliable use

Run gbrain whoami first in any new sandbox. Most later failures trace back to credentials or scope. Keep each brain page focused on one entity, decision, or topic, so search returns clear results. Use the agent's personal notebook for fast working memory and the brain for knowledge other people should find later.

• Confirm gbrain whoami succeeds before anything else
• Keep one topic per page and update pages instead of duplicating them
• Save conclusions, not raw conversation logs
• Use gbrain search before trusting an answer about org history