Skill Management

Overview

Skill management commands help you build, test, and deploy your AI skills.

lua init

Create new skill project

lua compile

Compile TypeScript code

lua test

Test tools interactively

lua push

Upload version to server

lua deploy

Deploy to production

lua init

Initialize a new Lua skill project in the current directory.

mkdir my-skill && cd my-skill
lua init                    # Minimal project (recommended)
lua init --with-examples    # Include 30+ example tools

Options

Option	Description
`--with-examples`	Include example skills, tools, jobs, webhooks, and processors
`--agent-id <id>`	Use existing agent by ID (non-interactive)
`--agent-name <name>`	Name for new agent (requires —org-id or —org-name)
`--org-id <id>`	Use existing organization by ID
`--org-name <name>`	Create new organization with this name
`--force`	Skip confirmations / overwrite existing project
`--restore-sources`	Automatically restore project source files from backup (requires —agent-id)

Non-Interactive Mode

# Use existing agent
lua init --agent-id abc123

# Create agent in existing organization
lua init --agent-name "My Bot" --org-id org456

# Create agent + new organization
lua init --agent-name "My Bot" --org-name "Acme Corp"

# Override existing project
lua init --agent-id abc123 --force

# With example code
lua init --agent-id abc123 --with-examples

# Restore from backup
lua init --agent-id abc123 --restore-sources

What It Does

Choose Agent

Select existing agent or create new one

Configure Agent (if new)

Enter business name
Enter agent name
Select business type
Select brand personality
Enter brand traits
Configure features

Create Project

Copies template files
Creates lua.skill.yaml
Installs dependencies
Ready to customize!

Interactive Prompts

Minimal (Default)
With Examples
Existing Agent

$ lua init
? What would you like to do? Create new agent
? Enter business name: My Coffee Shop
? Enter agent name: CoffeeBot
? Select business type: Food & Beverage
? Select brand personality: Friendly
? Enter brand traits: Warm, welcoming, knowledgeable
🔄 Creating agent...
✅ Agent created successfully!
✅ Created lua.skill.yaml
✅ Copied template files
✅ Updated LuaAgent configuration
📦 Installing dependencies...
✅ Lua skill project initialized successfully!
💡 Tip: Use `lua init --with-examples` to include example code

$ lua init --with-examples
? What would you like to do? Create new agent
? Enter business name: My Coffee Shop
? Enter agent name: CoffeeBot
...
✅ Created lua.skill.yaml
✅ Copied template files
✅ Included example skills, tools, jobs, and webhooks
✅ Updated LuaAgent configuration
📦 Installing dependencies...
✅ Lua skill project initialized with examples!
💡 Check the examples/ folder for sample skills, tools, jobs, and webhooks

$ lua init
? What would you like to do? Select existing agent
? Select organization: My Organization
? Select agent: CoffeeBot
✅ Created lua.skill.yaml
✅ Copied template files
📦 Installing dependencies...
✅ Lua skill project initialized successfully!

What Gets Created

Minimal (Default)
With Examples

your-skill/
├── src/
│   └── index.ts              # Empty agent ready to customize
├── lua.skill.yaml            # Configuration (auto-managed)
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript config
├── .env.example              # Environment variables template
└── README.md                 # Quick start guide

A clean slate - build your agent from scratch!

your-skill/
├── src/
│   └── index.ts              # Agent configuration
├── examples/                 # Reference code
│   ├── skills/               # Example skills & tools
│   │   ├── tools/            # 30+ tool implementations
│   │   └── *.skill.ts        # Skill definitions
│   ├── webhooks/             # HTTP endpoint examples
│   ├── jobs/                 # Scheduled task examples
│   ├── preprocessors/        # Message filter examples
│   ├── postprocessors/       # Response formatter examples
│   └── services/             # Helper utilities
├── lua.skill.yaml
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Examples in a separate folder - copy what you need!

Configuration File

lua.skill.yaml is created with:

agent:
  agentId: agent_abc123
  orgId: org_xyz789

skills: []  # Auto-populated during compilation

