Learn how to create custom agents, commands, skills, and other extensions for AIWG.

References:

• @docs/extensions/overview.md - Extension system overview
• @docs/extensions/extension-types.md - Type reference
• @src/extensions/types.ts - Type definitions
• @agentic/code/frameworks/sdlc-complete/agents/README.md - Agent examples

Use CLI scaffolding commands to generate extension stubs:

# Create new agent
aiwg add-agent "Security Auditor"

# Create new command
aiwg add-command "security-scan"

# Create new skill
aiwg add-skill "security-awareness"

# Create new addon
aiwg scaffold-addon "security-tools"

# Create new framework
aiwg scaffold-framework "security-framework"

Create extension manifest manually:

{
  "id": "security-auditor",
  "type": "agent",
  "name": "Security Auditor",
  "description": "Reviews code for security vulnerabilities",
  "version": "1.0.0",
  "capabilities": ["security", "code-review", "vulnerability-detection"],
  "keywords": ["security", "audit", "vulnerabilities"],
  "category": "sdlc/security",
  "platforms": {
    "claude": "full",
    "generic": "full"
  },
  "deployment": {
    "pathTemplate": ".{platform}/agents/{id}.md"
  },
  "metadata": {
    "type": "agent",
    "role": "Security Review and Vulnerability Detection",
    "model": {
      "tier": "sonnet"
    },
    "tools": ["Read", "Grep", "Bash"]
  }
}

Agents are specialized AI personas with defined roles and capabilities.

---
name: Security Auditor
description: Reviews code for security vulnerabilities
version: 1.0.0
capabilities:
  - security
  - code-review
  - vulnerability-detection
keywords:
  - security
  - audit
  - vulnerabilities
category: sdlc/security
model: sonnet
tools:
  - Read
  - Grep
  - Bash
---

# Security Auditor

You are a Security Auditor specializing in vulnerability detection and security best practices.

## Role

Review code for security vulnerabilities including:
- Injection attacks (SQL, XSS, Command Injection)
- Authentication and authorization flaws
- Sensitive data exposure
- Security misconfigurations
- Known vulnerable dependencies

## Workflow

1. **Identify sensitive code paths**
   - Authentication mechanisms
   - Data validation points
   - External API calls
   - Database queries

2. **Review for common vulnerabilities**
   - Use OWASP Top 10 as checklist
   - Check for input validation
   - Verify output encoding
   - Review access controls

3. **Document findings**
   - Severity (Critical/High/Medium/Low)
   - Location (file:line)
   - Vulnerability type
   - Recommended fix

4. **Generate security report**
   - Executive summary
   - Detailed findings
   - Remediation plan
   - Risk assessment

## Tools

- **Read**: Examine source code
- **Grep**: Search for patterns (e.g., `eval(`, `exec(`)
- **Bash**: Run security scanners (npm audit, bandit, etc.)

## Example Usage

"Review authentication code in src/auth/ for security issues" "Scan for SQL injection vulnerabilities" "Generate security report for production deployment"

## References

- @.aiwg/security/threat-model.md
- @.aiwg/security/security-checklist.md
- @docs/architecture/security-architecture.md

interface AgentMetadata {
  type: 'agent';
  role: string;                     // Agent's primary role
  model: {
    tier: 'haiku' | 'sonnet' | 'opus';
    override?: string;              // Specific model ID
  };
  tools: string[];                  // Available tools
  template?: string;                // Complexity template
  maxTools?: number;                // Tool count limit
  canDelegate?: boolean;            // Can call other agents
  readOnly?: boolean;               // No Write/Bash allowed
  workflow?: string[];              // Step-by-step process
  expertise?: string[];             // Areas of expertise
  responsibilities?: string[];      // What agent does
}

DO:

• Define clear, specific roles
• List required tools explicitly
• Provide step-by-step workflows
• Include concrete examples
• Add relevant references
• Use appropriate model tier (haiku for simple, opus for complex)

DON'T:

• Make agents too generic
• Omit tool requirements
• Skip workflow documentation
• Forget platform compatibility

