Creating Extensions

Build custom extensions

Creating Custom Extensions

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

References:

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

Quick Start

Scaffolding

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"

Manual Creation

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"]
  }
}

Creating Agents

Agents are specialized AI personas with defined roles and capabilities.

Agent Structure

---
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

Agent Metadata

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
}

Best Practices

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

Creating Commands (Advanced / Legacy)

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.

Command Structure

---
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

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


## Arguments

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

## Options

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

## What It Does

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`

## Examples

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


## Output

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

Critical Issues: 1. [email protected] - Prototype Pollution (CVE-2020-8203) Fix: npm install [email protected]

2. [email protected] - SSRF (CVE-2020-28168) Fix: npm install [email protected]

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

Command Metadata

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"
}

Command Templates

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

Creating Skills

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.

NL Trigger Strategy

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:

Include in `## Triggers`Omit from `## Triggers`
Domain abbreviations ("SAST", "RTM", "IOC")Primary phrases matching the description
Colloquial shorthand ("ship it", "we got paged")Rewordings of the skill name
Tool-specific names ("stryker", "volatility")Obvious synonyms ("scan" for a scanning skill)
Auto-trigger file patternsQuestions Claude can infer from description
Negation patterns ("what are we NOT doing")Generic phrases ("run this", "do that")

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

Description Quality Checklist

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

CriterionStrongWeak
Specific"Validate phase gate criteria with multi-agent review and generate pass/fail reports""Check project gates"
Action-oriented"Extract IOCs from investigation artifacts and produce STIX 2.1 output""Handle IOCs"
Domain-scoped"Continuous risk identification, assessment, tracking, and retirement throughout SDLC""Manage risks"
Includes key terms"STRIDE threat modeling, vulnerability scanning, and security control validation""Security stuff"
Differentiating"Detects AI-generated writing patterns and suggests authentic alternatives""Check writing quality"

SKILL.md Frontmatter Reference

`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.

FieldSourceRequiredPurpose
`name:`OfficialYesSkill name; also controls the generated command's slash-command path
`description:`OfficialYes (non-empty)Primary NL signal. Claude reads this at session start and autonomously invokes the skill when user intent matches. Codex rejects skills without it. A weak or empty description degrades discoverability and breaks deployments.
`effort:`OfficialModel effort override: `1` (low), `2` (medium), `3` (high)
`user-invocable:`Official`false` = background-only; not shown in `/` autocomplete
`disable-model-invocation:`Official`true` = explicit user-only; disables autonomous model invocation
`context:`Official`fork` (isolated) or `inherit` (shared context)
`allowed-tools:`OfficialRestrict which tools the skill may use
`platforms:`AIWG-internalMulti-provider deployment targets
`autoTrigger:`AIWG-internalAIWG-level auto-trigger annotation
`commandHint:`AIWG-internalOverrides the `argument-hint` in the generated command file

Skill Structure

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

Skill Metadata

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;
}

Creating Hooks

Hooks respond to lifecycle events.

Hook Structure

{
  "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
  }
}

Hook Events

EventWhenCan Block
`pre-session`Session startNo
`post-session`Session endNo
`pre-command`Before command runsYes
`post-command`After command completesNo
`pre-agent`Before agent invocationYes
`post-agent`After agent completesNo
`pre-write`Before file writeYes
`post-write`After file writeNo
`pre-bash`Before bash executionYes
`post-bash`After bash completesNo

Creating Templates

Templates are document scaffolds with variables.

Template Structure

---
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/

Creating Souls

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.

Authoring Workflow

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

Required Sections

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 vs Agent Scope

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.

Wiring Souls Into Context

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.

Creating Behaviors

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.

Authoring Workflow

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>

Choosing a Mode

  • `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.

Required Frontmatter

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.

Cross-Platform Notes

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.

Creating Teams

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.

Authoring Workflow

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.

Team Authoring Checklist

  • 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.

Native vs Emulated Execution

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.

Validation

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

Testing Extensions

Agent Testing

# 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?

Command Testing

# Test command execution
aiwg security-scan src/

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

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

Skill Testing

# 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

Publishing Extensions

Package Structure

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

Publishing to npm

# 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

Using Published Addons

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

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

Best Practices

General

  • 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

Agents

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

Commands

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

Skills

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

Templates

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

Examples

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

Support

See Also