The lua.skill.yaml file is auto-managed by the CLI. Do not manually edit it except for incrementing version numbers. All configuration belongs in your code (src/index.ts).

Persona is stored in your LuaAgent code (in src/index.ts), not in YAML. The YAML file is state-only and tracks IDs and versions.

lua compile

Compile TypeScript skill into deployable JavaScript bundles.

lua compile

What It Does

Analyze Code

Detects all tools from your src/index.ts file

Bundle Tools

Uses esbuild to create optimized JavaScript bundles

Extract Metadata

Extracts tool names, descriptions, and schemas

Create Deployment

Generates deployment artifacts in dist/ directory

Update Config

Creates/updates skills in lua.skill.yaml

Output

dist/
├── deployment.json          # Deployment metadata
├── index.js                 # Main skill bundle
└── tools/                   # Individual tool bundles
    ├── GetWeatherTool.js
    ├── UserDataTool.js
    └── ...

.lua/
├── deploy.json              # Legacy format
├── get_weather.js           # Uncompressed (debugging)
└── ...

Example Output

$ lua compile
🔨 Compiling Lua skill...
📦 Found 15 tools to bundle...
📦 Bundling GetWeatherTool...
📦 Bundling UserDataTool...
📦 Bundling ProductsTool...
... (more tools)
📦 Bundling main index...
✅ Skill compiled successfully - 15 tools bundled

Features

✅ Automatic Detection - Finds all tools in your code
✅ Fast Bundling - Uses esbuild for speed
✅ Type Safety - Validates TypeScript
✅ Dependency Management - Bundles all dependencies
✅ Skill Creation - Auto-creates skills in config
✅ Drift Detection - Checks for server/local differences

Compile Options

lua compile              # Default: compile without drift check
lua compile --sync       # Enable drift detection and prompt if found
lua compile --verbose    # Show detailed compilation output

Flag	Description
`--sync`	Enable drift detection during compile (prompts if drift found)
`--verbose`	Show detailed compilation output

Learn More

See lua sync for details on drift detection

lua test

Test individual tools locally in a sandboxed environment.

lua test

Options

Option	Description
`--name <name>`	Entity name to test (non-interactive)
`--input <json>`	JSON input string for testing

Non-Interactive Mode

# Test a skill/tool
lua test skill --name get_weather --input '{"city": "London"}'

# Test a webhook
lua test webhook --name payment-hook --input '{"query": {}, "headers": {}, "body": {"type": "payment"}}'

# Test a job
lua test job --name daily-report

# Test preprocessor
lua test preprocessor --name filter --input '{"message": "hello", "channel": "web"}'

# Test postprocessor
lua test postprocessor --name formatter --input '{"message": "hi", "response": "hello", "channel": "web"}'

How It Works

Compile

Compiles your skill first

List Tools

Shows all available tools

Select Tool

Choose which tool to test

Enter Inputs

Dynamic prompts based on tool’s schema

Execute

Runs tool in secure VM sandbox

View Results

Shows output or error messages

Example Session

$ lua test
🧪 Testing Lua skill...
📦 Compiling code first...
✅ Skill compiled successfully
📄 Loaded environment variables from .env file

? 🔧 Select a tool to test:
❯ get_weather - Get the weather for a given city
  create_product - Create a new product
  search_products - Search products
  get_user_data - Get user data
  
✅ Selected tool: get_weather

📝 Enter input values:
? city (required): London

🚀 Executing tool...
Input: {
  "city": "London"
}
✅ Tool execution successful!
Output: {
  "weather": "3",
  "city": "London",
  "temperature": 15.2,
  "description": "Windspeed 12.3 km/h"
}

Features

✅ Dynamic Prompts - Based on Zod schema
✅ Type Validation - Validates inputs automatically
✅ Environment Loading - Loads .env and lua.skill.yaml variables
✅ Secure Sandbox - Isolated VM execution
✅ Detailed Errors - Clear error messages

Testing Complex Inputs

# Nested objects
? shippingAddress.street (required): 123 Main St
? shippingAddress.city (required): New York
? shippingAddress.zip (required): 10001

