create-agent

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 `.claude/agent-memory/custom-{name}/` folder.

## Working Folder

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

**Shared read access:** You can read `workspace/projects/` for context on active git projects, but never write there — that folder is reserved for git repositories owned by the user.

> **Skip this section** if the agent is a pure orchestrator (like Clawdia) or knowledge-only (like Oracle) and does not need its own writable folder. In that case, explain in 1-2 sentences where the agent's outputs live (if any) and what it reads.

## Your Domain

{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

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

## How You Work

1. Always read your memory folder first: `.claude/agent-memory/custom-{name}/`
2. {workflow step}
3. {workflow step}
4. Save learnings to your memory folder

## Skills You Can Use

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

## Anti-patterns

- 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 `config/workspace.yaml`

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}/