LuaSkill

Overview

LuaSkill is the main class for defining a skill - a collection of related tools that your AI agent can use.

import { LuaSkill } from 'lua-cli';

const skill = new LuaSkill({
  name: "my-skill",
  description: "Brief description of the skill",
  context: "Detailed instructions for the AI",
  tools: [new MyTool1(), new MyTool2()]
});

Constructor

new LuaSkill(config)

Creates a new skill instance.

LuaSkillConfig

required

Skill configuration object

Configuration Parameters

string

default:"unnamed-skill"

Unique identifier for the skillFormat: lowercase, alphanumeric, hyphens onlyExamples: "weather-skill", "product-catalog-skill"

string

required

Brief description (1-2 sentences) of what the skill doesThis appears in skill listings and helps users understand the skill’s purpose.

string | { base?: string; voice?: string; text?: string }

required

Detailed instructions for the AI on when and how to use the tools.String form (recommended):

Critical for proper tool selection
Write it like instructions to a smart assistant

Object form (channel-aware): Only use when you need different instructions per channel.

base — Always rendered, on every channel
voice — Appended to base on voice channels, ignored on text
text — Appended to base on text channels (web, WhatsApp, SMS), ignored on voice

See Channel-aware Prompts for details.

LuaTool[]

Array of tool instances to include in the skillCan be empty initially and tools added later with addTool() or addTools().

function

async condition(): Promise<boolean>

Optional gate for the whole skill. Return true to expose it, false to hide it.When it returns false the skill disappears completely: its tools can’t be called and its name, its context, and its tool names are left out of the agent’s prompt. The agent doesn’t know the capability exists.See Conditional Skills.

Conditional Skills

Use condition when a whole capability should be invisible to some users — tiering, entitlements, per-customer features.

import { LuaSkill, User } from 'lua-cli';
import CheckPointsTool from './tools/CheckPointsTool';
import RedeemPointsTool from './tools/RedeemPointsTool';

const loyaltySkill = new LuaSkill({
  name: 'loyalty-rewards',
  description: 'Loyalty points balance and reward redemption',
  context: `
    This skill manages the loyalty programme.

    Tool Usage:
    - check_points: Use when the customer asks about their balance.
    - redeem_points: Use when the customer wants to spend points. Confirm the reward first.
  `,
  condition: async () => {
    const user = await User.get();
    return user.data?.loyaltyEnrolled === true;
  },
  tools: [new CheckPointsTool(), new RedeemPointsTool()],
});

A customer who isn’t enrolled talks to an agent that has never heard of a loyalty programme. There is no check_points tool to refuse, and no loyalty context to leak. How it behaves:

Evaluated on every message, for the current user. Results are not cached between turns, so the gate always reflects current state.
Runs like your tool code. Has access to all Platform APIs (User, Data, Lua, Products, etc.).
Absent condition means always on. Existing skills are unaffected.
Skill-level short-circuits tool-level. If the skill is hidden, its tools’ own condition functions never run.

If you author a skill as a LuaSkill subclass rather than a config object, declare condition as a class field or method — the semantics are identical.

Fail-closed behavior: If your condition function throws an error or times out (30s), the skill is hidden. Design for that — a flaky third-party call inside a condition will hide the capability from users who should have it. Prefer a flag you already store on the user record over a live external lookup on every message.

Skill condition vs tool condition

Both gates take the same shape. They differ in what the agent still knows about.

	Tool `condition`	Skill `condition`
Scope	One tool	Every tool in the skill
Tool callable when `false`	No	No
Tool name in the prompt	Removed	Removed
Skill name and context in the prompt	Still rendered	Removed
Agent can mention the capability	Yes — the skill’s context still describes it	No — it doesn’t know it exists
Reach for it when	The capability is known to the user but currently unavailable	The existence of the capability is itself sensitive

Gate individual tools with LuaTool.condition when the rest of the skill still applies — for example, hiding cancel_order while track_order stays available.

Methods

addTool()

Adds a single tool to the skill.

