Skip to content
Skills Library
AI & agents · Research

brain

/brain

Search and analyze governed notes, decisions, runbooks, and conventions, returning a qmd:// citation for every supported claim. Use when checking what the brain has captured about architecture, infrastructure, decisions, or operating practices. Trigger with "/brain", "ask the brain", or "check my knowledge base".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Search and analyze governed notes, decisions, runbooks, and conventions, returning a qmd:// citation for every supported claim. Use when checking what the brain has captured about architecture, infrastructure, decisions, or operating practices. Trigger with "/brain", "ask the brain", or "check my knowledge base".

Triggers from the description

ask the braincheck my knowledge base

Arguments

/brain [question]
Original author description

Search and analyze governed notes, decisions, runbooks, and conventions, returning a qmd:// citation for every supported claim. Use when checking what the brain has captured about architecture, infrastructure, decisions, or operating practices. Trigger with "/brain", "ask the brain", or "check my knowledge base".

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Examples
  6. Error Handling
  7. Guardrails
  8. Resources
Original SKILL.md headings · 138 lines, 945 words
SKILL.md preview
---
name: brain
description: |
  Search and analyze governed notes, decisions, runbooks, and conventions, returning
  a qmd:// citation for every supported claim. Use when checking what the brain has
  captured about architecture, infrastructure, decisions, or operating practices.
  Trigger with "/brain", "ask the brain", or "check my knowledge base".
allowed-tools: "mcp__governed-brain__brain_search"
version: 1.2.1
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: Apache-2.0
compatibility: "Designed for Claude Code; ships with the bobs-big-brain (governed-brain) plugin, which auto-wires the governed-brain MCP server. Works in both modes: local (in-process, needs qmd on PATH) and team (proxies to your team brain when TEAMKB_API_URL is set). Same brain_search either way."
tags: [brain, knowledge, search, citations, governance, local-first, team]
argument-hint: "[question]"
model: inherit
effort: low
---

# Brain — cited answers from your governed knowledge base

Ask your knowledge **brain** a question and get an answer grounded in your governed
corpus, where **every claim carries a qmd:// citation**. The brain does not paraphrase
from memory — it retrieves governed memories and cites them, so any answer is
verifiable after the fact.

## Overview

This is the read surface of Bob's Big Brain: your files are **compiled** into
governed memories, **governed** by deterministic code, and **retrieved** with citations
by **Tobi's qmd** (OSS). The `brain_search` MCP tool fronts that retrieval. Your product
surround is INTKB govern + ICO compile + this plugin — not a fork of qmd.

The job here is to turn a natural-language question into a cited answer — and to refuse
to answer beyond what the citations support.

## Prerequisites

- The **bobs-big-brain** / governed-brain plugin is installed (MCP `governed-brain`).
- **Mode is automatic.** In **local mode** (default) search runs **in-process**
  against your local `~/.teamkb` index — no network, no API key; a compatible **qmd**
  binary must be available (prefer monorepo pin `@tobilu/qmd` via the Registrar / installer).
  Operators can use `scripts/bbb-qmd` from bobs-big-brain-registrar so XDG points at the team
  index, not personal `~/.cache/qmd`. In **team mode** (`TEAMKB_API_URL` set) search
  proxies to the team brain. Every hit is a `qmd://` citation.
- See [the runtime contract](references/runtime-contract.md) for exact inputs, result shapes,
  authentication, and mode-specific failures.

## Instructions

### Step 1: Search the governed corpus

Retrieval is **Tobi's qmd** (BM25 keyword via the MCP). Prefer **short keyword queries**
over full sentences.

1. Derive **1–4 distinctive nouns/verbs** from the user question (drop what/why/how, articles,
   auxiliaries, prepositions).
2. Call **`brain_search`** with those keywords and `scope: "curated"` (default promoted knowledge).

```
brain_search({ query: "SOPS age secrets", scope: "curated" })
```

The tool returns `{ source, results: [{ citation, snippet, score, collection }] }`.
Each `citation` is a `qmd://COLLECTION/FILENAME` URI — the receipt for that hit.

**Empty-result ladder (do not stop after one miss):**

1. **Keyword retry (curated):** only if the first call was still a long natural-language sentence
   (you skipped deriving 1–4 keywords). Re-run with 1–4 keywords only. **Skip this step** when the
   first query was already keyword-style — do not re-call with the same tokens.
2. **Scope retry (`all`):** if curated is still empty, re-run the **same keywords** with
   `scope: "all"`. Do **not** use `inbox`/`archived` unless the user asks.
3. Only after curated+keywords and all+keywords are empty → Step 3 (honest refuse).

```
brain_search({ query: "shipped week", scope: "curated" })
// if empty (keywords already used):
brain_search({ query: "shipped week", scope: "all" })
```

### Step 2: Answer ONLY from the cited results

- Synthesize a direct answer from the returned snippets.
- **Attach the qmd:// citation to every claim**, inline — for example:
  `The proxy reverse-proxies the API (qmd://kb-curated/system-map.md).`
- If two hits conflict, surface both with their citations rather than silently
  picking one — the governance layer tracks contradictions; do not paper over them.
