feat(tinyclaw): implement skills system with executor and CLI commands

Add SkillExecutor with load/save/execute functionality:
- SkillExecutor struct with storage directory management
- Load/save skills from JSON files in ~/.config/terraphim/skills/
- Execute skills with template variable substitution
- Progress tracking and cancellation support
- Input validation with defaults support

Add CLI commands:
- skill save <path>: Save a skill from JSON file
- skill load <name>: Display skill details
- skill list: Show all saved skills
- skill run <name> [key=value...]: Execute a skill
- skill cancel: Cancel running skill execution

Implement template substitution:
- Replace {variable} patterns with input values
- Smart matching for alphanumeric+underscore variables only
- Prevents false matches on JSON object braces

Tests: 12 new tests (all passing), 87 total tests

Author: AlexMikhalev

Cargo.lock

@@ -47,6 +47,7 @@ env_logger = "0.11"
 
 # Environment
 env_home = "0.1"
+dirs = "5"
 
 # Regex for ExecutionGuard
 regex = "1"
@@ -61,11 +62,16 @@ serenity = { version = "0.12", optional = true }
 # Re-enable when matrix-sdk updates to rusqlite 0.32+ or when conflict resolved
 # matrix-sdk = { version = "0.7", optional = true, default-features = false, features = ["native-tls"] }
 
+# Voice transcription (optional)
+# whisper-rs = { version = "0.11", optional = true }
+# symphonia = { version = "0.5", optional = true, features = ["ogg", "pcm"] }
+
 [features]
 default = ["telegram", "discord"]
 telegram = ["dep:teloxide"]
 discord = ["dep:serenity"]
 # matrix = ["dep:matrix-sdk"]
+# voice = ["dep:whisper-rs", "dep:symphonia"]
 
 [dev-dependencies]
 tokio-test = "0.4"

crates/terraphim_tinyclaw/Cargo.toml

@@ -5,6 +5,7 @@ mod channels;
 mod config;
 mod format;
 mod session;
+mod skills;
 mod tools;
 
 use crate::agent::agent_loop::{HybridLlmRouter, ToolCallingLoop};
@@ -14,8 +15,10 @@ use crate::channel::{Channel, ChannelManager, build_channels_from_config};
 use crate::channels::cli::CliChannel;
 use crate::config::Config;
 use crate::session::SessionManager;
+use crate::skills::{Skill, SkillExecutor};
 use crate::tools::create_default_registry;
 use clap::{Parser, Subcommand};
+use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
 
@@ -47,6 +50,37 @@ enum Commands {
     },
     /// Run as gateway server with all enabled channels.
     Gateway,
+    /// Manage skills (workflows).
+    Skill {
+        #[command(subcommand)]
+        command: SkillCommands,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+enum SkillCommands {
+    /// Save a skill from a JSON file.
+    Save {
+        /// Path to the skill JSON file
+        path: PathBuf,
+    },
+    /// Load and display a skill.
+    Load {
+        /// Name of the skill to load
+        name: String,
+    },
+    /// List all saved skills.
+    List,
+    /// Run a skill with optional inputs.
+    Run {
+        /// Name of the skill to run
+        name: String,
+        /// Input values as key=value pairs (e.g., name=Alice message=hello)
+        #[arg(value_name = "INPUTS")]
+        inputs: Vec<String>,
+    },
+    /// Cancel the currently running skill.
+    Cancel,
 }
 
 #[tokio::main]
@@ -92,6 +126,10 @@ async fn main() -> anyhow::Result<()> {
             log::info!("Starting in gateway mode");
             run_gateway_mode(config).await?;
         }
+        Commands::Skill { command } => {
+            log::info!("Executing skill command");
+            run_skill_command(command).await?;
+        }
     }
 
     log::info!("terraphim-tinyclaw shutting down");
@@ -226,3 +264,144 @@ async fn run_gateway_mode(config: Config) -> anyhow::Result<()> {
 
     Ok(())
 }
