create-agent
The create-agent skill guides users through setting up a custom, domain-specific agent by collecting specifications like name, domain, personality, model preference, and workspace folder. Use this when a user requests to build a new agent, needs a specialized assistant for a particular task domain, or wants to extend their workspace with custom AI capabilities tailored to specific workflows.
git clone --depth 1 https://github.com/evolution-foundation/evo-nexus /tmp/create-agent && cp -r /tmp/create-agent/.claude/skills/create-agent ~/.claude/skills/create-agentSKILL.md
# 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`:
```markdown
---
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`:
```markdown
---
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:
```typescript
'{agent-name}': {
icon: {IconName},
color: '{hex color from frontmatter}',
colorMuted: '{color}1F',
glowColor: '{cUse this agent when the user needs strategic architecture analysis, design tradeoffs, or read-only debugging — high-stakes decisions where vague advice is worse than no advice. Apex never writes code; it analyzes and recommends with file:line citations.\n\nExamples:\n\n- user: \"why is the bot runtime hanging on reconnect?\"\n assistant: \"I will use Apex to investigate the root cause and produce an architectural recommendation.\"\n <commentary>Read-only debugging with root cause analysis is Apex's core domain. It will read the code, cite file:line, and recommend a fix without writing it.</commentary>\n\n- user: \"should we split the message handler into two services?\"\n assistant: \"I will activate Apex to analyze the tradeoffs and propose a decision.\"\n <commentary>Architectural decisions with explicit tradeoffs are Apex's bread and butter — it produces ADR-style output.</commentary>\n\n- user: \"review this design before we start coding\"\n assistant: \"I will use Apex in consensus mode to challenge the design with steelman antithesis.\"\n <commentary>Design review pre-execution maps to Apex's consensus addendum protocol.</commentary>
Use this agent when dealing with HR and People Operations activities. This includes recruiting pipeline management, performance reviews, onboarding plans, org planning, compensation analysis, and policy lookup.\\n\\nExamples:\\n\\n- user: \"What is the status of our recruiting pipeline?\"\\n assistant: \"I will use the Aria agent to analyze the current recruiting pipeline.\"\\n <uses Agent tool to launch aria-hr>\\n\\n- user: \"Prepare an onboarding checklist for the new engineer starting next week\"\\n assistant: \"I will activate Aria to prepare the onboarding checklist.\"\\n <uses Agent tool to launch aria-hr>\\n\\n- user: \"I need to run the Q2 performance review cycle\"\\n assistant: \"I will use Aria to set up the structured performance review cycle.\"\\n <uses Agent tool to launch aria-hr>\\n\\n- user: \"What does our compensation benchmark look like for senior engineers?\"\\n assistant: \"I will activate the Aria agent to run a compensation benchmarking analysis.\"\\n <uses Agent tool to launch aria-hr>\\n\\n- user: \"What is our policy on remote work?\"\\n assistant: \"I will use Aria to look up the remote work policy.\"\\n <uses Agent tool to launch aria-hr>
Use this agent when the user needs help managing projects — creating new projects, reviewing project status, updating project documentation, breaking down goals into actionable tasks, or navigating the project lifecycle. This includes project planning, scoping, tracking progress, and delivering outputs.\\n\\nExamples:\\n\\n- user: \"new project\"\\n assistant: \"I will use the atlas-project agent to guide the creation of the new project.\"\\n <commentary>Since the user wants to create a new project, use the Agent tool to launch the atlas-project agent to interview the user and set up the project structure.</commentary>\\n\\n- user: \"what is the status of the main project?\"\\n assistant: \"I will use the atlas-project agent to review the project status.\"\\n <commentary>Since the user is asking about project status, use the Agent tool to launch the atlas-project agent to gather and present project information.</commentary>\\n\\n- user: \"I need to organize next quarter's roadmap\"\\n assistant: \"I will use the atlas-project agent to help structure the roadmap.\"\\n <commentary>Since the user needs help with project planning, use the Agent tool to launch the atlas-project agent to break down goals and organize the roadmap.</commentary>
Use this agent when there is a clear, well-scoped task to implement in code — a feature, fix, or refactor with defined acceptance criteria. Bolt prefers the smallest viable change, runs verification after each step, and escalates to @apex-architect after 3 failed attempts on the same issue.\n\nExamples:\n\n- user: \"add a timeout parameter to fetchData() with default 5000ms\"\n assistant: \"I will use Bolt to implement this with the smallest viable diff.\"\n <commentary>Clear, scoped task. Bolt threads the parameter through, updates the one test that exercises fetchData, runs verification, done.</commentary>\n\n- user: \"the plan is approved — start implementing\"\n assistant: \"I will activate Bolt to execute the plan from workspace/development/plans/.\"\n <commentary>Hand-off from @compass-planner with an approved plan file. Bolt reads the plan and executes step by step.</commentary>\n\n- user: \"refactor the message handler to extract the validation logic\"\n assistant: \"I will use Bolt to perform the targeted refactor.\"\n <commentary>Specific refactor with clear boundaries — Bolt's domain.</commentary>
Use this agent for UI/UX design and implementation — production-grade interfaces with intentional aesthetic. Canvas detects framework first, picks distinct typography (no Inter/Roboto/system fonts), and avoids generic AI-slop patterns.\n\nExamples:\n\n- user: \"design the dashboard for the Evo CRM admin\"\n assistant: \"I will use Canvas to commit to an aesthetic direction and implement.\"\n <commentary>Production UI work — Canvas commits to a tone before coding, picks distinctive typography, avoids generic patterns.</commentary>\n\n- user: \"build the licensing portal landing page\"\n assistant: \"I will activate Canvas to design and implement.\"\n <commentary>Web product design — Canvas's domain. Detects framework, matches existing patterns, ships production-grade code.</commentary>
Use this agent when the user needs operational and strategic support — managing agenda, emails, tasks, meetings, prioritization, decision-making, research, documentation, or any form of organized execution. This is the default agent for day-to-day work.\\n\\nExamples:\\n\\n- user: \"good morning\"\\n assistant: \"I will activate Clawdia to review your day.\"\\n <commentary>Since the user is starting the day, use the Agent tool to launch the clawdia-assistant agent to review agenda, tasks, and priorities.</commentary>\\n\\n- user: \"what do I have today?\"\\n assistant: \"I will use Clawdia to check your agenda and tasks for the day.\"\\n <commentary>The user wants to know their schedule. Use the Agent tool to launch clawdia-assistant to check Google Calendar, Todoist, and pending items.</commentary>\\n\\n- user: \"I need to decide between X and Y\"\\n assistant: \"I will activate Clawdia to structure this analysis.\"\\n <commentary>The user needs help with a decision. Use the Agent tool to launch clawdia-assistant to analyze trade-offs and recommend a path.</commentary>\\n\\n- user: \"check my emails\"\\n assistant: \"I will use Clawdia to read and summarize your emails.\"\\n <commentary>The user wants email triage. Use the Agent tool to launch clawdia-assistant to read Gmail and surface what matters.</commentary>\\n\\n- user: \"what are my tasks?\"\\n assistant: \"I will activate Clawdia to list your open tasks.\"\\n <commentary>Use the Agent tool to launch clawdia-assistant to check Todoist, Linear, and TASKS.md for open items.</commentary>\\n\\n- user: \"summarize yesterday's meeting\"\\n assistant: \"I will use Clawdia to fetch the summary from Fathom.\"\\n <commentary>The user wants meeting notes. Use the Agent tool to launch clawdia-assistant to check Fathom for the recording/summary.</commentary>
Use this agent when the user needs a structured work plan from a vague idea, when they say 'plan this' or 'let's plan', or when execution should not start until the work is scoped into 3-6 actionable steps. Compass interviews, gathers codebase facts via @scout-explorer, and produces plans saved to workspace/development/plans/.\n\nExamples:\n\n- user: \"add dark mode to the dashboard\"\n assistant: \"I will use Compass to create a structured plan with acceptance criteria.\"\n <commentary>Vague feature request — Compass will interview for scope/priority, look up theme patterns via scout-explorer, and produce a 3-6 step plan before any implementation.</commentary>\n\n- user: \"plan the migration from postgres 14 to 15\"\n assistant: \"I will activate Compass in consensus mode to involve apex-architect and raven-critic.\"\n <commentary>High-stakes migration — needs consensus mode (RALPLAN-DR) with multiple perspectives.</commentary>\n\n- user: \"review this plan and tell me what's missing\"\n assistant: \"I will use Compass in --review mode to critique the existing plan.\"\n <commentary>Existing plan critique is Compass's review mode.</commentary>
Use this agent when dealing with data analysis, SQL queries, dashboards, visualizations, statistical analysis, and data validation activities.\\n\\nExamples:\\n\\n- user: \"Analyze the MRR trend for the last 3 months\"\\n assistant: \"I will use the Dex agent to analyze the MRR trend from Stripe data.\"\\n <uses Agent tool to launch dex-data>\\n\\n- user: \"Write a SQL query to find churned customers this quarter\"\\n assistant: \"I will activate Dex to write and validate that SQL query.\"\\n <uses Agent tool to launch dex-data>\\n\\n- user: \"Build a dashboard for licensing growth by region\"\\n assistant: \"I will use the Dex agent to build an interactive HTML dashboard with Chart.js.\"\\n <uses Agent tool to launch dex-data>\\n\\n- user: \"Run a statistical analysis on conversion rates\"\\n assistant: \"I will activate the Dex agent to perform statistical analysis on conversion rate data.\"\\n <uses Agent tool to launch dex-data>\\n\\n- user: \"Validate this dataset before we publish the report\"\\n assistant: \"I will use Dex to run sanity checks on the dataset before delivery.\"\\n <uses Agent tool to launch dex-data>