> ## 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

# 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.

```rust theme={null}
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:

```rust theme={null}
#[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:

```rust theme={null}
#[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:

```rust theme={null}
#[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:

```rust theme={null}
#[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:

```rust theme={null}
#[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:

```rust theme={null}
export_skill!(YourSkillType);
```

Expands to:

```rust theme={null}
#[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:

```rust theme={null}
pub type CreateSkillFn = unsafe extern "C" fn() -> *mut std::ffi::c_void;
```

## Usage Examples

### Basic Skill Implementation

```rust theme={null}
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`:

```toml theme={null}
[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