lua-cli 3.5.0-alpha.3 → 3.5.0-beta.1

package/docs/api/LuaSkill.md

@@ -0,0 +1,396 @@
+# 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)
+