OpenSkills - Give Your Agents Skills

English | 中文

A Claude Skills compatible runtime with dual sandboxing: native execution (macOS seatbelt + Linux Landlock) for Python and shell scripts (primary), plus experimental WASM-based sandboxing for cross-platform security. OpenSkills implements the Claude Code Agent Skills specification, providing a secure, flexible runtime for executing skills in any agent framework.

Philosophy

OpenSkills is syntactically 100% compatible with Claude Skills, meaning any skill that follows the Claude Skills format (SKILL.md with YAML frontmatter) will work with OpenSkills. What makes OpenSkills unique is its dual sandboxing approach:

• Native sandboxing (primary) for Python and shell scripts via OS-level isolation (macOS seatbelt + Linux Landlock) - production-ready, fully supported
• WASM/WASI sandboxing (experimental) for cross-platform security and consistency - available for early adopters

Primary execution model: Native Python and shell scripts via OS-level sandboxing (macOS seatbelt and Linux Landlock). This is the recommended, production-ready approach that works with the full Python ecosystem and native tools.

Experimental WASM support: WASM sandboxing is available for developers who want to explore cross-platform deterministic execution, but it is not required for using OpenSkills. Most skills work perfectly fine with native scripts.

OpenSkills can be integrated into any agent framework (LangChain, Vercel AI SDK, custom frameworks) to give agents access to Claude-compatible skills.

Core Design Principles

1. 100% Syntactic Compatibility: OpenSkills reads and executes skills using the exact same SKILL.md format as Claude Skills. Skills can be shared between Claude Code and OpenSkills without modification.

2. Dual Sandbox Architecture: OpenSkills combines native OS-level sandboxing (primary) with experimental WASM/WASI 0.3 sandboxing:

   • Native Sandboxing (primary): Python and shell script execution with OS-level isolation (macOS seatbelt + Linux Landlock) - production-ready, full ecosystem support
   • WASM/WASI (experimental): Cross-platform security, capability-based permissions, memory safety, deterministic execution - available for early adopters
   • Automatic Detection: Runtime automatically chooses the appropriate sandbox based on skill type
   • Native-first: Most skills use native scripts; WASM is optional for specific use cases

3. Native Scripts First: OpenSkills prioritizes native Python and shell script execution, which provides full access to the Python ecosystem and native tools. WASM compilation is available as an experimental option for specific use cases requiring cross-platform determinism.

Target Use Case

OpenSkills is designed for any agent framework that needs Claude-compatible skills:

• Agent Framework Integration: Works with LangChain, Vercel AI SDK, custom frameworks, or any system that needs tool-like capabilities
• Enterprise Agents: Internal skills developed by trusted developers
• Native Scripts: Primary execution model using Python and shell scripts with OS-level sandboxing
• Cross-Platform Native: macOS seatbelt + Linux Landlock (both production-ready)
• Experimental WASM: Optional WASM execution for specific use cases requiring determinism
• Security & Auditability: Both sandboxing methods provide strong isolation and audit logging

Recommended approach: Use native Python and shell scripts for most skills. WASM is available for experimental use cases but is not required.

Limitations

Current Limitations

1. Native Scripts Platform Scope:

   • Native Python and shell scripts are supported on macOS (seatbelt) and Linux (Landlock) - both production-ready
   • Other platforms should use experimental WASM execution

2. WASM Support (Experimental):

   • WASM sandboxing is experimental and not the primary execution method
   • Build workflow required: JavaScript/TypeScript skills must be compiled to WASM components before execution
   • Limited native library support: Native Python packages, shell tools, etc. don't work in WASM
   • WASI compatibility required: Code must use WASI APIs, not native OS APIs

Recommendation: Use native Python and shell scripts for production skills. WASM is available for experimental use cases but is not required.

Roadmap

OpenSkills will evolve to address limitations while maintaining its native-first approach:

1. Enhanced Native Sandboxing: Continue improving Linux Landlock and macOS seatbelt policy coverage and diagnostics.

2. WASM Improvements (experimental): Continued development of WASM support for specific use cases requiring determinism and cross-platform consistency.

3. Enhanced Tooling: Better development tools and templates for both native scripts and WASM compilation.

Features

