> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillbridgedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Custom Agents

> Build your own specialized AI agents tailored to specific educational needs

# Creating Custom Agents

While SkillShop's system agents cover many common educational tasks, you can create custom agents tailored to your specific needs, teaching style, or unique educational contexts. Custom agents allow you to define specialized expertise, behavior, and tool access.

<Note>
  Custom agents use the same powerful infrastructure as system agents but can be personalized for your specific educational requirements and workflows.
</Note>

## When to Create Custom Agents

Consider creating custom agents when you need:

<CardGroup cols={2}>
  <Card title="Specialized Expertise" icon="brain">
    Subject-specific knowledge not covered by system agents (e.g., specialized medical training, niche technical skills)
  </Card>

  <Card title="Unique Teaching Style" icon="user">
    Agents that match your specific pedagogical approach or institutional requirements
  </Card>

  <Card title="Custom Workflows" icon="workflow">
    Agents designed for your organization's specific processes and procedures
  </Card>

  <Card title="Targeted Audiences" icon="users">
    Agents optimized for specific student populations, age groups, or learning contexts
  </Card>
</CardGroup>

## Agent Creation Process

### Step 1: Access Agent Creation

<Steps>
  <Step title="Navigate to Agents">
    Go to the Agents section in SkillShop's main navigation
  </Step>

  <Step title="Click Create Agent">
    Use the "Create Agent" button in the top-right corner of the agents page
  </Step>

  <Step title="Choose Agent Type">
    Select "Custom Agent" to create a new agent from scratch
  </Step>
</Steps>

### Step 2: Basic Configuration

<Tabs>
  <Tab title="Identity">
    **Agent Name**: Unique identifier (no spaces, lowercase with underscores)

    ```text theme={null}
    Example: "chemistry_lab_assistant"
    ```

    **Display Name**: Human-readable name shown in the interface

    ```text theme={null}
    Example: "Chemistry Lab Assistant"
    ```

    **Description**: Clear explanation of the agent's purpose and capabilities

    ```text theme={null}
    Example: "Specialized assistant for high school chemistry lab activities, safety protocols, and experiment guidance"
    ```
  </Tab>

  <Tab title="Category">
    Choose from available categories:

    * **General Assistant**: Multi-purpose agents
    * **Curriculum Design**: Learning path and course structure specialists
    * **Content Creation**: Material and resource generators
    * **Assessment Design**: Quiz and test creators
    * **Tutoring**: Student support and personalized learning
    * **Custom**: Unique specializations not covered by other categories
  </Tab>

  <Tab title="Visibility">
    **Public Agents**: Visible to all users in your organization
    **Private Agents**: Only visible to you (the creator)

    <Note>
      You can change visibility settings later if needed.
    </Note>
  </Tab>
</Tabs>

### Step 3: System Prompt Design

The system prompt is the most important part of your agent - it defines the agent's personality, expertise, and behavior patterns. SkillShop uses advanced template processing that allows you to create dynamic, context-aware prompts.

#### Template Variables

Your system prompts can include template variables that are automatically filled in during conversations:

<Tabs>
  <Tab title="Built-in Variables">
    These variables are automatically available in all agent prompts:

    ```text theme={null}
    {{ message }}     - The user's current message or request
    {{ agentName }}   - Your agent's unique identifier  
    {{ userId }}      - The current user's ID
    {{ sessionId }}   - The conversation session ID
    ```

    **Example usage**:

    ```text theme={null}
    You are helping with this request: {{ message }}

    As {{ agentName }}, your role is to provide specialized assistance.
    ```
  </Tab>

  <Tab title="Variable Syntax">
    SkillShop supports enhanced template syntax for different variable types:

    * **`{{ variable }}`** - Required variable (error if missing)
    * **`{{ variable! }}`** - Explicitly required (same as above, more clear)
    * **`{{ variable? }}`** - Optional variable (empty if missing)

    **Example**:

    ```text theme={null}
    Subject: {{ subject! }}
    Grade Level: {{ gradeLevel? }}
    Additional Context: {{ context? }}
    ```
  </Tab>

  <Tab title="Advanced Features">
    **Document Inclusion**: Reference external documentation

    ```text theme={null}
    {{ docs/chemistry/safety-protocols.md }}
    ```

    **Prompt References**: Include other prompts

    ```text theme={null}
    {{ prompt/content_analysis }}
    ```

    **Nested Variables**: Access complex data

    ```text theme={null}
    Student: {{ user.profile.name? }}
    School: {{ user.school.name? }}
    ```
  </Tab>