+
+async fn run_skill_command(command: SkillCommands) -> anyhow::Result<()> {
+    let executor = SkillExecutor::with_default_storage()
+        .map_err(|e| anyhow::anyhow!("Failed to initialize skill executor: {}", e))?;
+
+    match command {
+        SkillCommands::Save { path } => {
+            let json = tokio::fs::read_to_string(&path)
+                .await
+                .map_err(|e| anyhow::anyhow!("Failed to read skill file: {}", e))?;
+
+            let skill: Skill = serde_json::from_str(&json)
+                .map_err(|e| anyhow::anyhow!("Invalid skill JSON: {}", e))?;
+
+            executor
+                .save_skill(&skill)
+                .map_err(|e| anyhow::anyhow!("Failed to save skill: {}", e))?;
+
+            println!(
+                "✓ Skill '{}' saved successfully (v{})",
+                skill.name, skill.version
+            );
+        }
+
+        SkillCommands::Load { name } => {
+            let skill = executor
+                .load_skill(&name)
+                .map_err(|e| anyhow::anyhow!("Failed to load skill: {}", e))?;
+
+            println!("Skill: {}", skill.name);
+            println!("Version: {}", skill.version);
+            println!("Description: {}", skill.description);
+            if let Some(author) = skill.author {
+                println!("Author: {}", author);
+            }
+
+            if !skill.inputs.is_empty() {
+                println!("\nInputs:");
+                for input in &skill.inputs {
+                    let req = if input.required {
+                        "required"
+                    } else {
+                        "optional"
+                    };
+                    let default = input
+                        .default
+                        .as_ref()
+                        .map(|d| format!(" (default: {})", d))
+                        .unwrap_or_default();
+                    println!(
+                        "  - {}: {} [{}]{}",
+                        input.name, input.description, req, default
+                    );
+                }
+            }
+
+            println!("\nSteps ({} total):", skill.steps.len());
+            for (i, step) in skill.steps.iter().enumerate() {
+                let step_type = match step {
+                    crate::skills::SkillStep::Tool { tool, .. } => format!("tool: {}", tool),
+                    crate::skills::SkillStep::Llm { .. } => "llm".to_string(),
+                    crate::skills::SkillStep::Shell { .. } => "shell".to_string(),
+                };
+                println!("  {}. {}", i + 1, step_type);
+            }
+        }
+
+        SkillCommands::List => {
+            let skills = executor
+                .list_skills()
+                .map_err(|e| anyhow::anyhow!("Failed to list skills: {}", e))?;
+
+            if skills.is_empty() {
+                println!("No skills saved. Use 'skill save <file>' to add one.");
+            } else {
+                println!("Saved skills ({} total):", skills.len());
+                for skill in skills {
+                    println!(
+                        "  • {} (v{}) - {}",
+                        skill.name, skill.version, skill.description
+                    );
+                }
+            }
+        }
+
+        SkillCommands::Run { name, inputs } => {
+            let skill = executor
+                .load_skill(&name)
+                .map_err(|e| anyhow::anyhow!("Failed to load skill: {}", e))?;
+
+            // Parse inputs
+            let mut input_map = HashMap::new();
+            for input in inputs {
+                if let Some((key, value)) = input.split_once('=') {
+                    input_map.insert(key.to_string(), value.to_string());
+                } else {
+                    eprintln!(
+                        "Warning: Invalid input format '{}', expected key=value",
+                        input
+                    );
+                }
+            }
+
+            println!("Running skill '{}'...", skill.name);
+
+            let result = executor
+                .execute_skill(&skill, input_map, None)
+                .await
+                .map_err(|e| anyhow::anyhow!("Skill execution failed: {}", e))?;
+
+            println!("\nStatus: {:?}", result.status);
+            println!("Duration: {}ms", result.duration_ms);
+
+            if !result.output.is_empty() {
+                println!("\nOutput:\n{}", result.output);
+            }
+
+            if !result.execution_log.is_empty() {
+                println!("\nExecution Log:");
+                for log in &result.execution_log {
+                    let status = if log.success { "✓" } else { "✗" };
+                    println!(
+                        "  {} Step {} ({}): {}ms - {}",
+                        status,
+                        log.step_number + 1,
+                        log.step_type,
+                        log.duration_ms,
+                        log.output.chars().take(50).collect::<String>()
+                    );
+                }
+            }
+        }
+
+        SkillCommands::Cancel => {
+            executor.cancel();
+            println!("Cancellation signal sent.");
+        }
+    }
+
+    Ok(())
+}