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
Next Steps