# Arrays
? items[0].id (required): product_123
? items[0].quantity (required): 2
? Add another item? No

# Optional fields
? description (optional): [Press Enter to skip]

lua push

Push your compiled components to the Lua server.

lua push                 # Interactive selection
lua push skill           # Push a skill
lua push persona         # Push persona
lua push webhook         # Push a webhook
lua push job             # Push a job
lua push preprocessor    # Push a preprocessor
lua push postprocessor   # Push a postprocessor
lua push mcp             # Push an MCP server
lua push all --force     # Push all components

Options

Option	Description
`--name <name>`	Entity name to push (non-interactive)
`--set-version <ver>`	Version to set (e.g., 1.0.5)
`--force`	Skip all confirmation prompts
`--auto-deploy`	Automatically deploy to production after push

Non-Interactive Mode

# Push specific skill with version
lua push skill --name mySkill --set-version 1.0.5

# Push all components
lua push all --force

# Push and auto-deploy to production
lua push all --force --auto-deploy

# Push webhook with version
lua push webhook --name payment-hook --set-version 2.0.0

# Push job with version
lua push job --name daily-report --set-version 1.0.0

Push All: Use lua push all --force to push all components at once. Add --auto-deploy to also activate/deploy them.

Usage Modes

Interactive Mode
Direct Mode - Skill
Direct Mode - Persona

Default behavior - prompts for selection

$ lua push
? What would you like to push?
  › skill
    persona

Best for: When you’re not sure or want to see options

Skip prompt and push skill directly

$ lua push skill
# No prompt - goes straight to pushing skill

Best for: Quick iterations, automation, when you know what you want

Skip prompt and push persona directly

$ lua push persona
# No prompt - goes straight to pushing persona

Best for: Persona-only updates, faster workflow

What It Does (Skills)

Select Skill (if interactive)

Choose which skill to push (if multiple)

Enter Version

Enter new version number (auto-suggests next patch)

Current version: 1.0.0
? Enter new version to push: (1.0.1)

Update Configuration

Updates version in lua.skill.yaml

Authenticate

Validates your API key

Compile

Automatically compiles the skill

Upload

Uploads bundles to server

Optional Deploy

Choose to deploy immediately or later

? Would you like to deploy this version to production now? (y/N)

Example: Push Only (Interactive)

$ lua push
? What would you like to push?
  › skill
    persona

📦 Pushing skill: customer-service

Current version: 1.0.0
? Enter new version to push: (1.0.1) ⏎

📝 Updating version from 1.0.0 to 1.0.1
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 10 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.1 of "customer-service" pushed successfully

? Would you like to deploy this version to production now? No

[Version pushed, use 'lua deploy' to deploy later]

Example: Push Only (Direct Mode)

$ lua push skill
📦 Pushing skill: customer-service

Current version: 1.0.0
? Enter new version to push: (1.0.1) ⏎

📝 Updating version from 1.0.0 to 1.0.1
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 10 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.1 of "customer-service" pushed successfully

? Would you like to deploy this version to production now? No

[Version pushed, use 'lua deploy' to deploy later]

Example: Push and Deploy

$ lua push
📦 Pushing skill: order-management

Current version: 0.5.0
? Enter new version to push: 1.0.0

📝 Updating version from 0.5.0 to 1.0.0
✅ Authenticated
🔄 Compiling skill...
✅ Skill compiled successfully - 8 tools bundled
🔄 Pushing version to server...
✅ Version 1.0.0 of "order-management" pushed successfully

? Would you like to deploy this version to production now? Yes

⚠️  WARNING: You are about to deploy to PRODUCTION!
⚠️  This will affect ALL users immediately.

? Are you absolutely sure you want to deploy? Yes

🔄 Publishing version...
✅ Version 1.0.0 deployed successfully to production

Version Management

Auto-Increment
Custom Version
Semantic Versioning

The command auto-suggests the next patch version:

Current: 1.0.0  → Suggests: 1.0.1
Current: 1.5.9  → Suggests: 1.5.10
Current: 2.0.0  → Suggests: 2.0.1