• ✅ 100% Claude Skills Compatible: Full SKILL.md format support
• 🔒 Dual Sandbox Architecture: Native (macOS seatbelt + Linux Landlock) + experimental WASM/WASI 0.3
• 🧰 Native Script Support: Execute Python and shell scripts with OS-level sandboxing on macOS and Linux
• 🤖 Any Agent Framework: Integrate with LangChain, Vercel AI SDK, or custom frameworks
• 🚀 Pre-built Tools: Ready-to-use tool definitions for TS/Python (~200 lines less code)
• 📊 Progressive Disclosure: Efficient tiered loading (metadata → instructions → resources)
• 🔌 Multi-Language Bindings: Rust core with TypeScript and Python bindings
• 🛡️ Capability-Based Security: Fine-grained permissions via native OS sandboxing (and WASI for experimental WASM)
• 🏗️ Build Tool: openskills build for compiling TS/JS to WASM components (experimental)
• 🌐 Cross-Platform Native: macOS seatbelt + Linux Landlock (both production-ready)
• 📁 Workspace Management: Built-in sandboxed workspace for file I/O operations

Quick Start

Installation

# Rust (from source)
git clone https://github.com/Geeksfino/openskills.git
cd openskills

# Initialize submodules (required for tests and examples)
git submodule update --init --recursive

cd runtime
cargo build --release

# TypeScript
npm install @finogeek/openskills

# Python
pip install finclip-openskills
# Note: Pre-built wheels are available for macOS and Linux only.
# Windows users need to build from source: git clone https://github.com/Geeksfino/openskills.git && cd openskills/bindings/python && pip install maturin && maturin develop

Building a Skill

OpenSkills uses a plugin-based build system for compiling JavaScript/TypeScript → WASM. The system supports multiple build backends (plugins), allowing you to choose the compiler that best fits your needs.

Plugin System Architecture:

• Plugins: Modular build backends that handle compilation (e.g., javy, quickjs, assemblyscript)
• Auto-detection: When no plugin is specified, the system tries available plugins in order until one works
• Plugin selection: Choose explicitly via --plugin flag or .openskills.toml config file

Recommended for new users: The quickjs plugin (easiest setup - just run the setup script below)

First-time setup (required before building skills):

Run the setup script to install build tools and download dependencies:

# This will:
# - Download the WASI adapter
# - Install javy CLI (downloads pre-built binary when available)
# - Install wasm-tools
# - Check for optional tools (AssemblyScript)
./scripts/setup_build_tools.sh

Build a skill:

# Build a skill from TypeScript/JavaScript
cd my-skill
openskills build

# Auto-detection: tries plugins in order (javy → quickjs → assemblyscript)
# until it finds one that's available and has all dependencies

Choose a plugin explicitly:

openskills build --plugin quickjs       # Recommended: easiest setup
openskills build --plugin javy          # Requires javy plugin.wasm file
openskills build --plugin assemblyscript # Requires asc compiler
openskills build --list-plugins         # Show all available plugins and their status

Plugin comparison:

• quickjs (recommended): Easiest setup - just run setup script. Uses javy CLI + wasm-tools. Supports WASI 0.3.
• javy: Requires building javy plugin.wasm file. Uses javy-codegen library. Legacy support.
• assemblyscript: High-performance TypeScript-like language. Requires asc compiler.

Alternative: javy plugin setup (if you prefer the default javy plugin):

If you want to use the javy plugin instead of quickjs, you need to build the javy plugin:

# Build the javy plugin (one-time setup)
./scripts/build_javy_plugin.sh

# Export the plugin path (or add to your shell profile)
export JAVY_PLUGIN_PATH=/tmp/javy/target/wasm32-wasip1/release/plugin_wizened.wasm

Config file (optional): place .openskills.toml or openskills.toml in the skill directory.

[build]
plugin = "quickjs"  # or "assemblyscript"

# Plugin options are usually auto-detected
# [build.plugin_options]
# adapter_path = "~/.cache/openskills/wasi_preview1_adapter.wasm"

How the plugin system works:

1. Plugin selection: You can specify a plugin via --plugin flag, config file, or let the system auto-detect
2. Auto-detection: When no plugin is specified, the system tries registered plugins in order until it finds one that:
   • Is available (has all required dependencies)
   • Supports the source file extension (.ts, .js, etc.)
3. Plugin execution: Each plugin handles the full compilation pipeline:
   • TypeScript transpilation (if needed)
   • JavaScript/TypeScript → WASM core module
   • WASM core → WASI 0.3 component (for quickjs/assemblyscript)
4. Automatic setup: QuickJS/AssemblyScript plugins auto-download the WASI adapter if needed
5. **Configu