Example: Multiple Profiles

This example demonstrates how to create multiple skill profiles that agents can switch between based on the task at hand.

Overview

Multiple profiles allow you to organize tools by purpose, keeping the agent's context clean by only loading relevant tools for each task.

Use Cases

Research tasks vs. data analysis tasks
Frontend development vs. backend development
Content creation vs. code review
Different permission levels or environments

Configuration

providers:
  - cursor

options:
  toolExposure: on-demand  # Important for profile switching

skills:
  - id: researcher
    type: inline
    def:
      content: |
        ---
        name: researcher
        description: Web research capabilities
        ---
        
        # Researcher Profile
        
        For research tasks: use brave_search to find information online.
        
        ## When to Use
        - User asks about current information
        - Need to research topics
        - Verify facts or find sources
      requires:
        - brave_search
  
  - id: data-analyst
    type: inline
    def:
      content: |
        ---
        name: data-analyst
        description: Data analysis with pandas
        ---
        
        # Data Analyst Profile
        
        For data analysis: use pandas_query to query CSV files
        and plot_data to create visualizations.
        
        ## When to Use
        - Working with CSV or data files
        - Need to query or filter data
        - Creating charts or plots
      requires:
        - pandas_query
        - plot_data
  
  - id: file-worker
    type: inline
    def:
      content: |
        ---
        name: file-worker
        description: File system operations
        ---
        
        # File Worker Profile
        
        For file operations: use read_file, write_file, and list_directory.
        
        ## When to Use
        - Reading or writing files
        - Exploring project structure
        - Managing local files
      requires:
        - read_file
        - write_file
        - list_directory

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}
  
  - id: filesystem
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-filesystem
      args:
        - /Users/username/projects

tools:
  # Research tools
  - id: brave_search
    type: mcp
    def:
      server: "@brave"
      tool: brave_web_search
  
  # Data analysis tools
  - id: pandas_query
    type: command
    def:
      init:
        cmd: pip install pandas
      run:
        cmd: python -c "import pandas as pd; df = pd.read_csv('{file}'); print(df.query('{query}'))"
        args:
          - name: file
            type: string
            required: true
          - name: query
            type: string
            required: true
  
  - id: plot_data
    type: command
    def:
      init:
        cmd: pip install matplotlib pandas
      run:
        cmd: python -c "import pandas as pd; import matplotlib.pyplot as plt; df = pd.read_csv('{file}'); df.plot(x='{x}', y='{y}'); plt.savefig('plot.png'); print('Plot saved to plot.png')"
        args:
          - name: file
            type: string
            required: true
          - name: x
            type: string
            required: true
          - name: y
            type: string
            required: true
  
  # File system tools
  - id: read_file
    type: mcp
    def:
      server: "@filesystem"
      tool: read_file
  
  - id: write_file
    type: mcp
    def:
      server: "@filesystem"
      tool: write_file
  
  - id: list_directory
    type: mcp
    def:
      server: "@filesystem"
      tool: list_directory

{
  "providers": ["cursor"],
  "options": {
    "toolExposure": "on-demand"
  },
  "skills": [
    {
      "id": "researcher",
      "type": "inline",
      "def": {
        "content": "---\nname: researcher\ndescription: Web research capabilities\n---\n\n# Researcher Profile\n\nFor research tasks: use brave_search to find information online.",
        "requires": ["brave_search"]
      }
    },
    {
      "id": "data-analyst",
      "type": "inline",
      "def": {
        "content": "---\nname: data-analyst\ndescription: Data analysis with pandas\n---\n\n# Data Analyst Profile\n\nFor data analysis: use pandas_query and plot_data.",
        "requires": ["pandas_query", "plot_data"]
      }
    },
    {
      "id": "file-worker",
      "type": "inline",
      "def": {
        "content": "---\nname: file-worker\ndescription: File system operations\n---\n\n# File Worker Profile\n\nFor file operations: use read_file, write_file, and list_directory.",
        "requires": ["read_file", "write_file", "list_directory"]
      }
    }
  ],
  "servers": [
    {
      "id": "brave",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}"
        }
      }
    },
    {
      "id": "filesystem",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-filesystem",
        "args": ["/Users/username/projects"]
      }
    }
  ],
  "tools": [
    {
      "id": "brave_search",
      "type": "mcp",
      "def": {
        "server": "@brave",
        "tool": "brave_web_search"
      }
    },
    {
      "id": "pandas_query",
      "type": "command",
      "def": {
        "init": {
          "cmd": "pip install pandas"
        },
        "run": {
          "cmd": "python -c \"import pandas as pd; df = pd.read_csv('{file}'); print(df.query('{query}'))\"",
          "args": [
            {
              "name": "file",
              "type": "string",
              "required": true
            },
            {
              "name": "query",
              "type": "string",
              "required": true
            }
          ]
        }
      }
    },
    {
      "id": "plot_data",
      "type": "command",
      "def": {
        "init": {
          "cmd": "pip install matplotlib pandas"
        },
        "run": {
          "cmd": "python -c \"import pandas as pd; import matplotlib.pyplot as plt; df = pd.read_csv('{file}'); df.plot(x='{x}', y='{y}'); plt.savefig('plot.png'); print('Plot saved to plot.png')\"",
          "args": [
            {
              "name": "file",
              "type": "string",
              "required": true
            },
            {
              "name": "x",
              "type": "string",
              "required": true
            },
            {
              "name": "y",
              "type": "string",
              "required": true
            }
          ]
        }
      }
    },
    {
      "id": "read_file",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "read_file"
      }
    },
    {
      "id": "write_file",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "write_file"
      }
    },
    {
      "id": "list_directory",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "list_directory"
      }
    }
  ]
}

