create-agent

name	create-agent
description	Create a new custom agent for the workspace. Guides the user through defining agent name, domain, personality, skills, model, and memory folder. Use when the user says 'create an agent', 'new agent', 'add an agent', 'I need a custom agent', or wants to create a specialized agent for a specific domain.

Create Custom Agent

Guide the user through creating a new custom agent that extends the workspace with a specialized domain.

What You're Building

A custom agent is a .md file in .claude/agents/ with the custom- prefix. It has:

• A system prompt defining personality, domain, and behavior
• A slash command in .claude/commands/
• A persistent memory folder in .claude/agent-memory/
• Optional skills it can use

Custom agents are gitignored (the custom- prefix triggers this) — they're personal to your workspace.

Step 1: Understand the Agent

Ask the user:

1. What domain should this agent cover? (e.g., "DevOps monitoring", "customer support", "legal review")
2. What name? Suggest a short, memorable name. The final file will be custom-{name}.md
3. What should it do? Key responsibilities and tasks
4. What personality/tone? (technical, friendly, formal, concise)
5. Which model? Default: sonnet. Use opus for complex reasoning tasks
6. What color? For the dashboard card. Suggest a hex color that fits the domain (e.g., #FF6B6B for alerts, #4ECDC4 for monitoring)
7. What working folder? The agent's writable folder inside workspace/. Use a sector name (not the agent's name) for easy navigation. Examples: workspace/devops/, workspace/support/, workspace/qa/. Some agents (pure orchestrators or knowledge agents) may not need one — in that case, skip the ## Working Folder section.

Step 2: Generate the Agent File

Create .claude/agents/custom-{name}.md:

---
name: custom-{name}
description: "{one-line description of the agent's domain}"
model: sonnet
color: "{hex color}"
---

# {Agent Display Name}

You are **{Agent Display Name}**, a specialized agent for {domain description}.

## Workspace Context

Before starting any task, read `config/workspace.yaml` to load workspace settings:

- `workspace.owner` — who you are working for
- `workspace.company` — the company name
- `workspace.language` — **always respond and write documents in this language** (never hardcode)
- `workspace.timezone` — use for all date/time references
- `workspace.name` — the workspace name

Defer to `workspace.yaml` as the source of truth. Never hardcode language, owner, or company.

## Shared Knowledge Base

Beyond your own agent memory in `.claude/agent-memory/custom-{name}/`, you have **read and write access** to a shared knowledge base at `memory/`. Start by reading `memory/index.md` — it catalogs everything available.

- `memory/index.md` — catalog of the shared knowledge base (read first)
- `memory/people/` — profiles of team members, partners, vendors
- `memory/projects/` — project context and history
- `memory/context/company.md` — organizational structure, tools, ceremonies
- `memory/glossary.md` — internal terms, acronyms, nicknames
- `memory/trends/` — weekly metric snapshots

**Read from `memory/` whenever:** the user mentions a person by name or nickname, uses an internal acronym, refers to a project by shorthand, or needs company context.

**Write to `memory/` when:** you learn something durable and shared — either because the user asks or because the context clearly requires it. Ephemeral or agent-specific notes stay in your own  folder.



Your workspace folder:  — {what goes here: outputs, reports, artifacts}. Create the directory if it does not exist. All outputs you produce go here.

 You can read  for context on active git projects, but never write there — that folder is reserved for git repositories owned by the user.





{Detailed description of what this agent handles. Be specific about:}
 What tasks fall under this domain
 What data sources it accesses
 What outputs it produces



 {personality trait 1}
 {personality trait 2}
 {personality trait 3}



 Always read your memory folder first: 
 {workflow step}
 {workflow step}
 Save learnings to your memory folder



{List relevant existing skills or note that custom skills can be created}



 Do NOT {thing to avoid}
 Do NOT {thing to avoid}
 Do NOT mix with other agent domains
 Do NOT hardcode language, owner, or company — always defer to 

Naming the Working Folder

Use the sector/domain name, not the agent's name:

Good (sector)	Bad (agent name)
workspace/devops/	workspace/devon/
workspace/qa/	workspace/quinn/
workspace/security/	workspace/sentinel/

Why: when the user navigates the filesystem, they think in terms of work areas, not agent identities. If you later rename the agent, the folder stays stable.

Step 3: Generate the Slash Command

Create .claude/commands/custom-{name}.md:

---
description: "{short description} — custom agent"
allowed-tools: ["Agent"]
---

Launch the custom-{name} agent.

Use the Agent tool with `subagent_type: "custom-{name}"` to handle this request. The agent has its own memory in `.claude/agent-memory/custom-{name}/` and its system prompt in `.claude/agents/custom-{name}.md`.

Step 4: Register in Dashboard (core agents only)

If the agent does NOT have the custom- prefix (i.e., it's a core agent that will be committed to the repo), add it to AGENT_META in dashboard/frontend/src/pages/Agents.tsx:

1. Add the icon import from lucide-react at the top of the file
2. Add an entry to the AGENT_META object:

'{agent-name}': {
  icon: {IconName},
  color: '{hex color from frontmatter}',
  colorMuted: '{color}1F',
  glowColor: '{color}26',
  command: '/{command-name}',
  label: '{domain label}',
},

Without this step, the agent card in the dashboard will show a generic icon and no /command badge.

Skip this step for custom agents — they use DEFAULT_META with dynamic colors from frontmatter automatically.

Step 5: Create Memory Folder

mkdir -p .claude/agent-memory/custom-{name}

The memory folder is already gitignored (.claude/agent-memory/ is in .gitignore).

Step 6: Verify

Run a quick check:

ls -la .claude/agents/custom-{name}.md
ls -la .claude/commands/custom-{name}.md
ls -d .claude/agent-memory/custom-{name}/

Tell the user:

• Agent created: custom-{name}
• Invoke with: /custom-{name} in Claude Code
• Visible in dashboard: Agents page (with "custom" badge)
• Memory: .claude/agent-memory/custom-{name}/
• To delete: remove the 3 paths above

Agent Naming Convention

Pattern	Example	Domain
custom-devops	DevOps agent	Infrastructure monitoring
custom-support	Support agent	Customer tickets
custom-legal	Legal agent	Contract review
custom-data	Data agent	Analytics, ETL
custom-qa	QA agent	Testing, quality

Rules:

• Always use custom- prefix (required for gitignore and dashboard badge)
• Use lowercase, hyphen-separated names
• Keep names short (1-2 words after prefix)
• Avoid names that conflict with core agents

Core Agents (Do Not Duplicate)

These domains are already covered by core agents:

Agent	Domain
clawdia-assistant	Operations, calendar, email, tasks
flux-finance	Finance, Stripe, ERP
atlas-project	Projects, GitHub, Linear
pulse-community	Community, Discord, WhatsApp
pixel-social-media	Social media, content
sage-strategy	Strategy, OKRs
nex-sales	Sales, pipeline
mentor-courses	Courses, education
kai-personal-assistant	Personal, health, habits

If the user's request overlaps with a core agent, suggest using that agent instead or creating the custom agent for the specific subset that's different.

Important Notes

• Custom agents (custom-*) are gitignored — they won't be pushed to the repo
• Custom commands (custom-*) are also gitignored
• Agent memory is always gitignored (all of .claude/agent-memory/)
• The dashboard auto-discovers custom agents and shows them with a gray "custom" badge
• Custom agents can use any existing skill — just list them in the system prompt
• To create custom skills for the agent, use the skill naming convention: .claude/skills/{prefix}-{action}/