Guide · Agent skill
How to use the Brain Query Skill agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Brain Query Skill is an agent skill that makes an AI agent answer questions from a personal knowledge base called a 'brain' (the gbrain project) instead of from its general knowledge. This guide explains what the skill does, how to install it, how to phrase requests so it triggers, and what to check before relying on its answers. You need an existing gbrain brain for it to be useful.
Brain Query Skillgarrytan/gbrain · MIT Download the skill Quick start
- 1Set up a gbrain brain. Make sure you have a running gbrain brain and can reach it through the gbrain CLI or an MCP server exposing its tools.
- 2Download the ZIP. Get the query skill ZIP from this page and unzip it so the SKILL.md file sits in a folder named query.
- 3Place the skill folder. Copy the folder into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
- 4Or upload in the Claude apps. Open Settings, choose Capabilities, then Skills, and upload the skill if you use the Claude apps.
- 5Ask a natural question. Ask something like 'What do we know about Jane Doe?' so the agent searches the brain.
- 6Check citations and notices. Confirm each claim cites a page slug and read any degraded or truncated notices before trusting a gap.
What is an agent skill and what does the query skill do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. This one is named query and is part of the gbrain coding plugin variants.
When installed, the agent searches your brain before answering. It runs keyword and semantic searches, reads the top matching pages, and replies with citations to specific page slugs. If the brain has no information on a topic, the agent says so instead of guessing. It also notes conflicting or stale sources.
When a gbrain server provides memory-specific tools, the skill prefers them: recall for budget-packed memory reads, entity for a person, company or project card, and synthesize for answers that must combine evidence across several pages. If those tools are not available, it falls back to search, query and get_page.
Install the query skill from a ZIP or the Claude apps
Download the ZIP for the query skill from this page and unzip it. The package contains a single file, SKILL.md.
For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can upload the skill instead. Open Settings, go to Capabilities, then Skills, and upload it there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you start
The skill only queries an existing brain. It does not create one and has nothing to search without it. The brain must be reachable either through the gbrain CLI or through an MCP server that exposes gbrain's tools.
An embeddings provider is recommended for full semantic search. Without one, searches run on keywords only, and the skill flags those results as degraded.
- A running gbrain brain
- Access through the gbrain CLI or an MCP server exposing its tools
- An embeddings provider for full semantic search (recommended)
How to trigger the skill with natural requests
You do not need a special command. The skill is triggered by questions and lookup phrases such as the ones below. Ask in plain language and name the person, company, project or topic you care about.
For relational questions, phrases such as 'who knows who' or 'relationship between' steer the agent toward connections between pages.
- "What do we know about Jane Doe?"
- "Tell me about the Q3 pricing project."
- "Who is the contact at Acme?"
- "What happened with the vendor migration?"
- "Search for notes on onboarding."
- "Look up background on the Berlin partnership."
- "Who knows who between the design and data teams?"
Read the answers: citations, gaps and conflicts
A good answer gives a direct response, then cites each claim to a page slug such as people/jane-doe. Source precedence is applied: user statements rank highest, then compiled truth, then timeline entries, then external sources.
If the answer says the brain doesn't have information on a topic, treat that as a real gap. If it says searches are degraded, the empty result may not mean your notes are missing. Pages marked [STALE] may be out of date.
- Citations look like [Source: people/jane-doe, compiled truth]
- Gap flag: the brain doesn't have information on X
- Conflict notes show both citations when sources disagree
Safety notes: scripts, network and sensitive records
This skill runs no scripts and uses no network access of its own. It reads what your brain already stores. Access to the brain is still governed by how you connected it.
Do not use this skill on a brain that holds sensitive records you have not reviewed, because the agent will surface that content in its answers.
- Runs scripts: no
- Uses network: no
- Only reads stored brain content; it does not browse the web for current information
Tips for better answers
Name things exactly as they appear in your notes. Exact names and dates are matched by keyword search, while concept questions use semantic search. If a result looks empty, ask again with exact names and synonyms, and check the notices the agent reports.
For a tight token budget, you can ask the agent to use recall with a budget and cite the evidence it returns. The skill stays within the brain's stored content either way.
- Use exact names and dates for keyword matches
- Ask concept questions in full sentences for semantic matches
- Enable embeddings if searches keep reporting keyword-only results
- Ask for a narrower question when results are truncated
What people use it for
- Look up what your notes say about a contact before a meeting
- Find the background on a project and the open questions recorded about it
- Trace which people or companies connect to a given topic
- Check whether a fact appears in your saved pages, with the page it came from
- Test a gbrain-connected agent setup by asking questions with known answers
Frequently asked questions
Do I need to pay to use the query skill?
The source does not state pricing for this skill. The skill is published under the MIT licence. You still need a running gbrain brain to use it, and the source does not specify costs for that setup.
What do I need before installing the query skill?
You need a running gbrain brain reachable through the gbrain CLI or an MCP server exposing its tools. An embeddings provider is recommended for full semantic search, since keyword-only results are flagged as degraded.
Where do I put the query skill folder?
For Claude Code, place the unzipped folder in ~/.claude/skills/ for personal use or in .claude/skills/ inside a project. In the Claude apps, upload it under Settings, Capabilities, then Skills.
Why does the agent say the brain is searching keywords only?
That means no embeddings provider is active, so semantic search is not running. The skill treats the result as degraded, so an empty answer may not mean your notes lack the topic. Enabling embeddings is the fix the notice points to.
Can the query skill answer questions about current news or the web?
No. The skill only reads the content stored in your brain and does not look up live or current web information.
How does this compare with a general chatbot answer?
The skill is built to answer only from brain content and to cite page slugs for each claim. A general answer may draw on knowledge outside your saved notes, which this skill is designed to avoid.
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 the query skill if you already keep notes or contacts in a gbrain knowledge base and want answers that trace back to specific saved pages. Pick something else if you have no brain set up, need live web information, or your brain holds sensitive records you have not reviewed.
Download the skill