Prefer aiwg add-skill for new workflows. Skills are the primary extension type — AIWG generates the corresponding command file automatically during deployment. Direct command authoring is for advanced cases where you need to write command-format content that doesn't originate from a skill source.

Commands are CLI and slash commands with argument parsing.

---
name: Security Scan
description: Run security vulnerability scan
version: 1.0.0
capabilities:
  - security
  - scanning
  - vulnerability-detection
keywords:
  - security
  - scan
  - vulnerabilities
category: security
argumentHint: "[--fix] [path]"
allowedTools:
  - Read
  - Bash
  - Write
---

# Security Scan Command

Run comprehensive security vulnerability scan.

## Usage

```bash
aiwg security-scan                  # Scan current directory
aiwg security-scan src/             # Scan specific path
aiwg security-scan --fix            # Auto-fix issues
aiwg security-scan --report         # Generate report

• path - Directory to scan (optional, defaults to current directory)

• --fix - Automatically fix issues where possible
• --report - Generate detailed security report
• --severity <level> - Filter by severity (critical/high/medium/low)

1. Detects language/framework
2. Runs appropriate scanners:
   • npm audit for Node.js
   • pip-audit for Python
   • bundle audit for Ruby
3. Checks for:
   • Known vulnerable dependencies
   • Security misconfigurations
   • Code patterns (hardcoded secrets, etc.)
4. Generates report in .aiwg/security/scan-report.md

# Basic scan
aiwg security-scan

# Scan with auto-fix
aiwg security-scan --fix

# Critical issues only
aiwg security-scan --severity critical

# Generate detailed report
aiwg security-scan --report

Security Scan Results:
  ✓ Dependencies scanned: 156
  ⚠ Critical issues: 2
  ⚠ High issues: 5
  ℹ Medium issues: 12

Critical Issues:
  1. lodash@4.17.20 - Prototype Pollution (CVE-2020-8203)
     Fix: npm install lodash@4.17.21

  2. axios@0.21.0 - SSRF (CVE-2020-28168)
     Fix: npm install axios@0.21.4

Report saved to: .aiwg/security/scan-report.md

### Command Metadata

```typescript
interface CommandMetadata {
  type: 'command';
  template: 'utility' | 'transformation' | 'orchestration';
  arguments?: CommandArgument[];
  options?: CommandOption[];
  argumentHint?: string;            // For help display
  allowedTools?: string[];
  model?: string;
  executionSteps?: string[];
  successCriteria?: string[];
}

interface CommandArgument {
  name: string;
  description: string;
  required: boolean;
  type: 'string' | 'number' | 'boolean';
  default?: string | number | boolean;
  position?: number;
}

interface CommandOption {
  name: string;
  description: string;
  type: 'string' | 'boolean' | 'number' | 'array';
  default?: string | boolean | number;
  short?: string;                   // e.g., "-f"
  long?: string;                    // e.g., "--fix"
}

Utility - Simple operations:

• Single file operations
• Status checks
• Information display
• Quick transformations

Transformation - Data processing:

• File format conversion
• Code generation
• Report generation
• Data validation

Orchestration - Complex workflows:

• Multi-step processes
• Agent coordination
• Framework deployment
• Migration operations

Skills are natural language workflows. Claude Code uses the description: field for native NL matching — it reads each skill's description at session start and autonomously decides when a skill is relevant.

The description: field is the primary NL signal. Write it well — Claude matches user intent against it automatically. Anything a user says that resembles the description will match without explicit trigger lists.

The ## Triggers body section is for alternate expressions only — phrases Claude would not naturally associate with the skill description:

Do NOT add a triggers: key to frontmatter. Triggers are expressed through:

• description: — primary NL signal (frontmatter)
• ## Triggers section in body — supplementary alt expressions only

A strong description enables Claude to match user intent without explicit trigger phrases.

name: and description: are REQUIRED in every SKILL.md. Codex rejects any skill whose frontmatter is missing a non-empty description: field, and Claude Code cannot auto-invoke skills without it. Tooling (scaffolder, generator, deployers) enforces this at runtime — never skip it.