</Tabs>

#### Prompt Structure

<Accordion title="Identity and Role">
  Define who the agent is and what they do:

  ```text theme={null}
  You are a Chemistry Lab Assistant specialized in high school chemistry education. 
  Your primary role is to help students and teachers with laboratory activities, 
  safety protocols, and experimental procedures.
  ```
</Accordion>

<Accordion title="Expertise and Knowledge">
  Specify the agent's areas of expertise:

  ```text theme={null}
  Your expertise includes:
  - Laboratory safety protocols and procedures
  - Common high school chemistry experiments
  - Equipment usage and maintenance
  - Chemical properties and reactions
  - Troubleshooting experimental problems
  - Data analysis and interpretation
  ```
</Accordion>

<Accordion title="Behavior and Personality">
  Define how the agent should interact:

  ```text theme={null}
  Your communication style should be:
  - Clear and safety-focused
  - Patient and encouraging with students
  - Detailed when explaining procedures
  - Always emphasizing safety first
  - Supportive of student curiosity and learning
  ```
</Accordion>

<Accordion title="Constraints and Guidelines">
  Set important limitations and guidelines:

  ```text theme={null}
  Important guidelines:
  - Always prioritize safety in all recommendations
  - Encourage proper lab procedures and protocols
  - When unsure about safety, recommend consulting a teacher
  - Provide step-by-step instructions for complex procedures
  - Use age-appropriate language for high school students
  ```
</Accordion>

#### Example Complete Prompt with Template Variables

```text theme={null}
You are a Chemistry Lab Assistant specialized in high school chemistry education. 
Your primary role is to help students and teachers with laboratory activities, 
safety protocols, and experimental procedures.

Current Request: {{ message }}
Student Level: {{ gradeLevel? }}
Safety Context: {{ safetyLevel? }}

Your expertise includes:
- Laboratory safety protocols and procedures
- Common high school chemistry experiments (acid-base reactions, 
  stoichiometry labs, gas laws, etc.)
- Equipment usage and maintenance
- Chemical properties and reactions
- Troubleshooting experimental problems
- Data analysis and interpretation

Your communication style should be:
- Clear and safety-focused
- Patient and encouraging with students
- Detailed when explaining procedures
- Always emphasizing safety first
- Supportive of student curiosity and learning

Important guidelines:
- Always prioritize safety in all recommendations
- Encourage proper lab procedures and protocols
- When unsure about safety, recommend consulting a teacher
- Provide step-by-step instructions for complex procedures
- Use age-appropriate language for high school students
- Reference relevant safety data sheets when appropriate

When helping with experiments, always include:
1. Safety considerations and required PPE
2. Step-by-step procedures tailored to: {{ message }}
3. Expected observations and results
4. Common troubleshooting tips
5. Connections to underlying chemical principles

{{ docs/chemistry/safety-protocols.md }}
```

<Note>
  The template variables (`{{ message }}`, `{{ gradeLevel? }}`, etc.) are automatically filled in when users interact with your agent, making responses more personalized and contextual.
</Note>

### Step 4: Model Configuration

<Tabs>
  <Tab title="Model Selection">
    Choose the AI model that powers your agent:

    **Claude 3.5 Haiku**: Fast, efficient, good for simple tasks
    **Claude 3.5 Sonnet**: Balanced performance and capability
    **Claude 3 Opus**: Most capable, best for complex reasoning
    **GPT-4**: Alternative high-performance option

    <Tip>
      Start with Claude 3.5 Sonnet for most educational tasks - it provides excellent performance with reasonable speed.
    </Tip>
  </Tab>

  <Tab title="Parameters">
    **Temperature** (0.0 - 1.0): Controls creativity vs. consistency

    * **0.1-0.3**: Factual, consistent responses (good for tutoring)
    * **0.4-0.7**: Balanced creativity and consistency (good for content creation)
    * **0.8-1.0**: Highly creative responses (good for brainstorming)

    **Max Tokens**: Maximum response length

    * **2000**: Short to medium responses
    * **4000**: Detailed explanations and content
    * **8000+**: Comprehensive materials and long-form content
  </Tab>

  <Tab title="Memory Settings">
    **Memory Enabled**: Allow the agent to remember conversation context

    * **Recommended**: Enable for most educational agents
    * **Benefits**: Continuity across conversations, building on previous work
    * **Considerations**: May retain sensitive information across sessions
  </Tab>