- **Do not add knowledge the citations do not support.** Any reasoning beyond the
  corpus must be labeled clearly as inference, not the brain's answer.

### Step 3: Handle an empty result honestly

If `results` is **still** empty after the empty-result ladder in Step 1, say so plainly: the brain
has nothing governed on that topic. Do **not** fall back to general knowledge and present it as the
brain's answer. Optionally note that the topic may need to be captured (run `/brain-save`).

## Output

1. A short, direct answer.
2. Each load-bearing claim followed by its qmd:// citation.
3. A closing **Sources** list of the distinct qmd:// URIs used.

## Examples

**Cited answer:**

```
/brain what does my system map say about the proxy?

→ The proxy is the single ingress; it reverse-proxies each domain to its service
  and must be reloaded, not restarted, after edits (qmd://kb-curated/system-map.md).

Sources:
- qmd://kb-curated/system-map.md
```

**Empty result (honest refusal):**

```
/brain what is my refund policy?

→ The brain has nothing governed on a refund policy. I won't guess from general
  knowledge. If this should be in your brain, capture it with /brain-save.
```

## Error Handling

| Situation                              | Response                                                                                                                         |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `brain_search` returns empty `results` | Run the empty-result ladder (keywords → scope all); only then refuse. Do not fabricate.                                          |
| `qmd` missing / index empty            | Retrieval degrades to empty. Tell operator: install `@tobilu/qmd`, run INTKB `pnpm search-canary -- --heal` or `bbb-qmd status`. |
| MCP tool unavailable                   | Plugin not enabled; install/enable bobs-big-brain / governed-brain.                                                              |
| User asks to write/capture             | Out of scope here — direct them to `/brain-save`.                                                                                |

## Guardrails

- Read-only. This skill never writes to the corpus — capture and governance live in
  `/brain-save`.
- Never invent a qmd:// URI. Cite only URIs returned by `brain_search`.
- Prefer fewer, well-cited claims over a broad answer that cannot be anchored.
- Do not conflate this product with IRSB / Moat / Scout (separate stack).
- **Provenance ≠ truth.** Promotion receipts record each memory's capture channel (or `unattested`)
  and an origin-token hash — that proves WHERE a capture came from, not that its content is true. An
  authenticated insider can still have saved poisoned content with a valid origin; weigh cited answers
  accordingly and rely on govern policy, human review, and supersession as the content-quality gates.

## Resources

- [Bob's Big Brain umbrella](https://github.com/intent-solutions-io/bobs-big-brain-umbrella) — stack map.
- [bobs-big-brain-plugin](https://github.com/jeremylongshore/bobs-big-brain-plugin) — this plugin.
- [bobs-big-brain-registrar](https://github.com/jeremylongshore/bobs-big-brain-registrar) — govern layer (Bob's Big Brain Registrar) + `bbb-qmd`.
- [tobi/qmd](https://github.com/tobi/qmd) (npm `@tobilu/qmd`) — retrieve engine (OSS; the stack pins it rather than forking it).
- [bobs-big-brain-compiler](https://github.com/jeremylongshore/bobs-big-brain-compiler) — compile layer (Bob's Big Brain Compiler).
- The write counterpart: the `/brain-save` skill (governed capture).
Files in this package (2)
  • SKILL.md 8 KB
  • references/runtime-contract.md 2 KB

Versions

RepositoryScoreLicence
This page · jeremylongshore/tons-of-skills-marketplace100MIT
coco-research/coco100MIT
jeremylongshore/bobs-big-brain-registrar100Apache-2.0
onetest-ai/echo100AGPL-3.0
johantor/brain100Apache-2.0
guangshinhaha/shinstack100MIT
atlasatakahraman/knowledge-skeleton100GPL-3.0
kayossouza/brain-template100MIT
keli-wen/agy-staff95MIT

Database snapshot: 13.11.2026 · package version 2603a40b3c32 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100qmd
    Search markdown knowledge bases, notes, and documentation using QMD. Use when users ask to search notes, find documents, or look up information.
  • 100qmd
    Search local markdown knowledge bases, notes, and docs with qmd. Use when users ask to research on local notes, retrieve documents semantically, or mentions qmd access.
  • 100qmd
    Search local markdown knowledge bases, notes, docs, and wikis with QMD. Use when users ask to find notes, retrieve documents, inspect a wiki, answer from indexed markdown, or set up QMD access.
  • 100qmd
    Search local markdown knowledge bases, notes, docs, and wikis with QMD. Use when users ask to find notes, retrieve documents, inspect a wiki, answer from indexed markdown, or set up QMD access.
  • 100qmd
    Search local markdown knowledge bases, notes, docs, and wikis with QMD. Use when users ask to find notes, retrieve documents, inspect a wiki, answer from indexed markdown, or set up QMD access.
  • 100mobiai-brain
    Use when the user asks about past decisions, workarounds, bugfixes, testing patterns or integrations specific to *this* project, OR before proposing non-trivial architecture/integration changes. MobiAI Brain is per-project living memory at <repo>/.mobiai/brain/. Loads context…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.