Press Enter to accept or type your own version

You can enter any valid semver version:

Current: 0.5.0
? Enter: 1.0.0  # Major release

Current: 1.2.3
? Enter: 1.3.0  # Minor update

Current: 2.0.0
? Enter: 2.0.1-beta  # Pre-release

Follow semver conventions:

MAJOR (2.0.0): Breaking changes
MINOR (1.1.0): New features
PATCH (1.0.1): Bug fixes

# In lua.skill.yaml
skills:
  - name: my-skill
    version: 1.0.1  # Auto-updated by push

Version Conflict Avoidance: When using --force, the CLI automatically checks the server for the highest existing version and suggests the next available version. This prevents “Version already exists” errors during automated deployments.

Deploy Now or Later?

Deploy Later (Recommended)
Deploy Immediately

Push now, test, deploy when ready

$ lua push
? Deploy now? No  # Default

# Test in sandbox
$ lua chat → Sandbox mode

# Deploy when satisfied
$ lua deploy

Best for:

Major changes
Need more testing
Team coordination
Off-peak deployment

One-command deployment

$ lua push
? Deploy now? Yes
? Absolutely sure? Yes
✅ Deployed

Best for:

Critical hotfixes
Small bug fixes
Well-tested changes
Urgent updates

Important Notes

Version Management:

Always increments version (cannot overwrite)
Version is updated in lua.skill.yaml
All versions are preserved on server
Can deploy any previous version

Immediate Deployment:

Requires two confirmations for safety
Affects all users immediately
Have rollback plan ready
Monitor after deployment

Version Management

The version number is the only field in lua.skill.yaml you should manually edit:

skills:
  - name: my-skill
    version: 1.0.1  # Increment this before pushing

Then push:

lua push

Requirements

Must be in skill directory with lua.skill.yaml
Must have valid API key (lua auth configure)
Version must not already exist on server

lua deploy

Deploy a specific version to production (all users).

lua deploy

Options

Option	Description
`--skill-name <name>`	Skill to deploy (non-interactive)
`--skill-version <ver>`	Version to deploy, or ‘latest’
`--force`	Skip confirmation prompt

Non-Interactive Mode

# Deploy specific version
lua deploy --skill-name mySkill --skill-version 1.0.5 --force

# Deploy latest version
lua deploy --skill-name mySkill --skill-version latest --force

What It Does

Fetch Versions

Lists all pushed versions from server

Select Version

Choose which version to deploy

Confirm

Shows warning about production deployment

Deploy

Publishes selected version

Live!

Version is immediately available to all users

Example

$ lua deploy
✅ Authenticated
🔄 Fetching available versions...

? Select a version to deploy:
  1.0.2 - Created: Oct 3, 2025 by [email protected]
  1.0.1 - Created: Oct 2, 2025 by [email protected]
❯ 1.0.0 (CURRENT) - Created: Oct 1, 2025 by [email protected]

? ⚠️  Warning: This version will be deployed to all users. Do you want to proceed? Yes
🔄 Publishing version...
✅ Version 1.0.0 deployed successfully

Features

Shows all available versions
Indicates currently deployed version
Requires explicit confirmation
Immediate deployment (no rollback delay)

Deployment is immediate!All users will get the new version right away. Test thoroughly with lua chat first!

lua push backup

New in v3.5.0: Backup your project source files to cloud storage for disaster recovery and team collaboration.

Push your project source files to cloud storage for safekeeping. Uses content-addressed storage with automatic deduplication for efficient backups.

lua push backup                 # Backup project sources
lua push backup --force         # Force backup even if up-to-date
lua push backup --skip-compile  # Skip compilation (assume already compiled)

Options

Option	Description
`--force`	Force backup even if hash matches previous backup
`--skip-compile`	Skip compilation step (assumes dist/ already exists)

What Gets Backed Up

The backup includes all source files tracked in your compilation manifest:

