Project Structure

Overview

The Lua CLI creates a clean, minimal project structure by default. You can optionally include examples with --with-examples.

Minimal (Default)
With Examples
After You Build

your-project/
├── src/
│   └── index.ts           # Agent configuration (LuaAgent)
├── lua.skill.yaml         # Configuration (auto-managed)
├── package.json           # Dependencies
├── tsconfig.json          # TypeScript config
├── .env.example           # Environment template
└── README.md              # Quick start guide

your-project/
├── src/
│   └── index.ts           # Agent configuration
├── examples/              # Example code (reference only)
│   ├── skills/            # Example skills & tools
│   │   ├── tools/         # 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
└── README.md

your-project/
├── src/
│   ├── index.ts           # Agent configuration
│   ├── skills/            # Your skills
│   │   ├── tools/         # Your tools
│   │   └── my.skill.ts
│   ├── webhooks/          # Your webhooks (optional)
│   ├── jobs/              # Your jobs (optional)
│   └── services/          # Your utilities (optional)
├── dist/                  # Compiled output (auto-generated)
├── .lua/                  # CLI cache (auto-generated)
├── node_modules/          # Dependencies
├── lua.skill.yaml
├── package.json
├── tsconfig.json
└── .env                   # Your environment variables

Core Files

src/index.ts

Your agent’s main configuration file.

import { LuaAgent } from "lua-cli";

const agent = new LuaAgent({
    name: `my-agent`,
    persona: `You are a helpful assistant...`,
    
    skills: [],        // Add your skills here
    
    // Optional components:
    // webhooks: [],
    // jobs: [],
    // preProcessors: [],
    // postProcessors: [],
});

lua.skill.yaml

Auto-managed configuration file. Created during lua init, updated automatically by CLI commands.

agent:
  agentId: agent_abc123
  orgId: org_xyz789

skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_xyz  # Auto-created during compile

Do not manually edit this file! The lua.skill.yaml is managed by the CLI and stores state only (IDs and versions). All configuration belongs in your code:

Persona → LuaAgent in src/index.ts
Tool definitions → Your tool files
Skill configuration → LuaSkill in code
Environment variables → .env file or lua env command

The only exception: you may manually increment the version number before pushing a new release.

IDs like skillId, webhookId, and jobId are auto-generated during compilation. Never edit these manually.

package.json

Standard Node.js package configuration:

{
  "name": "lua-skill",
  "type": "module",
  "dependencies": {
    "lua-cli": "^3.1.0",
    "zod": "^3.24.1"
  }
}

Building Your Project

Recommended Structure

As your project grows, organize it like this:

src/
├── index.ts                    # Agent configuration
├── skills/
│   ├── tools/                  # Tool implementations
│   │   ├── WeatherTool.ts
│   │   ├── ProductTools.ts     # Multiple related tools
│   │   └── OrderTool.ts
│   ├── weather.skill.ts        # Weather skill
│   └── ecommerce.skill.ts      # E-commerce skill
├── webhooks/                   # (Optional) HTTP endpoints
│   └── PaymentWebhook.ts
├── jobs/                       # (Optional) Scheduled tasks
│   └── DailyReportJob.ts
└── services/                   # (Optional) Shared utilities
    └── ApiClient.ts

File Naming Conventions

Type	Pattern	Example
Tools	`Tool.ts` or `Tools.ts`	`WeatherTool.ts`, `ProductTools.ts`
Skills	`*.skill.ts`	`weather.skill.ts`
Webhooks	`*Webhook.ts`	`PaymentWebhook.ts`
Jobs	`*Job.ts`	`DailyReportJob.ts`
Preprocessors	`*.preprocessor.ts`	`filter.preprocessor.ts`
Postprocessors	`*.postprocessor.ts`	`format.postprocessor.ts`

Auto-Generated Directories

dist/

Compiled JavaScript output. Created by lua compile.

dist/
├── deployment.json       # Deployment metadata
├── index.js             # Compiled main file
└── tools/               # Compiled tool bundles

.lua/

CLI cache directory. Safe to delete - will be regenerated.

Environment Files

.env

Your local environment variables (create this file):

# External API Keys
STRIPE_API_KEY=sk_test_abc123
OPENAI_API_KEY=sk-...

# Configuration
API_BASE_URL=https://api.example.com

Add .env to .gitignore - never commit secrets!

.env.example

Template for environment variables (commit this):

STRIPE_API_KEY=your_stripe_key_here
OPENAI_API_KEY=your_openai_key_here

Git Configuration

✅ Commit These

.gitignore
.env.example
lua.skill.yaml
package.json
tsconfig.json
README.md
src/

❌ Don’t Commit These

.env
node_modules/
dist/
.lua/

Sample .gitignore

# Dependencies
node_modules/

# Build output
dist/
.lua/

# Environment
.env
.env.local
.env.*.local

# OS
.DS_Store

# IDE
.vscode/
.idea/

Project Size Patterns

Small (1-5 tools)
Medium (5-15 tools)
Large (15+ tools)

src/
├── index.ts
└── skills/
    ├── tools/
    │   └── MyTools.ts    # All tools in one file
    └── my.skill.ts

src/
├── index.ts
└── skills/
    ├── tools/
    │   ├── WeatherTool.ts
    │   ├── UserTools.ts
    │   └── ProductTools.ts
    ├── weather.skill.ts
    └── commerce.skill.ts

src/
├── index.ts
├── skills/
│   ├── weather/
│   │   ├── tools/
│   │   └── weather.skill.ts
│   ├── commerce/
│   │   ├── tools/
│   │   └── commerce.skill.ts
│   └── support/
│       ├── tools/
│       └── support.skill.ts
├── webhooks/
├── jobs/
└── services/

Next Steps

Building Skills

Learn how to build custom skills

Best Practices

Follow recommended patterns

API Reference

Available platform APIs

Examples

See working code examples

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Project Structure

Overview

Core Files

src/index.ts

lua.skill.yaml

package.json

Building Your Project

Recommended Structure

File Naming Conventions

Auto-Generated Directories

dist/

.lua/

Environment Files

.env

.env.example

Git Configuration

✅ Commit These

❌ Don’t Commit These

Sample .gitignore

Project Size Patterns

Next Steps

Building Skills

Best Practices

API Reference

Examples

​Overview

​Core Files

​src/index.ts

​lua.skill.yaml

​package.json

​Building Your Project

​Recommended Structure

​File Naming Conventions

​Auto-Generated Directories

​dist/

​.lua/

​Environment Files

​.env

​.env.example

​Git Configuration

​✅ Commit These

​❌ Don’t Commit These

​Sample .gitignore

​Project Size Patterns

​Next Steps

Building Skills

Best Practices

API Reference

Examples

Overview

Core Files

src/index.ts

lua.skill.yaml

package.json

Building Your Project

Recommended Structure

File Naming Conventions

Auto-Generated Directories

dist/

.lua/

Environment Files

.env

.env.example

Git Configuration

✅ Commit These

❌ Don’t Commit These

Sample .gitignore

Project Size Patterns

Next Steps