@webbywisp/create-ai-agent

Scaffold production-ready AI agent workspaces in seconds.

npx @webbywisp/create-ai-agent my-workspace

The fastest way to bootstrap a structured AI agent workspace — SOUL.md, AGENTS.md, memory system, heartbeat config, ops guide, and more. Works with OpenClaw, Claude Code, Cursor, or as a generic agent workspace.

Quick Start

# Interactive wizard (recommended)
npx @webbywisp/create-ai-agent my-workspace

# Non-interactive with defaults
npx @webbywisp/create-ai-agent my-workspace --yes

# Dry run — preview without writing
npx @webbywisp/create-ai-agent my-workspace --dry-run

# Specific template + platform
npx @webbywisp/create-ai-agent my-workspace --template solo --platform openclaw

# MCP agent workspace
npx @webbywisp/create-ai-agent my-mcp-agent --template mcp-agent

Commands

create-ai-agent [directory]          Scaffold a new workspace (default)
create-ai-agent init [directory]     Scaffold a new workspace
create-ai-agent add <file>           Add a file to an existing workspace
create-ai-agent validate             Check workspace for missing files
create-ai-agent list                 Show available templates + platforms
create-ai-agent list-templates       Show available templates + platforms

Options

-t, --template <name>    Template: solo | team-lead | sub-agent | mcp-agent | minimal
-p, --platform <name>    Platform: openclaw | claude-code | cursor | custom
--no-git                 Skip git initialization
--no-interactive         Use defaults, skip prompts (CI mode)
-y, --yes                Accept all defaults
--dry-run                Preview without writing files
--force                  Overwrite existing files

Templates

| Template | Description | Files | |----------|-------------|-------| | solo | Single agent, all responsibilities | AGENTS.md, SOUL.md, USER.md, OPS.md, TOOLS.md, HEARTBEAT.md, MEMORY.md, memory/ | | team-lead | Orchestrates sub-agents | All solo files + agent tracking templates | | sub-agent | Specialized worker, minimal footprint | AGENTS.md, SOUL.md, CONTEXT.md | | mcp-agent | Agent that integrates with MCP servers | AGENTS.md, SOUL.md, USER.md, OPS.md, TOOLS.md, MCP-SERVERS.md, MEMORY.md, memory/ | | minimal | Bare bones | AGENTS.md, SOUL.md |

Platforms

| Platform | Description | Core file | |----------|-------------|-----------| | openclaw | Full OpenClaw workspace | AGENTS.md | | claude-code | Claude Code workspace | CLAUDE.md | | cursor | Cursor rules + context | .cursorrules | | custom | Generic, no platform refs | AGENTS.md |

Generated Structure (solo/openclaw)

my-workspace/
├── AGENTS.md           # Core instructions — how the agent operates
├── SOUL.md             # Persona — tone, values, style
├── IDENTITY.md         # Name, role, emoji (compact)
├── USER.md             # Info about the human being served
├── OPS.md              # Operational responsibilities and workflows
├── TOOLS.md            # Environment-specific notes (SSH, cameras, etc.)
├── HEARTBEAT.md        # Periodic check-in tasks and schedule
├── MEMORY.md           # Long-term curated memory (starts empty)
├── memory/
│   ├── YYYY-MM-DD.md   # Today's daily log
│   ├── projects/
│   │   └── _index.md   # Project tracking
│   └── agents/
│       └── _index.md   # Sub-agent tracking
└── .gitignore

MCP Agent Template

The mcp-agent template is built for agents that integrate with MCP (Model Context Protocol) servers. It generates:

• MCP-SERVERS.md — registry of all your MCP servers with connection details, tools, and resources
• AGENTS.md — MCP-aware agent instructions (knows how to scaffold, register, and use MCP servers)
• Full memory system + OPS.md

Working with MCP servers

To scaffold a new MCP server from within your agent workspace:

npx @webbywisp/create-mcp-server my-server

@webbywisp/create-mcp-server — the companion CLI for scaffolding MCP servers with tool/resource/prompt templates. Three templates: tool-server, resource-server, prompt-server. Supports add tool, add resource, and add prompt subcommands.

After scaffolding, register the server in MCP-SERVERS.md and your agent knows how to use it.

The add command

Add individual files to an existing workspace:

create-ai-agent add soul       # Add/regenerate SOUL.md
create-ai-agent add heartbeat  # Add HEARTBEAT.md
create-ai-agent add ops        # Add OPS.md
create-ai-agent add memory     # Initialize memory/ directory
create-ai-agent add gitignore  # Add .gitignore
create-ai-agent add tools      # Add TOOLS.md
create-ai-agent add user       # Add USER.md
create-ai-agent add identity   # Add IDENTITY.md

The validate command

$ create-ai-agent validate

🔍 Validating workspace...

  ✅ AGENTS.md
  ✅ SOUL.md
  ✅ USER.md
  ⚠️  OPS.md — missing (run: create-ai-agent add ops)
  ❌ TOOLS.md — missing (run: create-ai-agent add tools)

1 error, 1 warning

Interactive Flow

$ npx @webbywisp/create-ai-agent my-agent

🔨 Agent Forge — scaffolding your AI workspace

? What is your agent's name? Sage
? Describe your agent's role in one sentence: Chief operator of the AI org
? Choose a template:
  ❯ solo — single agent, all responsibilities
    team-lead — orchestrates sub-agents
    sub-agent — specialized worker
    mcp-agent — integrates with MCP servers
    minimal — bare bones

? Target platform:
  ❯ openclaw — full OpenClaw workspace
    claude-code — CLAUDE.md focused
    cursor — .cursorrules + context
    custom — generic

? Name of the human this agent serves: Wisp
? Agent personality / vibe: Sharp, efficient, no fluff
? Initialize a git repository? Yes

✅ Workspace scaffolded at ./my-agent/
   16 files created

Why? The Problem We're Solving

Running AI agents in production requires structural thinking. You need:

• Consistent personality (SOUL.md) — so your agent acts predictably
• Clear responsibilities (AGENTS.md, OPS.md) — so tasks don't get dropped or duplicated
• Long-term memory (MEMORY.md + daily logs) — so context survives session restarts
• Operational knowledge (TOOLS.md, HEARTBEAT.md) — environment-specific config and periodic tasks
• User context (USER.md) — who you're serving and what they value

Without scaffolding, you end up with:

• Inconsistent behavior — agent personality drifts across sessions
• Lost context — important decisions fade between restarts
• Fragmented operations — tasks slip through the cracks, configs are scattered
• Difficult onboarding — new team members don't understand the agent's structure

create-ai-agent bootstraps the full stack in seconds. Pick your template (solo, team-lead, sub-agent, mcp-agent, or minimal), choose your platform (OpenClaw, Claude Code, Cursor, or generic), and you get a production-ready foundation.

Think of it as scaffolding for AI organizations — not boilerplate, but structural patterns that compound over time.

Companion Tools

• @webbywisp/create-mcp-server — scaffold MCP servers with type-safe tools, resources, and prompts: npx @webbywisp/create-mcp-server my-server
• AI Agent Workspace Kit — a complete, pre-built agent workspace with example files, guides, and patterns: webbywisp.gumroad.com ($19)

Setup for CI/CD Publishing

To publish to npm automatically when you push a version tag:

1. Create the NPM token:

   • Visit npmjs.com/settings/~/tokens
   • Create a new token with Automation scope

2. Store it in GitHub:

   • Go to your repo → Settings → Secrets and variables → Actions
   • Name: NPM_TOKEN

3. Trigger a publish:

   git tag v0.3.0
   git push origin v0.3.0

License

MIT