Source Code: src/ directory (TypeScript files)
Configuration: lua.skill.yaml, tsconfig.json, package.json
Environment Template: .env.example (if exists)
Documentation: README.md (if exists)

NOT backed up: node_modules/, dist/, .env (secrets), .git/ (use Git for version control)

How It Works

Compile Project

Ensures manifest is fresh (runs lua compile if needed)

Calculate Project Hash

Creates a content hash of all source files for deduplication

Check Existing Backup

Verifies if this exact project state already exists on server

Upload New Files

Uploads only new/changed files (content-addressed storage)

Compares file hashes with server
Uploads missing blobs in batches
Deduplicates identical files across backups

Save Manifest

Saves the project structure and file references to MongoDB

Update Local Tracking

Updates lua.skill.yaml with backup hash for drift detection

Example Output

$ lua push backup
ℹ️  Project hash: 8f3d4a2b1c9e...
🔄 Checking server for existing backup...
🔄 Checking which files need upload...
ℹ️  Files: 42 total, 38 already stored, 4 to upload
ℹ️  Upload size: 12.3 KB (base64)
🔄 Uploading 4 new files to storage...
🔄 Uploaded 4/4 files...
🔄 Saving backup manifest...
✅ Backup pushed successfully!
   Files: 42
   New uploads: 4
   Deduplicated: 38
   Hash: 8f3d4a2b1c9e...

Restoring from Backup

To restore a backed-up project on a new machine:

# Initialize with restore flag
lua init --agent-id abc123 --restore-sources

This will:

Create a new project directory
Download all source files from cloud storage
Restore the exact project state from backup
Install dependencies

Interactive restore:

$ lua init --agent-id abc123
? Would you like to restore project sources from backup? Yes
🔄 Fetching backup manifest...
✅ Found backup with 42 files
🔄 Downloading source files...
🔄 Downloaded 42/42 files...
✅ Sources restored successfully!
💡 Run 'lua compile' to rebuild from restored sources

Use Cases

Disaster Recovery
Team Collaboration
Migration
CI/CD Safety Net

Recover from lost laptop or corrupted files:

# On new machine
lua init --agent-id abc123 --restore-sources
npm install
lua compile
lua test

All your source code is back!

Share project with team members:

# Team member A pushes backup
lua push backup

# Team member B clones it
lua init --agent-id abc123 --restore-sources

No Git setup required for quick sharing.

Move project between machines:

# Old machine
lua push backup

# New machine
lua init --agent-id abc123 --restore-sources

Fresh install with all your code intact.

Automatic backups before deployments:

# In CI pipeline
lua push backup --force
lua push all --force --auto-deploy

Always have a recovery point.

Content-Addressed Storage

Backups use content-addressed storage (like Git):

Each file is stored by its SHA-256 hash
Identical files are stored only once
Subsequent backups only upload changed files
Extremely efficient for large projects with small changes

Example: If you change one line in one file, only that file is re-uploaded. The other 99 files reference existing blobs.

Best Practices

Backup Before Major Changes

lua push backup  # Safety checkpoint
# Make risky changes
lua test
lua push skill

If something breaks, restore from backup.

Use Git for Version Control

Backup ≠ Version Control

Backup: Disaster recovery, single snapshot
Git: Full history, branching, collaboration

Use both:

git commit -m "Add feature"  # Version control
lua push backup              # Disaster recovery snapshot

Backup Before Deployment

lua push backup --force
lua push all --force --auto-deploy

Always have a recovery point before production changes.

Regular Backups in CI/CD

Add to your deployment pipeline:

- name: Backup sources
  run: lua push backup --force

- name: Deploy
  run: lua push all --force --auto-deploy

Complete Workflow

New Project Workflow

# 1. Authenticate
lua auth configure

# 2. Initialize
mkdir my-skill && cd my-skill
lua init

# 3. Test
lua test

# 4. Push
lua push

# 5. Deploy
lua deploy

Development Workflow

# Configure environment if needed
lua env sandbox        # Add new API keys locally
lua env production     # Update production env vars

# Make changes to src/tools/*.ts

# Test your agent
lua chat  # Choose sandbox mode