</Tabs>

### Step 5: Tool Selection

Choose which tools your agent can access:

<AccordionGroup>
  <Accordion title="Essential Tools">
    **Data Lookup**: Access SkillShop's database of topics, skills, and content
    **Content Search**: Search educational materials and resources
    **Text Processing**: Analyze and transform text content

    <Note>
      These tools are recommended for most educational agents.
    </Note>
  </Accordion>

  <Accordion title="Specialized Tools">
    **Assessment Manager**: Create and manage assessments (for assessment-focused agents)
    **Learning Plan Manager**: Create learning plans and modules (for curriculum agents)
    **Content Discovery**: Find external educational content (for content agents)
    **Calculator**: Mathematical operations (for STEM agents)
    **Google Sheets**: Spreadsheet operations (for data-focused agents)
  </Accordion>

  <Accordion title="Advanced Tools">
    **Code Generator**: Generate and analyze code (for programming agents)
    **Issue Manager**: Manage development issues (for technical agents)
    **Agent Dispatch**: Call other agents (for orchestration agents)
  </Accordion>
</AccordionGroup>

### Step 6: Testing and Refinement

<Steps>
  <Step title="Initial Testing">
    Test your agent with sample questions and requests to verify it behaves as expected
  </Step>

  <Step title="Prompt Refinement">
    Adjust the system prompt based on testing results - add constraints, clarify behavior, or expand expertise
  </Step>

  <Step title="Tool Validation">
    Verify the agent can effectively use its assigned tools for intended tasks
  </Step>

  <Step title="User Testing">
    Have colleagues or students test the agent and provide feedback
  </Step>
</Steps>

## Advanced Agent Features

### Tool Choice Configuration

Control how your agent uses tools:

<Tabs>
  <Tab title="Auto (Recommended)">
    Let the agent decide when to use tools based on the request

    ```json theme={null}
    "toolChoice": "auto"
    ```
  </Tab>

  <Tab title="Required">
    Force the agent to use at least one tool for every response

    ```json theme={null}
    "toolChoice": "any"
    ```
  </Tab>

  <Tab title="Disabled">
    Prevent the agent from using any tools

    ```json theme={null}
    "toolChoice": "none"
    ```
  </Tab>

  <Tab title="Specific Tool">
    Force the agent to use a specific tool

    ```json theme={null}
    "toolChoice": {
      "type": "tool",
      "name": "data_lookup"
    }
    ```
  </Tab>
</Tabs>

### Context and Memory Management

Configure how your agent handles conversation context:

* **Session Continuity**: Maintain context within conversation sessions
* **Cross-Session Memory**: Remember information across different conversations
* **Context Limits**: Set maximum context length to manage performance
* **Memory Cleanup**: Automatically clear sensitive information

## Example Custom Agents

### STEM Lab Assistant

```text theme={null}
Agent Name: stem_lab_assistant
Display Name: STEM Lab Assistant
Category: Tutoring

System Prompt:
You are a STEM Lab Assistant specializing in hands-on science, technology, 
engineering, and mathematics activities for middle and high school students.

Your expertise includes:
- Laboratory safety and procedures across all STEM disciplines
- Equipment usage (microscopes, sensors, programming tools, etc.)
- Experimental design and data collection
- Mathematical modeling and analysis
- Engineering design process
- Technology integration in STEM learning

Always prioritize safety, encourage scientific thinking, and help students 
connect hands-on activities to underlying STEM principles.

Tools: data_lookup, content_search, calculator, text_processing
```

### Special Education Support Agent

```text theme={null}
Agent Name: special_education_assistant
Display Name: Special Education Assistant
Category: Tutoring

System Prompt:
You are a Special Education Assistant focused on supporting students with 
diverse learning needs and abilities.

Your expertise includes:
- Differentiated instruction strategies
- Accommodations and modifications
- Multi-sensory learning approaches
- Behavioral support strategies
- Assistive technology integration
- IEP goal alignment

Adapt your communication style to individual student needs, provide multiple 
ways to access content, and always maintain a patient, encouraging approach.

Tools: data_lookup, content_search, text_processing, learning_plan_manager
```

