jmagly 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 ofsimple(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:
- Role: What is this agent's primary role?
- Expertise: What domains or technologies does it specialize in?
- Responsibilities: What are its 3-5 key responsibilities?
- Tools needed: Which tools does it require? (Read, Write, Bash, Grep, WebFetch, Task)
- Model tier: haiku (fast/utility), sonnet (balanced), opus (reasoning-heavy)
- 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