Documentation Index
Fetch the complete documentation index at: https://doc.ambientsoul.ai/llms.txt
Use this file to discover all available pages before exploring further.
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(()) }
}
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),
}
#[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);
#[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
