create-agent

Create LearningAgent

Create a new LearningAgent and guide the user through initial configuration.

Arguments

$ARGUMENTS contains the agent name and an optional template path, separated by whitespace.

• Agent name (required): Use dashes for multi-word names (e.g., rails-activejob). If not provided, ask the user what to name the agent.
• Template agent path (optional): Path to an existing learning agent directory (e.g., .deepwork/learning-agents/my-existing-agent). If provided, the new agent is seeded with the template's core-knowledge.md, topics/, and learnings/ as a starting point. The user can then customize the copied content during configuration.

Procedure

Step 1: Validate and Run Scaffold Script

Parse $ARGUMENTS to extract the agent name (first word) and optional template path (second word, if present).

If the name contains spaces or uppercase letters, normalize to lowercase dashes (e.g., "Rails ActiveJob" → rails-activejob).

Check .claude/agents/ for an existing file matching <agent-name>.md. If found, inform the user of the conflict and ask how to proceed.

If a template path was provided, verify it exists and contains core-knowledge.md. If not, inform the user and ask how to proceed.

Run the scaffold script:

# Without template:
${CLAUDE_PLUGIN_ROOT}/scripts/create_agent.sh <agent-name>

# With template:
${CLAUDE_PLUGIN_ROOT}/scripts/create_agent.sh <agent-name> <template-agent-path>

If the script reports that directories already exist, inform the user and ask whether to proceed with updating the configuration or stop.

If a template was used, inform the user what was copied (the script output will list the counts).

Step 2: Configure the Agent

Ask the user about the agent's domain:

• What domain or area of expertise does this agent cover?
• What kinds of tasks will it be delegated to handle?

If a template was used, read the copied core-knowledge.md and present it to the user. Ask if they want to keep it as-is, modify it for the new agent's focus, or replace it entirely.

Based on their answers, update:

1. .deepwork/learning-agents/<agent-name>/core-knowledge.md: If created from scratch, replace the TODO content with the agent's core expertise in second person ("You should...", "You are an expert on..."). If seeded from a template, adapt the content to reflect the new agent's specific focus area.

   Example:

   You are an expert on Rails ActiveJob. You understand the full job lifecycle,
   supported adapters (Sidekiq, Resque, DelayedJob), retry configuration with
   exponential backoff, and callback patterns. You should always check the adapter
   documentation before recommending queue-specific features.
   

2. .claude/agents/<agent-name>.md frontmatter: Replace the TODO placeholders:

   • name: The agent's display name (human-readable, e.g., "Rails ActiveJob Expert")
   • description: A concise description for deciding when to invoke this agent (2-3 sentences max). Example: "Expert on Rails ActiveJob patterns including job creation, queue configuration, and retry logic. Invoke when delegating background job tasks or debugging queue issues."

Step 3: Seed Initial Knowledge (Optional)

If a template was used and topics/learnings were copied, list what was copied and ask if the user wants to review, remove, or add to them.

Otherwise, ask the user if they want to seed any initial topics or learnings. If yes, create files using these formats:

Topic file (.deepwork/learning-agents/<agent-name>/topics/<topic-name>.md):

---
name: "Topic Name"
keywords:
  - keyword1
  - keyword2
last_updated: "YYYY-MM-DD"
---

Detailed documentation about this topic area...

Learning file (.deepwork/learning-agents/<agent-name>/learnings/<learning-name>.md):

---
name: "Learning Name"
last_updated: "YYYY-MM-DD"
summarized_result: |
  One sentence summary of the key takeaway.
---

## Context
...
## Key Takeaway
...

Step 4: Summary

Output in this format:

## Agent Created: <agent-name>

**Files created/modified:**
- `.deepwork/learning-agents/<agent-name>/core-knowledge.md` — core expertise
- `.deepwork/learning-agents/<agent-name>/topics/` — topic documentation
- `.deepwork/learning-agents/<agent-name>/learnings/` — experience-based insights
- `.claude/agents/<agent-name>.md` — Claude Code agent file

Then output the following restart warning exactly as written, including the emphasis markers and blank lines. This is critical — the user WILL NOT be able to use the new agent without doing this:

---

## !! IMPORTANT — YOU MUST RESTART CLAUDE CODE !!

Claude Code does NOT hot-reload agent files. The agent you just created
is **invisible** to Claude until you restart.

**Do this now:**

1. Exit this Claude Code session (type `/exit` or Ctrl+C)
2. Restart with: `claude -c` (this continues your conversation)
3. The new agent will then be available via the Task tool

If you skip this step, Claude will not find the agent when you try to use it.

---

After the restart warning, output:

**Usage (after restart):**
  Use the Task tool with `name: "<agent-name>"` to invoke this agent.

**Learning cycle:**
  The post-Task hook will automatically track sessions. Run `/learning-agents learn`
  after sessions to identify and incorporate learnings.

Guardrails

• Do NOT overwrite existing files without user confirmation
• Do NOT create agents with names that conflict with existing Claude Code agents
• Use dashes consistently in folder names and .claude/agents/ filenames
• Keep the .claude/agents/ description field concise (2-3 sentences max)