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

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

Sync Options

Control drift detection during compile:

lua compile              # Default: check for drift, prompt if found
lua compile --no-sync    # Skip drift check entirely
lua compile --force-sync # Auto-update local from server if drift found

Flag	Description
`--no-sync`	Skip drift detection (useful for CI/CD)
`--force-sync`	Automatically sync from server without prompting

Learn More

See lua sync for details on drift detection

lua test

Test individual tools locally in a sandboxed environment.

lua test

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

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

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

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!

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

​What It Does

​Interactive Prompts

​What Gets Created

​Configuration File

​lua compile

​What It Does

​Output

​Example Output

​Features

​Sync Options

Learn More

​lua test

​How It Works

​Example Session

​Features

​Testing Complex Inputs

​lua push

​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

​What It Does

​Example

​Features

​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

What It Does

Interactive Prompts

What Gets Created

Configuration File

lua compile

What It Does

Output

Example Output

Features

Sync Options

lua test

How It Works

Example Session

Features

Testing Complex Inputs

lua push

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

What It Does

Example

Features

Complete Workflow

New Project Workflow

Development Workflow

Quick Fix Workflow

Troubleshooting

Best Practices

Next Steps