Project Agent Writer

Analyze the project's structure, conventions, and automation gaps, then design an agent to solve the user's problem. Always confirm with the user via AskUserQuestion before generating any files.

Core principle: First understand the problem, then analyze the project, then design the agent, and only generate after the user confirms.

Shared principle: This skill shares the 5 common writer disciplines with project-skill-writer / project-skill-installer / project-rules-writer. See ../project-skill-writer/references/writer-discipline.md for details.

Use Cases

Trigger when:

• The user says "create an agent", "I need an agent that...", "make AI do X every time"
• The user describes an automation need ("someone to automatically...", "I want something that monitors...")
• The user wants to build a grader, comparator, analyzer, transformer, researcher, or validator

Do not trigger when:

• The user wants to install a skill → delegate to project-skill-installer
• The user wants to create a skill → delegate to project-skill-writer
• The user wants to create a rule → delegate to project-rules-writer

Prerequisites

• Node.js >= 18
• The target project must have a writable directory for agent output

Workflow

[L1: Understand the problem]
         ↓
[L2: Project analysis]
         ↓
[L3: Agent design]
         ↓
[L4: Confirm]  ← AskUserQuestion (confirmation required)
         ↓
[L5: Generate]
         ↓
[L6: Verify]

L1: Understand the Problem

Extract the user's needs—do not ask "what do you want the agent to do?" but infer from their question:

Problem Classification

Extract the Agent Spec

Extract from the user's question:

• Role: what the agent does (extracted from the problem description)
• Input: what triggers the agent / what data it needs
• Output: what the agent produces
• Constraints: boundaries and limitations

L2: Project Analysis

Scan the project to understand context. Use search tools in parallel:

Detection Targets

Analysis Output

Project: {name}
Language: {detected language}
Existing agents: {list or "none"}
Existing skills: {list or "none"}
Automation scripts: {list or "none"}
Integration points: {API, file patterns, tools}
Conventions: {naming, output format}

L3: Agent Design

Based on the problem (L1) + analysis (L2), design the agent:

Agent: {name}
Problem: {the problem in the user's own words}
Role: {one-sentence description}
Type: {Grader|Comparator|Analyzer|Transformer|Researcher|Validator}

Trigger: {when the agent activates}
Input: {what data the agent needs}
Process: {high-level steps}
Output: {what the agent produces + format}
Constraints: {boundaries + what it should not do}

Files to create:
  - {path/to/agent.md}

L4: Confirm (AskUserQuestion required)

Critical: Present the design via AskUserQuestion before generating any files.

AskUserQuestion Call

Use AskUserQuestion:

{
  "questions": [{
    "question": "I've designed this agent based on your project. Should I create it?",
    "header": "Agent",
    "multiSelect": false,
    "options": [
      {
        "label": "Create {agent-name} (Recommended)",
        "description": "{type} agent — {one-sentence role}. Output: {path}"
      },
      {
        "label": "Adjust design",
        "description": "Let me refine the agent design before generating"
      },
      {
        "label": "Skip",
        "description": "Don't create an agent right now"
      }
    ]
  }]
}

Rules:

• Always show the designed agent's name and type
• Include the output path so the user knows where the file goes
• If multiple agent types are valid, offer alternatives:

{
  "questions": [{
    "question": "Your problem could be solved by different agent types. Which approach fits best?",
    "header": "Agent type",
    "multiSelect": false,
    "options": [
      {
        "label": "Grader agent (Recommended)",
        "description": "Evaluates outputs against expectations with pass/fail evidence"
      },
      {
        "label": "Validator agent",
        "description": "Checks correctness against rules and suggests fixes"
      },
      {
        "label": "Skip",
        "description": "Don't create an agent right now"
      }
    ]
  }]
}

• Never generate files before the user confirms
• If the user says "adjust the design", return to L3 with the feedback

L5: Generate

After the user confirms:

1. Use path discovery to determine the output path
2. Use scripts/cli.cjs init to create the agent scaffold
3. Fill in the role, input, process, and output from the L3 design
4. Set the correct project-relative output path
5. Include quality gates and constraints

Generation Command

node scripts/cli.cjs init \
  --skill-dir <this-skill-dir> \
  --name <agent-name> \
  --role "<one-sentence-role>" \
  --output-dir <project>/.agents/agents/

L6: Verify

Verify before delivery:

• The agent has a clear, specific role (not vague)
• Inputs are clearly defined and described
• The output schema is deterministic (JSON with known fields)
• Constraints are enforced (what it should not do)
• The output path is project-relative, not global
• The agent follows the conventions from the L2 analysis

Delivery Report

Agent created:
  Name: {agent-name}
  Type: {Grader|Comparator|Analyzer|...}
  Path: {project-relative path}

Usage: Launch this agent via the Task tool using its defined inputs.

Error Handling

Scope

This skill handles only:

• Analyzing the project for agent design context
• Designing the agent based on the user's problem
• Confirming the design via AskUserQuestion
• Generating the agent file to a project-relative path
• Verifying the generated agent

This skill does not handle:

• Creating skills → project-skill-writer
• Installing skills → project-skill-installer
• Creating rules → project-rules-writer
• Global agent installation (always scoped to the project)

References

• Agent patterns — Architecture patterns (grader, comparator, analyzer, transformer, researcher, validator)
• Path discovery — Output path determination (load after the design is complete)
• Example: Grader agent — Complete walkthrough of creating a grader agent