Add template agent support to create-agent skill (#226)

* Add template agent support to create-agent skill

Allow seeding a new LearningAgent from an existing one by passing an
optional template path. Copies core-knowledge.md, topics, and learnings
from the template as a starting point, which the user can then customize.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add requirements and tests for template agent creation

Add REQ-002.16 through REQ-002.24 covering template-based agent seeding
(validation, copying, reporting, skill guidance). Update REQ-002.5 and
REQ-002.6 to reflect the optional template argument.

Add 16 tests for create_agent.sh covering both baseline and template
flows — all passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix ruff formatting in test_create_agent_script.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nhorton

learning_agents/scripts/create_agent.sh

@@ -1,7 +1,14 @@
 #!/bin/bash
 # create_agent.sh - Create a new LearningAgent scaffold
 #
-# Usage: create_agent.sh <agent-name>
+# Usage: create_agent.sh <agent-name> [template-agent-path]
+#
+# Arguments:
+#   agent-name           Name for the new agent (use dashes for multi-word)
+#   template-agent-path  Optional path to an existing learning agent directory
+#                        (e.g., .deepwork/learning-agents/my-existing-agent)
+#                        If provided, copies core-knowledge.md, topics/*, and
+#                        learnings/* from the template into the new agent.
 #
 # Creates:
 #   .deepwork/learning-agents/<agent-name>/core-knowledge.md
@@ -13,12 +20,25 @@
 set -euo pipefail
 
 AGENT_NAME="${1:-}"
+TEMPLATE_PATH="${2:-}"
 
 if [ -z "$AGENT_NAME" ]; then
-    echo "Usage: create_agent.sh <agent-name>" >&2
+    echo "Usage: create_agent.sh <agent-name> [template-agent-path]" >&2
     exit 1
 fi
 
+# Validate template path if provided
+if [ -n "$TEMPLATE_PATH" ]; then
+    if [ ! -d "$TEMPLATE_PATH" ]; then
+        echo "Template agent directory not found: ${TEMPLATE_PATH}" >&2
+        exit 1
+    fi
+    if [ ! -f "$TEMPLATE_PATH/core-knowledge.md" ]; then
+        echo "Template directory missing core-knowledge.md: ${TEMPLATE_PATH}" >&2
+        exit 1
+    fi
+fi
+
 AGENT_DIR=".deepwork/learning-agents/${AGENT_NAME}"
 CLAUDE_AGENT_FILE=".claude/agents/${AGENT_NAME}.md"
 
@@ -55,8 +75,39 @@ These files let you customize how the learning cycle works for this agent. Each
 - **learning_from_issues.md** — Included during the `incorporate-learnings` step. Use this to guide how learnings are integrated — e.g., preferences for topics vs learnings, naming conventions, or areas of core-knowledge that should stay concise.
 ALG_README
 
-    # Create core-knowledge.md with TODO placeholder
-    cat > "${AGENT_DIR}/core-knowledge.md" << 'CORE_KNOWLEDGE'
+    # ========================================================================
+    # SEED FROM TEMPLATE OR CREATE EMPTY
+    # ========================================================================
+
+    if [ -n "$TEMPLATE_PATH" ]; then
+        # Copy core-knowledge.md from template
+        cp "$TEMPLATE_PATH/core-knowledge.md" "${AGENT_DIR}/core-knowledge.md"
+        echo "Copied core-knowledge.md from template"
+
+        # Copy topics (if any exist beyond .gitkeep)
+        TOPIC_COUNT=0
+        for f in "$TEMPLATE_PATH/topics/"*.md; do
+            [ -f "$f" ] || continue
+            cp "$f" "${AGENT_DIR}/topics/"
+            TOPIC_COUNT=$((TOPIC_COUNT + 1))
+        done
+        if [ "$TOPIC_COUNT" -gt 0 ]; then
+            echo "Copied ${TOPIC_COUNT} topic(s) from template"
+        fi
+
+        # Copy learnings (if any exist beyond .gitkeep)
+        LEARNING_COUNT=0
+        for f in "$TEMPLATE_PATH/learnings/"*.md; do
+            [ -f "$f" ] || continue
+            cp "$f" "${AGENT_DIR}/learnings/"
+            LEARNING_COUNT=$((LEARNING_COUNT + 1))
+        done
+        if [ "$LEARNING_COUNT" -gt 0 ]; then
+            echo "Copied ${LEARNING_COUNT} learning(s) from template"
+        fi
+    else
+        # Create core-knowledge.md with TODO placeholder
+        cat > "${AGENT_DIR}/core-knowledge.md" << 'CORE_KNOWLEDGE'
 TODO: Complete current knowledge of this domain.
 Written in second person ("You should...") because this text
 becomes the agent's system instructions. Structure it as:
@@ -66,6 +117,7 @@ becomes the agent's system instructions. Structure it as:
 4. Pitfalls to avoid
 5. Decision frameworks
 CORE_KNOWLEDGE
+    fi
 
     echo "Created agent directory: ${AGENT_DIR}"
 fi

learning_agents/skills/create-agent/SKILL.md

@@ -9,34 +9,49 @@ Create a new LearningAgent and guide the user through initial configuration.
 
 ## Arguments
 
-`$ARGUMENTS` is the agent name. Use dashes for multi-word names (e.g., `rails-activejob`). If not provided, ask the user what to name the agent.
+`$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:
 
 ```bash
-${CLAUDE_PLUGIN_ROOT}/scripts/create_agent.sh $ARGUMENTS
+# 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`**: Replace the TODO content with the agent's core expertise in second person ("You should...", "You are an expert on...").
+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:
    ```
@@ -52,7 +67,9 @@ Based on their answers, update:
 
 ### Step 3: Seed Initial Knowledge (Optional)
 
-Ask the user if they want to seed any initial topics or learnings. If yes, create files using these formats:
+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`):
 ```yaml

specs/learning-agents/REQ-002-agent-creation.md

@@ -24,12 +24,12 @@ If the agent directory `.deepwork/learning-agents/<agent-name>/` already exists,
 
 ### REQ-002.5: Scaffold Script Execution
 
-The skill MUST execute the scaffold script at `${CLAUDE_PLUGIN_ROOT}/scripts/create_agent.sh` passing the normalized agent name as the argument.
+The skill MUST execute the scaffold script at `${CLAUDE_PLUGIN_ROOT}/scripts/create_agent.sh` passing the normalized agent name as the first argument and, when a template path is provided, the template path as the second argument.
 
 ### REQ-002.6: Scaffold Script -- Agent Directory Creation
 
 The `create_agent.sh` script MUST create the following directory structure when the agent directory does not exist:
-- `.deepwork/learning-agents/<agent-name>/core-knowledge.md` -- with TODO placeholder content
+- `.deepwork/learning-agents/<agent-name>/core-knowledge.md` -- with TODO placeholder content (when no template is provided; see REQ-002.19 for template behavior)
 - `.deepwork/learning-agents/<agent-name>/topics/` -- with `.gitkeep`
 - `.deepwork/learning-agents/<agent-name>/learnings/` -- with `.gitkeep`
 - `.deepwork/learning-agents/<agent-name>/additional_learning_guidelines/` -- containing `README.md`, `issue_identification.md`, `issue_investigation.md`, and `learning_from_issues.md`
@@ -75,3 +75,39 @@ Upon completion, the skill MUST output a summary listing all files created or mo
 ### REQ-002.15: No Overwrites Without Confirmation
 
 The skill MUST NOT overwrite any existing file without explicit user confirmation.
+
+### REQ-002.16: Scaffold Script -- Template Agent Argument
+
+The `create_agent.sh` script MUST accept an optional second positional argument `[template-agent-path]` specifying the path to an existing LearningAgent directory. When not provided, the script MUST behave identically to the non-template flow (creating TODO placeholder content in `core-knowledge.md`).
+
+### REQ-002.17: Scaffold Script -- Template Validation -- Directory Existence
+
+When a template path argument is provided, the script MUST verify that the path is an existing directory. If the directory does not exist, the script MUST print an error message containing the path to stderr and exit with code 1.
+
+### REQ-002.18: Scaffold Script -- Template Validation -- Core Knowledge Required
+
+When a template path argument is provided and the directory exists, the script MUST verify that the template directory contains a `core-knowledge.md` file. If the file is missing, the script MUST print an error message containing the path to stderr and exit with code 1.
+
+### REQ-002.19: Scaffold Script -- Template Seeding -- Core Knowledge
+
+When a valid template path is provided, the script MUST copy `core-knowledge.md` from the template directory into the new agent's directory instead of creating the TODO placeholder content.
+
+### REQ-002.20: Scaffold Script -- Template Seeding -- Topics
+
+When a valid template path is provided, the script MUST copy all `.md` files from the template's `topics/` directory into the new agent's `topics/` directory. If no `.md` files exist in the template's `topics/` directory, the new agent's `topics/` directory MUST remain empty (aside from `.gitkeep`).
+
+### REQ-002.21: Scaffold Script -- Template Seeding -- Learnings
+
+When a valid template path is provided, the script MUST copy all `.md` files from the template's `learnings/` directory into the new agent's `learnings/` directory. If no `.md` files exist in the template's `learnings/` directory, the new agent's `learnings/` directory MUST remain empty (aside from `.gitkeep`).
+
+### REQ-002.22: Scaffold Script -- Template Copy Reporting
+
+When files are copied from a template, the script MUST output a confirmation message for the core-knowledge copy. The script MUST output the count of copied topic files when at least one topic was copied. The script MUST output the count of copied learning files when at least one learning was copied.
+
+### REQ-002.23: Skill -- Template Configuration Guidance
+
+When a template was used, the skill MUST read the copied `core-knowledge.md` and present it to the user, asking whether to keep it as-is, modify it for the new agent's focus, or replace it entirely. The skill MUST also list any copied topics and learnings and offer the user the opportunity to review, remove, or add to them.
+
+### REQ-002.24: Skill -- Template Argument Parsing
+
+The skill MUST parse `$ARGUMENTS` to extract the agent name (first token) and an optional template path (second token). Both tokens MUST be passed to the scaffold script as separate positional arguments.