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.
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.
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
└── ...
git clone https://github.com/Raulvalverdeleal/brain ~/.brainbrain is the CLI for registry management. Make it available globally:
# 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/brainbrain build-indexThis 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.
brainrequires Python 3. No dependencies beyond the standard library.
Add to your MCP config (e.g. claude_desktop_config.json, opencode.json, etc.):
{
"mcpServers": {
"brain": {
"command": "python3",
"args": ["~/.brain/brain_mcp.py"]
}
}
}Or for stdio-based transport:
{
"mcp": {
"brain": {
"command": "python3",
"args": ["~/.brain/brain_mcp.py"]
}
}
}The server auto-installs its only dependency (mcp[cli]) on first run.
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
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:
brain sync
brain search "react state management"
brain search frontend -azure --page 2
brain info react-best-practices
brain listRuns 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
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.
brain search "react state"
brain search postgres -azure -cloud
brain search "api design" --page 2Shows full metadata for a skill: description, keywords, dependencies, file tree.
brain info postgres-best-practicesThe 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
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
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...
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.
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.
skill_section("figma-implement-design", "phase-3-design-tokens")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.
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.
~/.agents/skills/
└── your-skill-name/
├── SKILL.md ← required
├── references/ ← optional: supplementary docs
└── scripts/ ← optional: helper scripts
Every SKILL.md must start with a YAML frontmatter block:
---
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 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.
{
"_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.