Skip to main content

​
Skill ABI API Reference

🚧 Work-in-Progress: This documentation is being actively developed.

​
Overview

The Skill ABI (Application Binary Interface) defines the contract between the Soul Kernel and Skills. This reference documents all types, traits, and functions available in the soul-kernel-skill-abi crate.

​
Core Trait

​
Skill

The main trait that all skills must implement. 
pub trait Skill: Send + Sync {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn capabilities(&self) -> Vec<Capability>;
    fn execute(&self, input: SkillInput) -> Result<SkillOutput, SkillError>;
    fn initialize(&mut self) -> Result<(), SkillError> { Ok(()) }
    fn shutdown(&mut self) -> Result<(), SkillError> { Ok(()) }
}
Thread Safety: Skills must be Send + Sync to support concurrent execution.

​
Types

​
Capability

Declares what a skill can do: 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum Capability {
    TextProcessing,
    ImageProcessing,
    AudioProcessing,
    VoiceSynthesis,
    VisionAnalysis,
    MotorControl,
    DataStorage,
    NetworkAccess,
    Custom(String),
}

​
SkillInput

Input types that can be passed to skills: 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum SkillInput {
    Text(String),
    Image(Vec<u8>),
    Audio(Vec<f32>),
    Json(serde_json::Value),
    Binary(Vec<u8>),
}

​
SkillOutput

Output types that skills can return: 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum SkillOutput {
    Text(String),
    Image(Vec<u8>),
    Audio(Vec<f32>),
    Json(serde_json::Value),
    Action(ActionCommand),
    Binary(Vec<u8>),
}

​
ActionCommand

Commands for controlling actuators in Physical AI: 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ActionCommand {
    pub target: String,
    pub action: String,
    pub parameters: serde_json::Value,
}

​
SkillError

Error types for skill execution: 
#[derive(Debug)]
pub enum SkillError {
    InvalidInput(String),
    ExecutionError(String),
    NotImplemented(String),
    ResourceUnavailable(String),
    Custom(Box<dyn Error + Send + Sync>),
}

​
Macros

​
export_skill!

Generates the required FFI export function: 
export_skill!(YourSkillType);
Expands to: 
#[no_mangle]
pub unsafe extern "C" fn create_skill() -> *mut std::ffi::c_void {
    let skill = Box::new(YourSkillType::new());
    let boxed: Box<dyn Skill> = skill;
    Box::into_raw(Box::new(boxed)) as *mut std::ffi::c_void
}

​
FFI Functions

​
create_skill

The C-compatible function that must be exported by dynamic libraries: 
pub type CreateSkillFn = unsafe extern "C" fn() -> *mut std::ffi::c_void;

​
Usage Examples

​
Basic Skill Implementation

use soul_kernel_skill_abi::*;

pub struct MySkill;

impl MySkill {
    pub fn new() -> Self {
        Self
    }
}

impl Skill for MySkill {
    fn name(&self) -> &str {
        "my-skill"
    }
    
    fn version(&self) -> &str {
        "1.0.0"
    }
    
    fn capabilities(&self) -> Vec<Capability> {
        vec![Capability::TextProcessing]
    }
    
    fn execute(&self, input: SkillInput) -> Result<SkillOutput, SkillError> {
        match input {
            SkillInput::Text(text) => {
                Ok(SkillOutput::Text(text.to_uppercase()))
            }
            _ => Err(SkillError::InvalidInput("Expected text".to_string()))
        }
    }
}

export_skill!(MySkill);

​
Building as Dynamic Library

In Cargo.toml: 
[lib]
crate-type = ["cdylib"]

[dependencies]
soul-kernel-skill-abi = "0.1"

​
Version Compatibility

  • Minimum supported Rust version: 1.79
  • ABI Version: 1.0.0
  • Binary compatibility: Platform-specific (.dylib, .so, .dll)

​
Safety Considerations

  • Skills run in the same process space
  • No sandboxing in v1 (planned for future)
  • Validate all inputs before processing
  • Handle errors gracefully (no panics)

​
Change Log

  • 2025-06-12: Initial API documentation for Skill ABI V1
    • Documented all public types and traits
    • Added FFI details and safety notes
    • Included usage examples