# LuaSkill

The `LuaSkill` class groups related tools together and provides context for when the agent should use them.

## Import

```typescript
import { LuaSkill } from 'lua-cli';
```

## Overview

Skills organize tools by functionality and help the AI understand:
- Which tools work together
- When to use certain tools
- What domain/category the tools belong to

## Constructor

```typescript
class LuaSkill {
  constructor(config: LuaSkillConfig);
}

interface LuaSkillConfig {
  /** Skill name (unique identifier) */
  name?: string;
  
  /** Short description (1-2 sentences) */
  description: string;
  
  /** Detailed context for when to use these tools */
  context: string;
  
  /** Array of tools to include */
  tools?: LuaTool[];
}
```

## Properties

### `name` (optional)
- **Type:** `string`
- **Default:** `'unnamed-skill'`
- **Description:** Identifier for the skill
- **Example:** `'weather-skill'`, `'product-management'`

### `description` (required)
- **Type:** `string`
- **Description:** Brief explanation of what the skill does
- **Best Practice:** 1-2 sentences, clear and concise

### `context` (required)
- **Type:** `string`
- **Description:** Detailed guidance for the AI on when/how to use these tools
- **Best Practice:** Include use cases, examples, and boundaries

### `tools` (optional)
- **Type:** `LuaTool[]`
- **Default:** `[]`
- **Description:** Array of tool instances

## Basic Example

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

export const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather information and forecasts',
  context: `Use these tools to provide weather information. 
  - get_weather: Current conditions for a city
  - get_forecast: 5-day forecast
  
  Always include temperature, condition, and location in responses.`,
  
  tools: [
    new GetWeatherTool(),
    new GetForecastTool()
  ]
});
```

## Adding Tools

### During Construction

```typescript
const skill = new LuaSkill({
  name: 'my-skill',
  description: 'My skill description',
  context: 'Use these tools for...',
  tools: [tool1, tool2, tool3]
});
```

### After Construction

```typescript
const skill = new LuaSkill({
  name: 'my-skill',
  description: 'My skill',
  context: 'Context...'
});

// Add tools later
skill.addTool(tool1);
skill.addTool(tool2);

// Add multiple tools
skill.addTools([tool3, tool4]);
```

## Methods

### `skill.addTool(tool)`

Adds a single tool to the skill.

**Example:**
```typescript
skill.addTool(new MyTool());
```

### `skill.addTools(tools)`

Adds multiple tools at once.

**Example:**
```typescript
skill.addTools([tool1, tool2, tool3]);
```

## Complete Examples

### E-commerce Skill

```typescript
import { LuaSkill } from 'lua-cli';
import {
  SearchProductsTool,
  GetProductByIdTool,
  CreateProductTool,
  UpdateProductTool,
  DeleteProductTool
} from './tools';

export const productSkill = new LuaSkill({
  name: 'product-skill',
  
  description: 'Product catalog management tools',
  
  context: `This skill provides comprehensive product management capabilities.

Use Cases:
- Product search: When user asks about products or wants to find items
- Product details: When user wants information about a specific product
- Inventory management: For admins to add/update/remove products

Tool Selection:
- search_products: User browsing or searching
- get_product_by_id: User asks about specific product
- create_product: Admin adding new product
- update_product: Admin updating price, stock, etc.
- delete_product: Admin removing product

Always verify admin permissions before allowing create/update/delete operations.`,

  tools: [
    new SearchProductsTool(),
    new GetProductByIdTool(),
    new CreateProductTool(),
    new UpdateProductTool(),
    new DeleteProductTool()
  ]
});
```

### Customer Support Skill

```typescript
import { LuaSkill } from 'lua-cli';
import {
  CreateTicketTool,
  SearchKnowledgeBaseTool,
  EscalateTool,
  GetTicketStatusTool
} from './tools';

export const supportSkill = new LuaSkill({
  name: 'customer-support-skill',
  
  description: 'Customer support and ticketing tools',
  
  context: `Customer support tools for handling user inquiries and issues.

Workflow:
1. First try search_knowledge_base to find existing solutions
2. If no solution found, create_ticket for the issue
3. For urgent/complex issues, use escalate_tool
4. Users can check ticket status with get_ticket_status

Best Practices:
- Always search knowledge base before creating tickets
- Include all relevant details when creating tickets
- Escalate only when truly necessary
- Keep users informed of ticket status`,

  tools: [
    new SearchKnowledgeBaseTool(),
    new CreateTicketTool(),
    new EscalateTool(),
    new GetTicketStatusTool()
  ]
});
```

### Analytics Skill

```typescript
import { LuaSkill } from 'lua-cli';
import {
  QueryDataTool,
  GenerateReportTool,
  ExportDataTool,
  VisualizeTool
} from './tools/analytics';