skill.addTool(tool: LuaTool): void

LuaTool

required

Tool instance to add

Example:

const skill = new LuaSkill({
  name: "my-skill",
  description: "My skill",
  context: "..."
});

skill.addTool(new GetWeatherTool());
skill.addTool(new CreateOrderTool());

Validation:

Tool name must be unique within the skill
Tool name must only contain: a-z, A-Z, 0-9, -, _
Throws error if validation fails

addTools()

Adds multiple tools to the skill at once.

skill.addTools(tools: LuaTool[]): void

LuaTool[]

required

Array of tool instances to add

Example:

skill.addTools([
  new GetWeatherTool(),
  new CreateOrderTool(),
  new SearchProductsTool()
]);

Validation:

All tools validated before adding
Atomic operation (all or nothing)
Throws error if any validation fails

Examples

Basic Skill

import { LuaSkill, LuaTool } from 'lua-cli';
import { z } from 'zod';

class HelloTool implements LuaTool {
  name = "say_hello";
  description = "Say hello to a user";
  inputSchema = z.object({
    name: z.string()
  });

  async execute(input: any) {
    return { message: `Hello, ${input.name}!` };
  }
}

const helloSkill = new LuaSkill({
  name: "hello-skill",
  description: "A simple greeting skill",
  context: "Use say_hello when users want to be greeted",
  tools: [new HelloTool()]
});

Weather Skill

import { LuaSkill } from 'lua-cli';
import GetWeatherTool from './tools/GetWeatherTool';
import GetForecastTool from './tools/GetForecastTool';

const weatherSkill = new LuaSkill({
  name: "weather-skill",
  description: "Provides weather information for any city worldwide",
  context: `
    This skill provides weather information.
    
    - Use get_weather for current conditions
    - Use get_forecast for 7-day predictions
    
    Always include the city name in responses.
    Mention temperature in user's preferred units.
  `,
  tools: [
    new GetWeatherTool(),
    new GetForecastTool()
  ]
});

E-commerce Skill

import { LuaSkill } from 'lua-cli';
import {
  SearchProductsTool,
  CreateProductTool,
  UpdateProductTool
} from './tools/ProductTools';

const ecommerceSkill = new LuaSkill({
  name: "ecommerce-skill",
  description: "Complete e-commerce product management",
  context: `
    This skill manages an e-commerce product catalog.
    
    Tool Usage:
    - search_products: When users describe what they're looking for
    - create_product: When adding new items (admin only)
    - update_product: When modifying prices, stock, or details
    
    Guidelines:
    - Always show prices with currency
    - Mention stock availability
    - Suggest related products when relevant
    - Confirm changes before updating
  `,
  tools: [
    new SearchProductsTool(),
    new CreateProductTool(),
    new UpdateProductTool()
  ]
});

Adding Tools Dynamically

const skill = new LuaSkill({
  name: "dynamic-skill",
  description: "Skill with dynamically added tools",
  context: "Tools will be added based on configuration"
});

// Add tools conditionally
if (config.enableWeather) {
  skill.addTool(new GetWeatherTool());
}

if (config.enableOrders) {
  skill.addTools([
    new CreateOrderTool(),
    new TrackOrderTool()
  ]);
}

Writing Good Context

The context field is critical for AI tool selection. Follow these guidelines:

Structure

context: `
  [What this skill does - 1 sentence]
  
  Tool Usage:
  - tool_1: [When to use] [What it returns]
  - tool_2: [When to use] [What it returns]
  
  Guidelines:
  - [Important rules]
  - [Edge cases]
  - [User experience tips]
`

Good Context Example

context: `
  This skill manages customer orders for a coffee shop.

  Tool Usage:
  - show_menu: Use when customers ask what's available. Returns drinks and food.
  - create_order: Use when taking an order. Confirm items and sizes first.
  - modify_order: Use to add/remove items. Ask which item to modify.
  - finalize_order: Use when confirmed. Returns total and estimated time.

  Guidelines:
  - Always ask about drink sizes (small/medium/large)
  - Mention daily special when showing menu
  - Confirm total before finalizing order
  - Ask about dietary restrictions for food
`

