Creating Extensions

Build custom extensions

Creating Custom Extensions

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

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:

Use AIWG to complete this documented outcome: Use CLI scaffolding commands to generate extension stubs
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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 the agent-owned add-skill operation 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

Use AIWG to complete this documented outcome: Command Structure
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Arguments

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

Options

the fix option - Automatically fix issues where possible
the report option - Generate detailed security report
`the severity option <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

Use AIWG to complete this documented outcome: Examples
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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., "the fix option" }


### 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 patterns | Questions 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.

| Criterion | Strong | Weak |
|-----------|--------|------|
| **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.

| Field | Source | Required | Purpose |
|-------|--------|----------|---------|
| `name:` | Official | **Yes** | Skill name; also controls the generated command's slash-command path |
| `description:` | Official | **Yes (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:` | Official | Model 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:` | Official | Restrict which tools the skill may use |
| `platforms:` | AIWG-internal | Multi-provider deployment targets |
| `autoTrigger:` | AIWG-internal | AIWG-level auto-trigger annotation |
| `commandHint:` | AIWG-internal | Overrides 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

| Event | When | Can Block |
|-------|------|-----------|
| `pre-session` | Session start | No |
| `post-session` | Session end | No |
| `pre-command` | Before command runs | Yes |
| `post-command` | After command completes | No |
| `pre-agent` | Before agent invocation | Yes |
| `post-agent` | After agent completes | No |
| `pre-write` | Before file write | Yes |
| `post-write` | After file write | No |
| `pre-bash` | Before bash execution | Yes |
| `post-bash` | After bash completes | No |

---

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

Scope

Components Reviewed:
{{componentList}}

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

Findings

Critical Issues

High Priority

Medium Priority

Low Priority / Informational

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.

Use AIWG to complete this documented outcome: Use the soul authoring skills rather than writing SOUL.md by hand — they enforce the section structure and validate output. Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

### 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 the agent-owned soul-enable operation to wire SOUL.md into platform
context files. the agent-owned soul-disable operation reverses it without deleting the
source. the agent-owned soul-status operation 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 the agent-owned add-behavior operation to scaffold the directory layout — it creates
`BEHAVIOR.md` plus a `scripts/` subdirectory and registers the behavior
with the daemon.

Use AIWG to complete this documented outcome: Use the agent-owned add-behavior operation to scaffold the directory layout — it creates BEHAVIOR.md plus a scripts/ subdirectory and registers the behavior with the daemon. Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

### 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](extension-types.md#behavior-extensions).

### 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).

Use AIWG to complete this documented outcome: 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 Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

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 the agent-owned mc operation (Mission Control)
orchestration — make sure the daemon is running and the requested
agents have been deployed to that provider.

### Related Patterns

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:

Use AIWG to complete this documented outcome: Validate your extension before deployment Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

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

Use AIWG to complete this documented outcome: Command Testing Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

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

Use AIWG to complete this documented outcome: Using Published Addons Have it inspect the current state, explain the plan, ask before material changes, and report the result with verification evidence.

---

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

- **Discord**: [Join Server](https://discord.gg/BuAusFMxdA)
- **GitHub Issues**: [Report Issues](https://github.com/jmagly/aiwg/issues)
- **Documentation**: [https://aiwg.io/docs](https://aiwg.io/docs)

---

## See Also

- [Extension System Overview](overview.md)
- [Extension Types Reference](extension-types.md)
- @docs/cli/reference.md - CLI commands
- @src/extensions/types.ts - Type definitions