export const analyticsSkill = new LuaSkill({
  name: 'analytics-skill',
  
  description: 'Data analytics and reporting tools',
  
  context: `Tools for querying data and generating insights.

Capabilities:
- Query databases with natural language
- Generate visual reports and charts
- Export data in various formats (CSV, JSON, Excel)
- Create visualizations (charts, graphs)

Use When:
- User asks for reports or analytics
- User wants to export data
- User needs data visualizations
- User asks questions that require data analysis

Output Format:
- Include relevant metrics and statistics
- Provide visual charts when applicable
- Explain findings in plain language
- Suggest actionable insights`,

  tools: [
    new QueryDataTool(),
    new GenerateReportTool(),
    new ExportDataTool(),
    new VisualizeTool()
  ]
});
```

## Context Best Practices

### ✅ Good Context

```typescript
context: `Use these payment tools for processing transactions.

Tool Selection:
- create_payment_link: When user wants to pay
- check_payment_status: When user asks about payment status
- process_refund: For refund requests (verify order first)

Security:
- Always validate payment amounts
- Confirm payment details with user before processing
- Never store raw credit card numbers

Error Handling:
- If payment fails, explain the error clearly
- Suggest alternative payment methods
- Provide customer support contact for issues`
```

### ❌ Bad Context

```typescript
context: `Payment stuff`  // Too vague!
```

## Organization Patterns

### By Domain

```typescript
// Separate skills for different business domains
const productSkill = new LuaSkill({...});  // Product operations
const orderSkill = new LuaSkill({...});    // Order processing
const userSkill = new LuaSkill({...});     // User management
```

### By Permission Level

```typescript
// Public tools anyone can use
const publicSkill = new LuaSkill({
  context: 'Tools available to all users...',
  tools: [searchTool, viewTool]
});

// Admin-only tools
const adminSkill = new LuaSkill({
  context: 'Admin tools - verify permissions before use...',
  tools: [createTool, deleteTool, manageTool]
});
```

### By Feature

```typescript
// Shopping cart feature
const cartSkill = new LuaSkill({
  context: 'Shopping cart management...',
  tools: [addToCartTool, removeFromCartTool, checkoutTool]
});

// Wishlist feature  
const wishlistSkill = new LuaSkill({
  context: 'Wishlist management...',
  tools: [addToWishlistTool, removeFromWishlistTool]
});
```

## Dynamic Skills

```typescript
import { LuaSkill } from 'lua-cli';
import { env } from 'lua-cli/skill';

// Build skill based on configuration
const tools = [coreTool];

if (env('ENABLE_ADVANCED_FEATURES') === 'true') {
  tools.push(advancedTool1, advancedTool2);
}

export const dynamicSkill = new LuaSkill({
  name: 'dynamic-skill',
  description: 'Dynamically configured skill',
  context: 'Tools based on environment configuration',
  tools
});
```

## Using in LuaAgent

```typescript
import { LuaAgent } from 'lua-cli';
import { weatherSkill } from './skills/weather';
import { productSkill } from './skills/products';
import { supportSkill } from './skills/support';

export const agent = new LuaAgent({
  name: 'multi-purpose-agent',
  persona: 'You are a helpful assistant...',
  skills: [
    weatherSkill,
    productSkill,
    supportSkill
  ]
});
```

## Validation

LuaSkill automatically validates:
- ✅ Tool names are unique within the skill
- ✅ Tool names follow naming conventions (lowercase, underscores)
- ✅ Each tool implements the LuaTool interface
- ✅ Required fields are present

## Related Documentation

- [LuaTool](./LuaTool.md) - Creating tools
- [LuaAgent](./LuaAgent.md) - Agent configuration
- [Skill Examples](../../template/src/skills/)

## See Also

- [Product Skill Example](../../template/src/skills/product.skill.ts)
- [Basket Skill Example](../../template/src/skills/basket.skill.ts)
- [Organizing Skills Guide](../guides/OrganizingSkills.md)

