add-agent

namespace	aiwg
name	add-agent
platforms	["all"]
description	Scaffold a new agent definition file inside an existing addon or framework

Add Agent

Scaffold a new agent definition file inside an existing addon or framework.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "I need a new agent" → scaffold agent in specified target
• "build me an agent" → scaffold agent with interactive guidance
• "write an agent for X" → scaffold agent named after the described role
• "agent for " → derive name from role, prompt for target

Trigger Patterns Reference

Pattern	Example	Action
Named add	"add agent security-auditor --to sdlc-complete"	Scaffold directly
Role description	"create an agent that reviews PRs"	Derive name, scaffold
Interactive	"add agent --interactive"	Guided mode, ask for name/target/template
Target omitted	"add agent code-reviewer"	Ask which addon or framework

Process

1. Parse Arguments

Extract from $ARGUMENTS:

• <name> — kebab-case agent name (required)
• --to <target> — addon or framework directory name (required)
• --template <type> — one of simple (default), complex, orchestrator, validator
• --interactive — enable guided design questions

If either <name> or --to is missing, ask before proceeding.

2. Validate Target

Confirm the target addon or framework exists:

# Check addons
ls agentic/code/addons/<target>/

# Check frameworks
ls agentic/code/frameworks/<target>/

If not found, report available targets and stop.

3. Interactive Design (if --interactive)

Ask the following before generating:

1. Role: What is this agent's primary role?
2. Expertise: What domains or technologies does it specialize in?
3. Responsibilities: What are its 3-5 key responsibilities?
4. Tools needed: Which tools does it require? (Read, Write, Bash, Grep, WebFetch, Task)
5. Model tier: haiku (fast/utility), sonnet (balanced), opus (reasoning-heavy)
6. Output format: What structured output should it produce?

4. Select Template

Template	Use When	Default Model	Tools
simple	Single-purpose utility agent	haiku	Read, Write
complex	Domain expert, reviewer, analyst	sonnet	Read, Write, Grep
orchestrator	Coordinates other agents	opus	Task
validator	Read-only quality/compliance gate	haiku	Read, Grep

5. Run Scaffolding

aiwg add-agent <name> --to <target> --template <type>

This generates <target>/agents/<name>.md with the appropriate frontmatter and section stubs.

6. Customize the Generated File

The generated agent file requires population of these sections:

---
name: <name>
description: <one-sentence purpose>
model: <claude-haiku-4-5|claude-sonnet-4-6|claude-opus-4-7>  # Pin specific variant; bare aliases (`sonnet`) inherit the parent session's 1M-context attributes and hit the usage-credit gate on subagent dispatch. See #1442.
tools: <comma-separated tool list>
category: <phase or domain>
---

# Agent Title

[Role description]

## Expertise

[Domain knowledge and skills]

## Responsibilities

[Numbered list of what this agent does]

## Workflow

[How it approaches tasks — research, draft, validate, output]

## Output Format

[Expected structure of deliverables]

7. Validate Against 10 Golden Rules

After creation, run the agent linter:

aiwg lint agents <target>/agents/<name>.md --verbose

Key checks:

• Single responsibility (no "and" overload in description)
• Minimal tools (0-3 tools, each justified)
• Explicit I/O contract defined
• Model tier matches task complexity

8. Update Manifest

The CLI tool updates <target>/manifest.json automatically. Verify:

{
  "agents": ["existing-agent", "<name>"]
}

Generated Structure

<target>/agents/<name>.md

Manifest updated: <target>/manifest.json

Output Format

Agent Created: <name>
─────────────────────
Location: <target>/agents/<name>.md
Template:  <type>
Model:     <model>

Created:
  ✓ <target>/agents/<name>.md
  ✓ manifest.json updated

Validation:
  ✓ Single responsibility
  ✓ Tool count within limit
  ✓ I/O contract defined

Next Steps:
  1. Edit Expertise section with domain knowledge
  2. Define Responsibilities (3-5 items)
  3. Specify Output Format structure
  4. Run: aiwg lint agents <target>/agents/<name>.md

Examples

Example 1: Simple utility agent

User: "add agent dependency-auditor --to aiwg-utils"

Action:

aiwg add-agent dependency-auditor --to aiwg-utils

Result: agentic/code/addons/aiwg-utils/agents/dependency-auditor.md scaffolded with simple template (haiku, Read + Grep tools).

Example 2: Complex domain expert

User: "create a threat modeling agent for sdlc-complete"

Extraction: name=threat-modeler, target=sdlc-complete, template=complex

Action:

aiwg add-agent threat-modeler --to sdlc-complete --template complex

Result: agentic/code/frameworks/sdlc-complete/agents/threat-modeler.md scaffolded with sonnet model, Read/Write/Grep tools.

Example 3: Interactive guided creation

User: "add agent --interactive --to sdlc-complete"

Process: Guided questions gather role, expertise, responsibilities, tools, and model tier before scaffolding.

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/devkit-create-agent/SKILL.md — Devkit equivalent (interactive design)
• @$AIWG_ROOT/src/cli/handlers/scaffolding.ts — CLI handler implementation
• @$AIWG_ROOT/docs/cli-reference.md — Full CLI reference
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/ — Example agent definitions