Library-based architecture for managing AI agent skills and capabilities

Problem

Agent frameworks like LangChain and CrewAI load every available tool into the model's context window for every request. With dozens of tools, MCP servers, and custom skills, this bloats token usage, increases latency, and confuses the model with irrelevant options. You need a way to define agent capabilities declaratively and load only what each agent needs for its specific task.

Solution

Build a library system where capabilities are stored as versioned files, and agents are defined with explicit tool allowlists. No framework needed -- just file structure and Claude Code CLI.

Library structure

Store all capabilities under /data/library/{type}/{namespace}/{name}:

/data/library/
  skill/
    _global/
      code-review/        # Directory-based skill (multiple files)
        prompt.md
        checklist.json
    my-team/
      deploy-preview/
        prompt.md
  agent/
    _global/
      code-reviewer.json
      security-auditor.json
    my-team/
      frontend-dev.json
  mcp/
    _global/
      github.json
      postgres.json
      filesystem.json
  hooks/
    _global/
      pre-commit.json
  rules/
    my-team/
      coding-standards.md

Agent definitions as JSON

Each agent declares its model, system prompt, and exactly which tools it can use:

{
  "name": "code-reviewer",
  "model": "claude-sonnet-4-5-20250929",
  "system_prompt": "You are a code reviewer. Focus on correctness, performance, and security. Reference the team coding standards.",
  "tools": ["Read", "Glob", "Grep"],
  "max_tokens": 4096,
  "rules": ["my-team/coding-standards"]
}

A more capable agent gets more tools:

{
  "name": "full-stack-dev",
  "model": "claude-sonnet-4-5-20250929",
  "system_prompt": "You are a full-stack developer with access to file editing, Git, and deployment tools.",
  "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
  "mcp_servers": ["github", "postgres", "filesystem"],
  "max_tokens": 16384
}

Scope resolution

Agent definitions resolve at three levels, with narrower scopes overriding broader ones:

1. Per-repository:  .claude/agents/{name}.md     (highest priority)
2. Namespace:       /data/library/agent/{team}/   (team-specific)
3. Global:          /data/library/agent/_global/   (shared defaults)

MCP server seeding

Seed common MCP servers per repository so agents have consistent external tool access:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] },
    "puppeteer": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-puppeteer"] }
  }
}

Orchestration flow

The orchestrator reads task requirements, selects the right agent definition, and spawns a Claude Code CLI process with only the declared tools:

# Spawn a code reviewer with restricted tools
claude --agent code-reviewer --allowlist "Read,Glob,Grep" \
  --prompt "Review the changes in the last commit for security issues"

Why It Works

By storing capabilities as files rather than code, you get version control, diffing, and easy auditing for free. The explicit tool allowlist per agent means a code reviewer literally cannot write files -- the model never even sees the Write tool in its context. This reduces both token cost and the risk of unintended actions. The namespace system lets teams customize agents while sharing a global baseline. And because the orchestration layer just spawns CLI processes, there is no framework lock-in -- you can swap models, add MCP servers, or change agent definitions without touching application code.

Context

• No LangChain, no CrewAI -- the entire system is file-based definitions plus Claude Code CLI
• Skills are directory-based so a single skill can include a prompt, examples, and config files
• The _global namespace provides shared defaults; team namespaces override for specific needs
• MCP servers give agents access to external systems (GitHub, databases, browsers) without custom tool code
• Hooks support pre/post tool execution logic for audit logging, approval gates, or cost tracking
• This pattern scales to dozens of agents because each one only loads its declared subset of capabilities