Poor Context Example

context: "A skill with tools for stuff"  // ❌ Too vague

Best Practices

Use Descriptive Names

// ✅ Good
name: "weather-skill"
name: "product-catalog-skill"
name: "customer-support-skill"

// ❌ Bad
name: "skill1"
name: "my_skill"
name: "test"

Write Clear Descriptions

// ✅ Good
description: "Provides real-time weather information and 7-day forecasts for cities worldwide"

// ❌ Bad
description: "Weather stuff"

Provide Detailed Context

The context field should include:

Overview of skill purpose
When to use each tool
Important guidelines
Edge cases to handle

Think of it as training documentation for the AI.

Group tools that work together:

// ✅ Good - Related tools together
const orderSkill = new LuaSkill({
  tools: [
    new CreateOrderTool(),
    new UpdateOrderTool(),
    new CancelOrderTool(),
    new TrackOrderTool()
  ]
});

// ❌ Bad - Unrelated tools mixed
const messySkill = new LuaSkill({
  tools: [
    new GetWeatherTool(),
    new CreateOrderTool(),
    new SendEmailTool()
  ]
});

Multi-Skill Projects

You can define multiple skills in one project:

// Product browsing
const catalogSkill = new LuaSkill({
  name: "catalog-skill",
  description: "Product browsing and search",
  tools: [new SearchProductsTool(), new GetProductTool()]
});

// Shopping cart
const cartSkill = new LuaSkill({
  name: "cart-skill",
  description: "Shopping cart management",
  tools: [new CreateBasketTool(), new AddItemTool()]
});

// Order processing
const orderSkill = new LuaSkill({
  name: "order-skill",
  description: "Order creation and tracking",
  tools: [new CreateOrderTool(), new TrackOrderTool()]
});

Each skill gets its own skillId in lua.skill.yaml and can be deployed independently.

Type Definitions

interface LuaSkillConfig {
  name?: string;
  description: string;
  context: string;
  tools?: LuaTool[];
  condition?: () => Promise<boolean>;
}

class LuaSkill {
  constructor(config: LuaSkillConfig);
  addTool(tool: LuaTool): void;
  addTools(tools: LuaTool[]): void;
}

Next Steps

LuaTool Interface

Learn how to implement tools

Build Your First Skill

Follow a complete tutorial

Template Guide

Explore the example project

Skills & Tools Concept

Understand the architecture

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Constructor

new LuaSkill(config)

Configuration Parameters

Conditional Skills

Skill condition vs tool condition

Methods

addTool()

addTools()

Examples

Basic Skill

Weather Skill

E-commerce Skill

Adding Tools Dynamically

Writing Good Context

Structure

Good Context Example

Poor Context Example

Best Practices

Multi-Skill Projects

Type Definitions

Next Steps

LuaTool Interface

Build Your First Skill

Template Guide

Skills & Tools Concept

​Overview

​Constructor

​new LuaSkill(config)

​Configuration Parameters

​Conditional Skills

​Skill condition vs tool condition

​Methods

​addTool()

​addTools()

​Examples

​Basic Skill

​Weather Skill

​E-commerce Skill

​Adding Tools Dynamically

​Writing Good Context

​Structure

​Good Context Example

​Poor Context Example

​Best Practices

​Multi-Skill Projects

​Type Definitions

​Next Steps

LuaTool Interface

Build Your First Skill

Template Guide

Skills & Tools Concept

Overview

Constructor

new LuaSkill(config)

Configuration Parameters

Conditional Skills

Skill condition vs tool condition

Methods

addTool()

addTools()

Examples

Basic Skill

Weather Skill

E-commerce Skill

Adding Tools Dynamically

Writing Good Context

Structure

Good Context Example

Poor Context Example

Best Practices

Multi-Skill Projects

Type Definitions

Next Steps