---
name: Security Awareness
description: Detects security-sensitive context and suggests review when editing authentication, authorization, or data-handling code
version: 1.0.0
capabilities:
  - security
  - context-awareness
  - automated-review
keywords:
  - security
  - awareness
  - context
autoTrigger: true
autoTriggerConditions:
  - "modifying-auth-code"
  - "handling-sensitive-data"
tools:
  - Read
  - Grep
---

# Security Awareness Skill

Automatically detects security-sensitive context and provides guidance.

## Triggers

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

- "OWASP check" → OWASP Top 10 validation
- "is the code safe" → colloquial security check
- "pentest prep" → pre-penetration-test readiness
- Auto-triggered when editing `src/auth/**`, `src/security/**`, or files containing password/token handling

## What It Does

1. **Detect sensitive context**
   - Authentication/authorization code
   - Data validation and sanitization
   - Cryptographic operations
   - External integrations

2. **Check for common issues**
   - Missing input validation
   - Improper error handling
   - Insecure defaults
   - Missing access controls

3. **Provide guidance**
   - Security best practices
   - OWASP recommendations
   - Framework-specific guidance
   - Link to security docs

4. **Suggest review if needed**
   - Flag high-risk changes
   - Recommend security agent review
   - Point to threat model

## References

- @.aiwg/security/threat-model.md
- @.aiwg/security/security-checklist.md
- @docs/architecture/security-architecture.md

## Example

**User edits:** `src/auth/login.ts`

**Skill activates:**

Security-sensitive code detected

You're modifying authentication logic. Consider:

• Input validation on username/password
• Rate limiting to prevent brute force
• Secure password hashing (bcrypt, scrypt)
• Session token security (httpOnly, secure flags)
• Audit logging for failed attempts

Recommend security review before merging. Run: /security-auditor "Review auth changes"

interface SkillMetadata {
  type: 'skill';
  autoTrigger?: boolean;            // Auto-activate
  autoTriggerConditions?: string[]; // When to auto-activate
  tools?: string[];
  references?: SkillReference[];
  inputRequirements?: string[];
  outputFormat?: string;
}

interface SkillReference {
  filename: string;
  description: string;
  path: string;
}

Hooks respond to lifecycle events.

{
  "id": "security-pre-commit",
  "type": "hook",
  "name": "Security Pre-Commit Hook",
  "description": "Runs security checks before git commit",
  "version": "1.0.0",
  "capabilities": ["security", "git-hooks", "validation"],
  "keywords": ["security", "pre-commit", "validation"],
  "category": "security/hooks",
  "platforms": {
    "claude": "full",
    "generic": "full"
  },
  "deployment": {
    "pathTemplate": ".{platform}/hooks/{id}.md"
  },
  "metadata": {
    "type": "hook",
    "event": "pre-write",
    "priority": 10,
    "canBlock": true
  }
}

Templates are document scaffolds with variables.

---
name: Security Review Template
description: Template for security review documentation
version: 1.0.0
capabilities:
  - documentation
  - security
  - templates
keywords:
  - template
  - security
  - review
category: security/templates
format: markdown
variables:
  - name: reviewDate
    description: Date of security review
    type: string
    required: true
  - name: reviewer
    description: Name of security reviewer
    type: string
    required: true
  - name: severity
    description: Overall severity rating
    type: string
    required: true
    default: "Medium"
---

# Security Review: {{project}}

**Review Date:** {{reviewDate}}
**Reviewer:** {{reviewer}}
**Overall Severity:** {{severity}}

## Executive Summary

<!-- Brief overview of security posture -->

## Scope

- **Components Reviewed:**
  - {{componentList}}

- **Review Type:**
  - [ ] Code Review
  - [ ] Architecture Review
  - [ ] Configuration Review
  - [ ] Dependency Review

## Findings

### Critical Issues

<!-- Issues requiring immediate attention -->

### High Priority

<!-- Important issues to address soon -->

### Medium Priority

