Building Skills

Building Process

Plan Your Skill

Define what your skill will do and what tools it needs

Create Tools

Implement tools as TypeScript classes

Define Skill

Add tools to a LuaSkill instance in index.ts

Test Locally

Test with lua chat (sandbox mode) and optionally lua test

Deploy

Push and deploy to production

Complete Example: Task Management Skill

Step 1: Plan

Goal: Build a skill to manage tasks Tools needed:

create_task - Add new tasks
list_tasks - View all tasks
complete_task - Mark tasks as done
search_tasks - Find tasks

Step 2: Create Tools

Create src/tools/TaskTools.ts:

import { LuaTool, Data } from "lua-cli";
import { z } from "zod";

export class CreateTaskTool implements LuaTool {
  name = "create_task";
  description = "Create a new task";
  
  inputSchema = z.object({
    title: z.string(),
    description: z.string().optional(),
    priority: z.enum(['low', 'medium', 'high']).default('medium')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.create('tasks', {
      ...input,
      status: 'pending',
      createdAt: new Date().toISOString()
    }, `${input.title} ${input.description || ''}`);
    
    return {
      taskId: task.id,
      message: `Task "${input.title}" created`
    };
  }
}

export class ListTasksTool implements LuaTool {
  name = "list_tasks";
  description = "List all tasks";
  inputSchema = z.object({});

  async execute(input: any) {
    const result = await Data.get('tasks', {}, 1, 50);
    
    return {
      tasks: result.data.map(entry => ({
        id: entry.id,
        ...entry.data
      })),
      count: result.pagination.totalCount
    };
  }
}

export class CompleteTaskTool implements LuaTool {
  name = "complete_task";
  description = "Mark a task as completed";
  
  inputSchema = z.object({
    taskId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const task = await Data.getEntry('tasks', input.taskId);
    
    await Data.update('tasks', input.taskId, {
      ...task.data,
      status: 'completed',
      completedAt: new Date().toISOString()
    });
    
    return {
      success: true,
      message: `Task completed!`
    };
  }
}

Step 3: Configure Agent with Skill

Update src/index.ts to use the LuaAgent pattern:

import { LuaAgent, LuaSkill } from "lua-cli";
import {
  CreateTaskTool,
  ListTasksTool,
  CompleteTaskTool
} from "./tools/TaskTools";

// Create skill
const taskSkill = new LuaSkill({
  name: "task-management-skill",
  description: "Manage tasks and to-do lists",
  context: `
    This skill helps users manage their tasks.
    
    - Use create_task when users want to add a new task
    - Use list_tasks to show all tasks
    - Use complete_task when users finish a task
    
    Always confirm task details before creating.
    When listing tasks, organize by priority.
  `,
  tools: [
    new CreateTaskTool(),
    new ListTasksTool(),
    new CompleteTaskTool()
  ]
});

// Configure agent
export const agent = new LuaAgent({
  name: "task-assistant",
  
  persona: `You are a helpful task management assistant.
  
Your role:
- Help users create and organize tasks
- Keep track of todos and deadlines
- Help users stay productive

Communication style:
- Friendly and encouraging
- Clear and concise
- Confirm before creating tasks`,

  
  skills: [taskSkill]
});

Use LuaAgent to configure your agent’s persona, welcome message, and skills together. This is now the recommended pattern.

Step 4: Test

# Test conversationally (primary)
lua chat

# Optional: Test individual tools
lua test

Select sandbox mode to test with your local skills.

Step 5: Deploy

lua push
lua deploy

Best Practices

Start Simple

Build one tool at a time:

Create basic version
Test thoroughly
Add more features
Test again

Use Descriptive Names

// ✅ Good
name = "create_task"
name = "search_products"
name = "send_email"

// ❌ Bad
name = "task1"
name = "do_stuff"
name = "tool"

Write Clear Descriptions

// ✅ Good
description = "Create a new task with title, description, and priority"

// ❌ Bad
description = "Creates tasks"

Validate Inputs

Use Zod for comprehensive validation:

inputSchema = z.object({
  email: z.string().email(),
  age: z.number().min(0).max(120),
  priority: z.enum(['low', 'medium', 'high'])
});

Handle Errors Gracefully

async execute(input: any) {
  try {
    const result = await api.call(input);
    return result;
  } catch (error) {
    throw new Error(
      `Failed to process request: ${error.message}`
    );
  }
}

Return Structured Data

// ✅ Good - Structured
return {
  success: true,
  taskId: task.id,
  message: "Task created"
};

// ❌ Bad - Unstructured
return "Task created with ID 123";

Common Patterns

CRUD Pattern

// Create
export class CreateItemTool {
  async execute(input) {
    return await Data.create('items', input);
  }
}

// Read
export class GetItemTool {
  async execute(input) {
    return await Data.getEntry('items', input.id);
  }
}

// Update
export class UpdateItemTool {
  async execute(input) {
    return await Data.update('items', input.id, input.data);
  }
}

// Delete
export class DeleteItemTool {
  async execute(input) {
    return await Data.delete('items', input.id);
  }
}

Search Pattern

export class SearchTool {
  async execute(input: { query: string }) {
    // Vector search
    const results = await Data.search(
      'items',
      input.query,
      10,
      0.7
    );
    
    return {
      items: results.map(entry => ({ id: entry.id, ...entry.data })),
      count: results.length
    };
  }
}

External API Pattern

export class ExternalApiTool {
  async execute(input: any) {
    // Get API key from environment
    const apiKey = env('EXTERNAL_API_KEY');
    
    if (!apiKey) {
      throw new Error('API key not configured');
    }
    
    // Call external API
    const response = await fetch(apiUrl, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    return await response.json();
  }
}

Next Steps

Multi-Skill Projects

Organize tools into multiple skills

Best Practices

Advanced tips and patterns

Tool Examples

See 30+ working examples

Build Your First Skill

Follow complete tutorial

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Building Skills

Building Process

Complete Example: Task Management Skill

Step 1: Plan

Step 2: Create Tools

Step 3: Configure Agent with Skill

Step 4: Test

Step 5: Deploy

Best Practices

Common Patterns

CRUD Pattern

Search Pattern

External API Pattern

Next Steps

Multi-Skill Projects

Best Practices

Tool Examples

Build Your First Skill

​Building Process

​Complete Example: Task Management Skill

​Step 1: Plan

​Step 2: Create Tools

​Step 3: Configure Agent with Skill

​Step 4: Test

​Step 5: Deploy

​Best Practices

​Common Patterns

​CRUD Pattern

​Search Pattern

​External API Pattern

​Next Steps

Multi-Skill Projects

Best Practices

Tool Examples

Build Your First Skill

Building Process

Complete Example: Task Management Skill

Step 1: Plan

Step 2: Create Tools

Step 3: Configure Agent with Skill

Step 4: Test

Step 5: Deploy

Best Practices

Common Patterns

CRUD Pattern

Search Pattern

External API Pattern

Next Steps