Creating Agents

Custom agents let you define specialized AI personas beyond the built-in archetypes. You can create agents on the fly, bundle them with skills, or define them in plugins.

Quick Start

Via Tool

CreateAgent(
    name="api-specialist",
    description="Expert in REST API design and implementation",
    system_prompt="You are an API design specialist who follows OpenAPI 3.1 standards. Focus on clean resource naming, proper HTTP verbs, pagination, and error responses."
)

Via Plugin

Create .gee/plugins/my-plugin/agents/api-specialist.md:

---
name: api-specialist
description: Expert in REST API design and implementation
model: claude-sonnet
---

You are an API design specialist who follows OpenAPI 3.1 standards.

## Priorities

1. Clean resource naming and URL structure
2. Proper HTTP verb usage
3. Consistent error response format
4. Pagination and filtering patterns
5. Authentication and authorization

Via Skill Frontmatter

Agents can be bundled directly in a skill’s SKILL.md:

---
name: api-toolkit
description: API development toolkit
agents:
  - name: api-designer
    description: API schema designer
    model: claude-opus
    system_prompt: |
      You are an API schema designer...
  - name: api-tester
    description: API test writer
    model: claude-sonnet
    system_prompt: |
      You write comprehensive API tests...
---

Agent Configuration

Field	Required	Description
name	Yes	Agent identifier
description	Yes	Short description shown in agent list
model	No	AI model to use (default: session model)
system_prompt	Yes	Instructions that define agent behavior

Using Custom Agents

/agent api-specialist         # Switch to your custom agent
/delegate api-specialist Design the user management API

Agent Sources

Source	Persistence	Priority
Built-in archetypes	Always available	Lowest
Skill-bundled	While skill is active	Medium
Plugin-defined	While plugin is installed	Medium
User-created	Until deleted	Highest

When multiple agents share the same name, higher-priority sources override lower ones.

Deleting Agents

DeleteAgent(agent_name="api-specialist")

Only works for agents you created. Built-in archetypes and skill/plugin agents can’t be deleted this way.

Next Steps

• Agents & Delegation — how agents work
• Creating Skills — bundle agents with skills
• Building Plugins — multi-component plugins