<!-- Issues to address in next sprint -->

### Low Priority / Informational

<!-- Nice-to-have improvements -->

## Recommendations

1. **Immediate Actions:**
   -

2. **Short-term (1-2 sprints):**
   -

3. **Long-term:**
   -

## Risk Assessment

**Current Risk Level:** {{riskLevel}}

**Residual Risk (after fixes):** {{residualRisk}}

## References

- @.aiwg/security/threat-model.md
- @.aiwg/architecture/security-architecture.md
- OWASP Top 10: https://owasp.org/www-project-top-ten/

Souls declare agent identity — worldview, opinions, vocabulary, and boundaries. Author souls when you need an agent or a whole project to hold a consistent character across sessions.

Use the soul authoring skills rather than writing SOUL.md by hand — they enforce the section structure and validate output.

# Generate from source material or interactive prompts
aiwg soul-create --interactive

# Improve an existing SOUL.md
aiwg soul-enhance .claude/SOUL.md

# Validate before committing
aiwg soul-validate .claude/SOUL.md

# Convert between soul and voice profile
aiwg soul-to-voice .claude/SOUL.md
aiwg voice-to-soul agentic/code/addons/voice-framework/voices/templates/technical-authority.md

Author the SOUL.md body with these sections:

• who-i-am — Core identity statement
• worldview — Perspective and philosophy
• opinions — Held positions and stances
• vocabulary — Preferred and avoided language
• boundaries — What this agent will and will not do

Project-scoped souls live at the platform context root (.claude/SOUL.md, .cursor/SOUL.md). Agent-scoped souls live next to the agent file with a .soul.md suffix (.claude/agents/test-engineer.soul.md). Set scope and (for agent scope) targetAgent in the manifest.

After authoring, run aiwg soul-enable to wire SOUL.md into platform context files. aiwg soul-disable reverses it without deleting the source. aiwg soul-status shows enforcement state across providers.

Behaviors are reactive capabilities that subscribe to system events and optionally execute shell scripts. Reach for a behavior when the capability needs to be always-on and event-driven, not just NL-invoked.

Use aiwg add-behavior to scaffold the directory layout — it creates BEHAVIOR.md plus a scripts/ subdirectory and registers the behavior with the daemon.

# Scaffold a new behavior (defaults to script mode)
aiwg add-behavior security-sentinel

# Scaffold an agent-mode behavior (no scripts; AI body)
aiwg add-behavior concierge --mode agent

# Deploy to a specific provider
aiwg add-behavior security-sentinel --provider openclaw

# Lifecycle
aiwg behavior list
aiwg behavior run <name>
aiwg behavior stop <name>

• mode: script (default) — Shell scripts execute on hook events. Use for build monitoring, scheduled audits, deterministic checks.
• mode: agent — The BEHAVIOR.md body instructs the AI directly, no scripts. Use for routing, interaction-layer behaviors (Concierge), or anything where AI judgment is central.

Every BEHAVIOR.md needs name, version, description, platforms, and at least one of triggers (NLP), hooks (events), or scripts. The full frontmatter reference is in Extension Types — Behavior.

OpenClaw is the reference implementation with native hook support. Other providers emulate hooks via the AIWG daemon — install and run the daemon for full behavior coverage. On platforms with no hook support, behaviors degrade to skills (NLP triggers only) automatically.

Teams compose 2–8 agents into a coordinated workflow. Author a team when a recurring multi-agent task benefits from explicit role assignment, dispatch ordering, and handoff gates.

Teams are JSON files validated against a schema. Place framework teams in agentic/code/frameworks/{framework}/teams/{slug}.json; place project-local teams in .aiwg/teams/{slug}.json (project-local takes precedence over framework teams with the same slug).

# List installed teams
aiwg team list

# Inspect a team
aiwg team info api-development

# Run a team
aiwg team run api-development --task "Design and ship the payments API"

Validate against the schema at agentic/code/frameworks/sdlc-complete/teams/schema.json before committing.

