> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Project Structure
> Understanding the template project organization
## Overview
The Lua CLI creates a clean, minimal project structure by default. You can optionally include examples with `--with-examples`.
```
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.**
```typescript theme={null}
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.
```yaml theme={null}
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:
```json theme={null}
{
"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):
```bash theme={null}
# 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):
```bash theme={null}
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
```
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
Learn how to build custom skills
Follow recommended patterns
Available platform APIs
See working code examples