How It Works

On-Demand Tool Exposure

The key to multiple profiles is setting toolExposure: on-demand:

Initial state: Agent sees only setup_tools and call_tool meta-tools
Task-specific loading: Agent calls setup_tools({"skills": ["researcher"]}}) and receives tool schemas
Context stays clean: Only 2 meta-tools in context until activated
Profile switching: Agent can activate different skills anytime
Tool invocation: Agent uses call_tool to invoke any activated tool

Usage Examples

Research Task

// User asks: "What are the latest developments in AI?"

// Step 1: Activate researcher skill
setup_tools({"skills": ["researcher"]})

// Step 2: Use call_tool to search
call_tool({
  "name": "brave_search",
  "data": {
    "query": "latest developments in AI"
  }
})

Data Analysis Task

// User asks: "Analyze the sales.csv file and show me revenue by month"

// Step 1: Activate data-analyst skill
setup_tools({"skills": ["data-analyst"]})

// Step 2: Query the data
call_tool({
  "name": "pandas_query",
  "data": {
    "file": "sales.csv",
    "query": "revenue > 1000"
  }
})

// Step 3: Plot the results
call_tool({
  "name": "plot_data",
  "data": {
    "file": "sales.csv",
    "x": "month",
    "y": "revenue"
  }
})

File Management Task

// User asks: "List all TypeScript files in the src directory"

// Step 1: Activate file-worker skill
setup_tools({"skills": ["file-worker"]})

// Step 2: List directory
call_tool({
  "name": "list_directory",
  "data": {
    "path": "/Users/username/projects/src"
  }
})

Loading Multiple Profiles

Agents can load multiple profiles at once for complex tasks:

// User asks: "Read data.csv, analyze it, then search for similar datasets online"

// Agent loads both profiles
setup_tools({"skills": ["data-analyst", "researcher"]})

// Now has access to tools from both profiles via call_tool

Setup Steps

1. Create the Configuration

capa init

Paste the configuration above into capabilities.yaml.

2. Update Paths

Change /Users/username/projects to your actual projects directory.

3. Install

capa install

Provide your Brave API key when prompted.

Benefits of Multiple Profiles

Reduced context: Agent only sees relevant tools
Better focus: Clear separation of concerns
Faster responses: Fewer tools to reason about
Organized tooling: Easy to understand and maintain
Flexible combinations: Load multiple profiles as needed

Best Practices

Clear naming: Use descriptive profile names (researcher, data-analyst)
Single responsibility: Each profile should have a focused purpose
Document when to use: Provide clear guidance in skill content
Avoid overlap: Minimize tool duplication across profiles
Test combinations: Verify that loading multiple profiles works as expected

Advanced: Environment-Based Profiles

Create profiles for different environments:

skills:
  - id: dev-tools
    type: inline
    def:
      content: |
        # Development Tools
        Local file access and debugging tools.
      requires:
        - read_file
        - write_file
  
  - id: prod-tools
    type: inline
    def:
      content: |
        # Production Tools
        Read-only access and monitoring tools.
      requires:
        - read_file  # No write access in prod

{
  "skills": [
    {
      "id": "dev-tools",
      "type": "inline",
      "def": {
        "content": "# Development Tools\nLocal file access and debugging tools.",
        "requires": ["read_file", "write_file"]
      }
    },
    {
      "id": "prod-tools",
      "type": "inline",
      "def": {
        "content": "# Production Tools\nRead-only access and monitoring tools.",
        "requires": ["read_file"]
      }
    }
  ]
}