• 2–8 agents — Smaller teams are clearer; larger teams hit context budget and coordination limits.
• One lead — Other roles are contributor, reviewer, advisor.
• Pick a dispatch mode — sequential (default) for handoff chains, parallel for independent reviews, consensus for joint decisions.
• Declare handoffs explicitly — Each handoff names the source agent, target agent, artifact passed, and quality gate.
• Set max_context_agents — Default is 4; lower it (2–3) for context-constrained sessions.

On Claude Code, teams dispatch agents natively via the Task tool. On all other providers, AIWG falls back to aiwg mc (Mission Control) orchestration — make sure the daemon is running and the requested agents have been deployed to that provider.

Teams complement SkillSmith (skills) and AgentSmith (agents) — author the constituent agents first, then compose them into a team. The parallel-dispatch skill is the shared primitive both team execution modes use under the hood.

Validate your extension before deployment:

aiwg validate-metadata path/to/extension.json

Checks:

• All required fields present
• ID follows kebab-case convention
• Version format valid (semver or CalVer)
• Capabilities and keywords provided
• Platform compatibility declared
• Metadata type matches extension type

# Test agent manually
/security-auditor "Review src/auth/login.ts"

# Verify workflow
# 1. Does agent follow defined workflow?
# 2. Does agent use only declared tools?
# 3. Does agent produce expected output format?

# Test command execution
aiwg security-scan src/

# Verify argument parsing
aiwg security-scan --fix --severity critical

# Check error handling
aiwg security-scan /nonexistent/path

# Test manual trigger
"Security review needed for this code"

# Test auto-trigger
# 1. Edit file matching conditions
# 2. Verify skill activates
# 3. Confirm guidance appears

my-security-addon/
├── manifest.json           # Addon manifest
├── README.md               # Documentation
├── LICENSE                 # License file
├── agents/
│   ├── security-auditor.md
│   └── manifest.json
├── commands/
│   ├── security-scan.md
│   └── manifest.json
├── skills/
│   ├── security-awareness/
│   │   ├── SKILL.md
│   │   └── references/
│   └── manifest.json
└── templates/
    ├── security-review.md
    └── manifest.json

# Package addon
cd my-security-addon
npm init

# Add to package.json
{
  "name": "@myorg/aiwg-security",
  "version": "1.0.0",
  "keywords": ["aiwg", "security", "addon"],
  "aiwg": {
    "type": "addon",
    "entry": "./manifest.json"
  }
}

# Publish
npm publish

# Install from npm
npm install -g @myorg/aiwg-security

# Deploy to project
aiwg use @myorg/aiwg-security

• Clear naming: Use descriptive, unique IDs
• Accurate metadata: Capabilities and keywords match functionality
• Platform testing: Test on all declared platforms
• Documentation: Include usage examples and references
• Versioning: Follow semantic versioning

• Focused roles: One agent, one responsibility
• Tool minimalism: Use minimum necessary tools
• Workflow clarity: Step-by-step processes
• Example usage: Show common invocations

• Argument clarity: Clear argument descriptions
• Error handling: Graceful failure messages
• Progress feedback: Show what's happening
• Dry-run support: Allow preview without changes

• Trigger specificity: Precise trigger phrases
• Context awareness: Activate in right situations
• Helpful guidance: Actionable recommendations
• Non-intrusive: Don't interrupt flow unnecessarily

• Variable clarity: Clear variable descriptions
• Sensible defaults: Provide defaults where appropriate
• Structure: Logical section organization
• Examples: Show filled-in template

See:

• @agentic/code/frameworks/sdlc-complete/agents/ - Agent examples
• @agentic/code/frameworks/sdlc-complete/commands/ - Command examples
• @agentic/code/frameworks/sdlc-complete/skills/ - Skill examples
• @agentic/code/frameworks/sdlc-complete/templates/ - Template examples

• Discord: Join Server
• GitHub Issues: Report Issues
• Documentation: https://aiwg.io/docs

• Extension System Overview
• Extension Types Reference
• @docs/cli/reference.md - CLI commands
• @src/extensions/types.ts - Type definitions