How to use the capture agent skill for gbrain

What the capture skill makes the agent do

Capture is the single entrypoint for saving content into gbrain. When you ask the agent to save something, it runs gbrain capture rather than lower-level commands such as gbrain put or a commit-then-sync sequence. The content is stored in the brain database and also written as a markdown file on disk under an inbox folder, and a receipt is printed so you can see where it went.

Once saved, the note can be found later with gbrain query, gbrain search, or by any agent connected to the brain over MCP.

• Default location: inbox/YYYY-MM-DD-<hash8> slug, written as a file under your sync repository path.
• Default type is note; you can override it with --type.
• Frontmatter records captured_via: capture-cli and a captured_at timestamp.
• The title is the first non-empty line of the body, capped at 80 characters.

Install the capture skill

Download the skill ZIP from this page. The skill is a folder whose main file is SKILL.md, so you install it by unzipping it into a skills directory.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps go to Settings → Capabilities → Skills and upload the ZIP there.

• Personal: ~/.claude/skills/ (available across projects).
• Project: .claude/skills/ inside the project folder.
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Before you start: what the skill needs

The skill only works as a front end to an existing gbrain setup. Check these three things first.

• The gbrain CLI is installed and configured on the machine.
• A gbrain brain database and a sync repository path exist.
• The agent runtime can run shell commands, because gbrain capture is a shell command.

Trigger the skill with natural requests

You do not need to type the command yourself. The skill is triggered by phrases such as the ones below. Say what you want saved and the agent will choose the capture path.

The skill is meant for the simple case of one thought, one note or one transcript. Pasting content and asking the agent to keep it also works, and the agent can capture a meeting summary or research note after it writes one.

• "Capture this thought"
• "Save this thought"
• "Remember this"
• "Drop this in the inbox"
• "Ingest this into my brain"
• "Save to brain"

Run capture yourself from the command line

You can call the command directly. Content can be passed inline, read from a file, or piped in. Flags let you set a slug, a type or a source, and control the output format.

• --file PATH reads a markdown or text file.
• --stdin reads from a pipe.
• --slug sets a specific slug such as daily/2026-05-21.
• --type idea and --source voice-whisper set type and source.
• --quiet prints only the slug, useful in scripts.
• --json prints structured output for tools.

Read the receipt

By default capture prints a five-line receipt. It shows the slug, the status, a content hash, the full file path on disk and the capture time. Use the slug to find the page later, and the file path to open the markdown directly.

• slug: the page identifier, for example inbox/2026-05-21-abcdef12.
• status: for example created_or_updated.
• file: where the markdown was written.
• captured_at: an ISO timestamp.

Safety notes: scripts, network and secrets

This skill runs scripts and uses the network. Captured content is written to disk and to the brain database. Inline text passed on the command line can end up in your shell history, so do not capture passwords, keys or other credentials this way. Use --file or --stdin for anything sensitive, and in practice avoid capturing secrets at all.

Captures made through this skill are local-CLI trust. Untrusted webhook ingestion uses a different route, POST /ingest, and not this skill. If a secret scanner refuses content, nothing is saved, and the agent will tell you what was refused rather than editing the content to get past the scanner.

Tips and when to use a different skill

Capture is for single items. For bulk work, use gbrain sync or gbrain import rather than looping capture over many files. Specialized ingestion paths exist for articles with author metadata, media, and meeting transcripts, and they handle their own slugging and cross-referencing.

• Do not loop capture over dozens of files; use gbrain sync or gbrain import.
• Use --file when you already have a fully formatted markdown file, since capture wraps plain prose in frontmatter for you.
• For articles with author and publication details, use the idea-ingest skill; for meeting transcripts, use the meeting-ingestion skill; for bulk media, use media-ingest.
• If a write is pending, do not capture it twice. Check its status with gbrain write-request and the request id.