Custom Agents

Beyond the 237+ built-in agents, you can create your own custom agents tailored to your specific workflows, conventions, and tools.

---

Creating a Custom Agent

1. Go to Agents view (Cmd + 2) > Custom tab
2. Click New Agent (or Import Agent)
3. Fill in the Agent Wizard form:

Field	Description	Required
Name	Agent identifier (used internally)	Yes
Display Name	Name shown in the UI	Yes
Description	What this agent does	Yes
Target	Output format or tool the agent is optimized for	No
Domain	Area of expertise (backend, frontend, etc.)	No
System Prompt	Instructions that guide the agent's behavior	Yes
Trigger Keywords	Words in your input that auto-select this agent	No

4. Click Save Agent

---

System Prompt Best Practices

The system prompt is the most important part of a custom agent. It tells the LLM exactly how to behave.

Good Example

You are an expert React developer specializing in:
- TypeScript with strict mode
- Tailwind CSS for styling
- React Query for data fetching

When generating code:
- Always use functional components
- Include proper TypeScript types
- Add meaningful comments for complex logic

Bad Example

You are a helpful assistant that can do anything.

The more specific your system prompt, the better the agent's output. Include your preferred patterns, libraries, and coding conventions.

---

Agent Attachments

Agents can include file attachments for additional context:

1. Edit your agent > scroll to Attachments section
2. Click Add File
3. Select a file (txt, md, json supported)

Limit	Value
Max files per agent	5
Max size per file	1 MB
Warning threshold	50 KB (may affect token budget)

Great for: Style guides, API specs, code templates, example outputs.

---

Importing and Exporting Agents

Exporting

1. Go to Agents view > Custom tab
2. Click Export on the agent card
3. Save the .json file

What's exported: Name, description, domain, system prompt, trigger keywords, attachments.

What's NOT exported: Internal system configurations.

Importing

1. Go to Agents view > Custom tab
2. Click Import Agent
3. Select the .json file
4. Review and confirm

Sharing with Your Team

1. Export your custom agents
2. Share via Git, Slack, email, or any file sharing
3. Team members import the file
4. Everyone has consistent agents

---

Tips for Agent Power Users

1. Create Domain-Specific Agents

Don't use generic agents. Create specialized ones:

• my-react-frontend -- Your React conventions
• my-node-backend -- Your API patterns
• my-aws-infra -- Your cloud setup

2. Use Trigger Keywords Wisely

Add keywords that match how you naturally speak:

Trigger Keywords:
  - react
  - component
  - hook
  - useState
  - useEffect
  - frontend

3. Add Negative Triggers

Prevent wrong matches by excluding terms:

Negative Triggers:
  - backend
  - server
  - api
  - database

4. Include Examples in Attachments

Attach example outputs so the agent learns your preferred style.

5. Test Before Relying

1. Create sample inputs
2. Run through the agent
3. Check output quality
4. Adjust system prompt as needed

---

Troubleshooting

Agent not appearing in suggestions

1. Check if the agent is enabled (toggle is on)
2. Verify trigger keywords match your input
3. Check for conflicting negative triggers
4. Try locking the agent manually

Agent output is wrong style

1. Review and refine the system prompt
2. Add more specific instructions
3. Include examples in attachments
4. Check the selected optimization profile -- it affects output structure

Custom agent lost

1. Check Agents view > Custom tab
2. Custom agents are stored locally and encrypted
3. If system keyring is inaccessible, agents may not load -- restart the app

Smart Detection picks the wrong agent

1. Lock the correct agent manually
2. Adjust trigger keywords on your preferred agent
3. Increase the auto-apply confidence threshold in Settings
4. Disable Smart Detection for agents and select manually