### Language Arts Writing Coach

```text theme={null}
Agent Name: writing_coach
Display Name: Writing Coach
Category: Tutoring

System Prompt:
You are a Writing Coach specializing in helping students develop their 
writing skills across various genres and purposes.

Your expertise includes:
- Writing process guidance (planning, drafting, revising, editing)
- Genre-specific writing strategies
- Grammar and mechanics instruction
- Peer review and feedback techniques
- Digital writing tools and platforms
- Portfolio development

Provide constructive, specific feedback that helps students grow as writers 
while maintaining their unique voice and creativity.

Tools: data_lookup, content_search, text_processing, assessment_manager
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Clear Purpose" icon="target">
    Define a specific, focused purpose for your agent rather than trying to make it do everything
  </Card>

  <Card title="Consistent Personality" icon="user">
    Maintain a consistent voice and approach throughout the system prompt
  </Card>

  <Card title="Safety First" icon="shield">
    Always include appropriate safety guidelines and constraints for your domain
  </Card>

  <Card title="Iterative Improvement" icon="refresh">
    Continuously test and refine your agent based on real usage and feedback
  </Card>
</CardGroup>

## Managing Custom Agents

### Editing Agents

* **Prompt Updates**: Modify system prompts to improve behavior
* **Tool Changes**: Add or remove tools based on usage patterns
* **Model Upgrades**: Switch to newer or more appropriate models
* **Configuration Tuning**: Adjust temperature and token limits

### Sharing Agents

* **Public Sharing**: Make agents available to your organization
* **Export/Import**: Share agent configurations with other SkillShop instances
* **Version Control**: Track changes and maintain agent versions
* **Collaboration**: Allow team members to contribute to agent development

### Performance Monitoring

* **Usage Analytics**: Track how often and how effectively your agent is used
* **Response Quality**: Monitor user satisfaction and feedback
* **Tool Usage**: Analyze which tools are most valuable for your agent
* **Cost Management**: Monitor token usage and computational costs

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="Agent Responses Are Too Generic">
    **Solution**: Add more specific expertise and constraints to your system prompt. Include domain-specific knowledge and examples. Use template variables like `{{ message }}` to make responses more contextual.
  </Accordion>

  <Accordion title="Agent Doesn't Use Tools Effectively">
    **Solution**: Explicitly mention tool usage in the system prompt and provide examples of when to use specific tools.
  </Accordion>

  <Accordion title="Agent Behavior Is Inconsistent">
    **Solution**: Lower the temperature setting and add more specific behavioral guidelines to the system prompt.
  </Accordion>

  <Accordion title="Agent Responses Are Too Long/Short">
    **Solution**: Adjust max tokens setting and include response length guidelines in the system prompt.
  </Accordion>

  <Accordion title="Template Variable Errors">
    **Possible causes**:

    * Using undefined variables in your prompt
    * Incorrect variable syntax
    * Missing required variables

    **Solutions**:

    * Use built-in variables: `{{ message }}`, `{{ agentName }}`, `{{ userId }}`, `{{ sessionId }}`
    * Check syntax: `{{ variable }}` (required), `{{ variable? }}` (optional)
    * Test your agent to ensure all variables are properly resolved
  </Accordion>

  <Accordion title="Agent Execution Fails">
    **Possible causes**:

    * Required template variables are missing
    * Invalid template syntax in system prompt
    * Referenced documents or prompts don't exist

    **Solutions**:

    * Review system prompt for template variable errors
    * Ensure referenced documents exist: `{{ docs/path/file.md }}`
    * Use optional syntax `{{ variable? }}` for non-critical variables
  </Accordion>
</AccordionGroup>

## Next Steps

<Steps>
  <Step title="Plan Your Agent">
    Identify a specific educational need not met by existing system agents
  </Step>

  <Step title="Create and Test">
    Build your agent using the creation interface and test thoroughly
  </Step>

  <Step title="Gather Feedback">
    Share with colleagues and students to gather improvement suggestions
  </Step>

  <Step title="Iterate and Improve">
    Continuously refine based on usage patterns and feedback
  </Step>

  <Step title="Explore Workflows">
    Consider creating workflow agents that combine your custom agent with others
  </Step>
</Steps>