Brain
Lazy loading for AI coding agent skills. A token-efficient MCP server that lets agents fetch only the skill sections they need, when they need them — without loading entire skill libraries into context.
Each skill is a folder with a SKILL.md that tells the agent how to approach a specific task — what tools to use, what patterns to follow, what to watch out for. Skills are loaded progressively via the MCP server, not pulled into context all at once.
One standard format. Any model. Any IDE. Zero context bloat.
Benchmarks
Same task, same project, same prompt — API documentation with two skills loaded.
| Brain (MCP) | Raw markdown files | |
|---|---|---|
| Context tokens | 20,000 | 150,000 |
| Cost | $0.03 | $0.24 |
| Lines added | 876 | 693 |
| Lines removed | 161 | 90 |
Brain used 86% fewer tokens while producing 26% more output. The agent fetched only the sections it needed via progressive disclosure — it never loaded the full skill files.
How it works
Skills live in ~/.agents/skills/ but agents must never access this directory directly. Instead, they use the MCP server (brain_mcp.py) to fetch only what they need, when they need it, without loading entire files into context.
Why this matters: Loading all skills into context wastes tokens and degrades performance. Brain's progressive disclosure ensures agents fetch only relevant sections — reducing context usage by 86%.
Security note: You should deny agent access to ~/.agents/skills and disable any direct skill-loading tools. Skills must always be accessed via the MCP server to maintain token efficiency.
The CLI (brain) handles registry management: syncing from remote, searching, and organizing skills.```
~/.brain/
├── brain_mcp.py ← MCP server (agent access layer)
├── brain_cli.py ← CLI tool for registry management
├── index.json ← pre-built frontmatter index
└── scripts/
└── build_index.py ← called by brain sync to regenerate index.json
~/.agents/
└── skills/ ← all available skills (agents must NOT access directly)
├── frontend-design/
│ └── SKILL.md
└── ...
---
## Setup
### 1. Clone the registry```bash
git clone https://github.com/Raulvalverdeleal/brain ~/.brain
2. Install brain
brain is the CLI for registry management. Make it available globally:```bash
Option 1: Create an alias
echo 'alias brain="python3 ~/.brain/brain_cli.py"' >> ~/.zshrc
source ~/.zshrc
Option 2: Create a symlink in your PATH
ln -s ~/.brain/brain_cli.py /usr/local/bin/brain
### 3. Build the index```bash
brain build-index
This parses all skill frontmatters once and writes ~/.brain/index.json. The MCP server loads this file at startup instead of scanning hundreds of files — startup goes from seconds to milliseconds.
> brain requires Python 3. No dependencies beyond the standard library.
4. Register the MCP server
Add to your MCP config (e.g. claude_desktop_config.json, opencode.json, etc.):```json
{
"mcpServers": {
"brain": {
"command": "python3",
"args": ["~/.brain/brain_mcp.py"]
}
}
}
Or for stdio-based transport:```json
{
"mcp": {
"brain": {
"command": "python3",
"args": ["~/.brain/brain_mcp.py"]
}
}
}
The server auto-installs its only dependency (mcp[cli]) on first run.
5. Secure your setup (important)
Never let agents access ~/.agents/skills directly. Doing so defeats lazy loading and wastes tokens by loading all skills into context.
To enforce this:
- Deny filesystem access to
~/.agents/skillsin your agent configuration - Disable direct skill-loading tools if your platform has them
- Add to your global AGENTS.md:
- Do not access skills via `/Users/username/.agents/skills` use always brain mcp server instead. - Only expose the Brain MCP server for skill access — it handles progressive disclosure automatically
CLI reference```
brain sync Pull registry and rebuild index if changed
brain search <query> [--page N] Search skills (prefix terms with - to exclude)
brain info <skill> Show metadata and file tree for a skill
brain list List all skills in the registry
**Examples:**```bash
brain sync
brain search "react state management"
brain search frontend -azure --page 2
brain info react-best-practices
brain list
sync
Runs git pull. If changes are detected — or if index.json is missing — it rebuilds the index automatically. If the registry is already current, it prints index stats and exits.```
● Syncing ~/.brain ...
✓ Already up to date.
──────────────────────────────────────────────────
index 2025-01-05T10:22:11Z 943 skills
no changes — index up to date
### search
Scores skills against your query and returns ranked results (3 per page via MCP, 5 per page via CLI). Name matches score highest, then keywords, then description. Use `-term` to exclude noisy results.```bash
brain search "react state"
brain search postgres -azure -cloud
brain search "api design" --page 2
info
Shows full metadata for a skill: description, keywords, dependencies, file tree.```bash
brain info postgres-best-practices
---
## MCP server tools
The MCP server exposes seven tools for progressive skill access. Agents move through levels only as deep as needed — **a typical session costs ~400 tokens vs 2000+** loading a full skill file cold.```
skill_search → find candidates (paginated, ranked)
skill_info → frontmatter + file tree, zero content cost
skill_toc → heading tree only, up to 5 skills at once
skill_section → one section by slug
skill_get → full SKILL.md content
skill_get_file → any supporting file (references/, scripts/)
skill_index_status → health check, force reload after sync
Progressive disclosure flow```
agent: skill_search("figma design implementation")
→ 3 results, page 1 of 2
agent: skill_info("figma-implement-design")
→ frontmatter + file tree (no content loaded)
agent: skill_toc("figma-implement-design")
→ heading tree with slugs, dependency TOCs appended
agent: skill_section("figma-implement-design", "phase-3-design-tokens")
→ only that section
### skill_search
Paginated search across all skills. Returns 3 results per page via MCP server (5 per page via CLI). Supports negative filtering.```
query: "figma design" matches:4 page:1/2
→ call skill_search(query='figma design', page=2) for more
■ figma-implement-design (score:14)
Full workflow to go from a Figma file to production-ready code...
skill_toc
Returns the heading tree of one or more skills as addressable slugs. Pass up to 5 IDs in one call to plan your section fetches upfront.```
■ figma-implement-design
phase-1-orient Phase 1 — Orient
phase-2-visual-reference Phase 2 — Visual reference
#phase-3-design-tokens Phase 3 — Design tokens
...
supporting files:
references/advanced-patterns.md
Dependency TOCs are listed but not expanded automatically — the agent requests them explicitly if needed.
### skill_section
Fetches content from one heading to the next heading of equal or higher level. The primary efficiency tool — use it instead of `skill_get` whenever possible.```bash
skill_section("figma-implement-design", "phase-3-design-tokens")
skill_info
Returns frontmatter metadata and file tree with zero content cost. If a skills.json exists in the project with notes for this skill, they are appended automatically.
How skills work
When the agent receives a task, it uses skill_search to find relevant skills, then progressively loads content via skill_toc and skill_section. The agent fetches skill_get only when it needs the full document.
Skills are intentionally independent — you only load what your task needs.
Skill structure```
~/.agents/skills/
└── your-skill-name/
├── SKILL.md ← required
├── references/ ← optional: supplementary docs
└── scripts/ ← optional: helper scripts
### Required frontmatter
Every `SKILL.md` must start with a YAML frontmatter block:```yaml
---
name: your-skill-name
description: One or two sentences. When should an agent use this skill?
keywords: react ui components typescript
---
name and description are required.
keywords is optional but improve search ranking and dependency resolution.
index.json
index.json is generated by build_index.py and is the MCP server's data source. It contains parsed frontmatter for every skill — never full content. Rebuild it after any brain sync that pulls changes.json
{
"_meta": {
"built_at": "2025-01-05T10:22:11Z",
"skill_count": 943
},
"skills": {
"frontend-design": {
"name": "frontend-design",
"description": "...",
"keywords": ["react", "ui", "css"],
"file_tree": ["SKILL.md"],
"has_references": false,
"has_scripts": false
}
}
}
TODOS
- [ ] Build index when a skill is added / re-build index on mcp launch.