# Optional: Test specific tools
lua test  # For debugging individual tools

# When satisfied, push (direct mode - faster!)
lua push skill

# Update production persona if needed
lua persona production # Or: lua push persona

# Deploy to production
lua deploy

Quick Fix Workflow

# 1. Edit file
vim src/tools/MyTool.ts

# 2. Test
lua test

# 3. Push and deploy (direct mode)
lua push skill
lua deploy

Troubleshooting

No lua.skill.yaml found

Error: ❌ No lua.skill.yaml foundSolution: Run command from skill directory or run lua init first

Version already exists

Error: ❌ Version 1.0.0 already exists on the serverSolution: Increment version in lua.skill.yaml:

skills:
  - version: 1.0.1  # Increment this

Compilation failed

Error: ❌ No index.ts foundSolution: Create src/index.ts with skill definition:

import { LuaSkill } from "lua-cli";
const skill = new LuaSkill({...});

Tool validation error

Error: ❌ Tool name invalidSolution: Tool names can only contain: a-z, A-Z, 0-9, -, _

// ✅ Good
name = "get_weather"

// ❌ Bad
name = "get weather"  // No spaces

Missing dependencies

Error: ❌ Cannot find module 'lua-cli'Solution: Install dependencies:

npm install

Best Practices

Test Before Pushing

Always test locally first:

lua test     # Test individual tools
lua chat     # Test conversationally
lua push     # Then push

Use Semantic Versioning

PATCH (1.0.1): Bug fixes
MINOR (1.1.0): New features
MAJOR (2.0.0): Breaking changes

Test in Sandbox Before Deploy

lua push     # Upload version
lua chat     # Test in sandbox
# If good, then:
lua deploy   # Deploy to production

Keep Version History

Don’t delete old versions - they serve as rollback points

Next Steps

Development Mode

Learn about live development with auto-reload

Build Your First Skill

Follow a complete tutorial

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

​Overview

lua init

lua compile

lua test

lua push

lua deploy

​lua init

​Options

​Non-Interactive Mode

​What It Does

​Interactive Prompts

​What Gets Created

​Configuration File

​lua compile

​What It Does

​Output

​Example Output

​Features

​Compile Options

Learn More

​lua test

​Options

​Non-Interactive Mode

​How It Works

​Example Session

​Features

​Testing Complex Inputs

​lua push

​Options

​Non-Interactive Mode

​Usage Modes

​What It Does (Skills)

​Example: Push Only (Interactive)

​Example: Push Only (Direct Mode)

​Example: Push and Deploy

​Version Management

​Deploy Now or Later?

​Important Notes

​Version Management

​Requirements

​lua deploy

​Options

​Non-Interactive Mode

​What It Does

​Example

​Features

​lua push backup

​Options

​What Gets Backed Up

​How It Works

​Example Output

​Restoring from Backup

​Use Cases

​Content-Addressed Storage

​Best Practices

​Complete Workflow

​New Project Workflow

​Development Workflow

​Quick Fix Workflow

​Troubleshooting

​Best Practices

​Next Steps

Development Mode

Build Your First Skill

Overview

lua init

Options

Non-Interactive Mode

What It Does

Interactive Prompts

What Gets Created

Configuration File

lua compile

What It Does

Output

Example Output

Features

Compile Options

lua test

Options

Non-Interactive Mode

How It Works

Example Session

Features

Testing Complex Inputs

lua push

Options

Non-Interactive Mode

Usage Modes

What It Does (Skills)

Example: Push Only (Interactive)

Example: Push Only (Direct Mode)

Example: Push and Deploy

Version Management

Deploy Now or Later?

Important Notes

Version Management

Requirements

lua deploy

Options

Non-Interactive Mode

What It Does

Example

Features

lua push backup

Options

What Gets Backed Up

How It Works

Example Output

Restoring from Backup

Use Cases

Content-Addressed Storage

Best Practices

Complete Workflow

New Project Workflow

Development Workflow

Quick Fix Workflow

Troubleshooting

Best Practices

Next Steps