Skip to main content
AI/MLjmagly

devkit-create-agent

Create a new agent with AI-guided expertise definition following the Agent Design Bible

Stars
141
Source
jmagly/aiwg
Updated
2026-05-31
Slug
jmagly--aiwg--devkit-create-agent
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jmagly/aiwg/HEAD/agentic/code/addons/aiwg-dev/skills/devkit-create-agent/SKILL.md -o .claude/skills/devkit-create-agent.md

Drops the SKILL.md into .claude/skills/devkit-create-agent.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Create AIWG Agent

Create a new agent with AI assistance to define expertise, workflow, and capabilities.

Follows: Agent Design Bible - 10 Golden Rules for production-grade agents.

Research Foundation: REF-001 (Bandara et al.), REF-002 (Roig 2025) failure archetype prevention.

Usage

/devkit-create-agent <name> --to <target> [options]

Arguments

Argument Required Description
name Yes Agent name (kebab-case recommended)

Required Options

Option Description
--to Target addon or framework

Optional Options

Option Description
--template Agent template: simple (default), complex, orchestrator
--interactive Enable interactive mode with guided questions

Templates

Templates are in ~/.local/share/ai-writing-guide/templates/agent-scaffolding/.

simple (default)

Single-purpose, focused agent with minimal structure (Rule 1: Single Responsibility).

  • Best for: Utility agents, single-task specialists
  • Model: haiku (efficiency tier)
  • Tools: Read, Write (Rule 2: Minimal Tools)

complex

Full reasoning agent with all safeguards including failure archetype prevention.

  • Best for: Subject matter experts, reviewers, analysts
  • Model: sonnet/opus (based on complexity)
  • Tools: Read, Write, Grep (Rule 2: 0-3 tools)
  • Includes: Grounding, uncertainty handling, recovery protocol

orchestrator

Multi-agent coordination with workflow patterns and agent assignment tables.

  • Best for: Workflow coordinators, phase managers
  • Model: opus (Rule 8: reasoning tier for coordination)
  • Tools: Task only (Rule 2: single tool for delegation)

validator

Read-only validation agent that doesn't modify state.

  • Best for: Quality gates, compliance checks, code review
  • Model: haiku/sonnet
  • Tools: Read, Grep (read-only)

Interactive Mode

When --interactive is specified, I will ask:

  1. Role: What is this agent's primary role?
  2. Expertise: What domains does it specialize in?
  3. Responsibilities: What are its key responsibilities?
  4. Tools: What tools does it need access to?
  5. Workflow: How should it approach tasks?
  6. Output: What format should its output take?

Examples

# Simple agent
/devkit-create-agent code-reviewer --to aiwg-utils

# Complex domain expert
/devkit-create-agent security-auditor --to sdlc-complete --template complex

# Orchestrator agent
/devkit-create-agent deployment-coordinator --to sdlc-complete --template orchestrator --interactive

Execution

  1. Validate inputs: Check name and target
  2. Verify target exists: Ensure addon/framework is installed
  3. Select template: Use specified or default to simple
  4. Gather expertise: In interactive mode, ask about domain knowledge
  5. Generate agent file: Create with frontmatter and sections
  6. Update manifest: Add agent to manifest.json
  7. Report success: Show location and customization tips

Output Location

<target>/agents/<name>.md

Agent File Structure

---
name: agent-name
description: Agent description
model: claude-sonnet-4-6
tools: Read, Write, MultiEdit, Bash, WebFetch
---

# Agent Title

[Description]

## Expertise
[Domain knowledge]

## Responsibilities
[What the agent does]

## Workflow
[How it approaches tasks]

## Output Format
[Expected output structure]

CLI Equivalent

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

10 Golden Rules Validation

After creation, validate against the Agent Design Bible:

aiwg lint agents <target>/agents/<name>.md --verbose
Rule Check
1. Single Responsibility One clear purpose, no "and" overload
2. Minimal Tools 0-3 tools, justified
3. Explicit I/O Inputs and outputs defined
4. Grounding Verify before acting (Archetype 1)
5. Uncertainty Escalate ambiguity (Archetype 2)
6. Context Scope Filter distractors (Archetype 3)
7. Recovery Handle errors (Archetype 4)
8. Model Tier Match task complexity
9. Parallel Ready Concurrent execution safe
10. Observable Traceable output

Related Commands

  • /devkit-create-command - Create a slash command
  • /devkit-create-skill - Create an auto-triggered skill
  • /devkit-validate - Validate agent structure
  • aiwg lint agents - Validate against 10 Golden Rules

References

  • @$AIWG_ROOT/agentic/code/addons/aiwg-dev/README.md — aiwg-dev addon overview
  • @$AIWG_ROOT/docs/extensions/extension-types.md — Extension types including agent type
  • @$AIWG_ROOT/docs/cli-reference.md — CLI reference including add-agent command
  • @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/god-session.md — Single-responsibility rules for agents
  • @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/agent-deployment.md — Agent metadata structure and multi-provider deployment