Aiwg add-agent

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

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/add-agent" ~/.claude/skills/jmagly-aiwg-add-agent && rm -rf "$T"

manifest: .agents/skills/add-agent/SKILL.md

source content

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 <role>" → 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>

--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: <haiku|sonnet|opus>
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