OpenSkills SDK

An open-source Agent Skill framework implementing the progressive disclosure architecture for AI agent skills.

Features

Three-layer progressive disclosure architecture
- Layer 1 (Metadata): Always loaded for skill discovery
- Layer 2 (Instruction): Loaded on demand when skill is selected
- Layer 3 (Resources): Conditionally loaded References and Scripts
SKILL.md file format - Simple markdown-based skill definition
Smart Reference loading - Three modes (explicit/implicit/always) with LLM-based selection
Auto-discovery - Automatically discover references from references/ directory
Script execution - Run scripts triggered by LLM via [INVOKE:name]
Multiple LLM providers - OpenAI, Azure OpenAI, Ollama, Together, Groq, DeepSeek
Auto skill invocation - Automatically match and invoke skills based on user queries
Multimodal support - Handle images via URL, base64, or file path
Sandbox execution - Secure script execution in isolated AIO Sandbox environment
Automatic file sync - Upload input files and download outputs automatically

Installation

pip install openskills-sdk

Quick Start

Using SkillAgent (Recommended)

import asyncio
from openskills import create_agent

async def main():
    # Create agent with infographic-skills
    agent = await create_agent(
        skill_paths=["./infographic-skills"],
        api_key="your-api-key",
        model="gpt-4",
    )

    # Chat with automatic skill invocation
    response = await agent.chat("帮我总结会议")
    print(response.content)
    print(f"Used skill: {response.skill_used}")

asyncio.run(main())

Using Sandbox Mode (Recommended for Script Execution)

import asyncio
from openskills import create_agent

async def main():
    # Create agent with sandbox enabled
    agent = await create_agent(
        skill_paths=["./skills"],
        api_key="your-api-key",
        model="gpt-4",
        use_sandbox=True,  # Enable sandbox execution
        sandbox_base_url="http://localhost:8080",
        auto_execute_scripts=True,
    )

    # Local file paths are automatically uploaded to sandbox
    response = await agent.chat("请处理这个文件: /path/to/file.pdf")
    print(response.content)

    # Output files are automatically downloaded to skill_dir/output/

asyncio.run(main())

Using SkillManager (Low-level API)

from pathlib import Path
from openskills import SkillManager

manager = SkillManager([Path("./infographic-skills")])

# Discover infographic-skills (Layer 1 - Metadata)
await manager.discover()

# Match user query
skills = manager.match("summarize meeting")

# Load instruction (Layer 2)
if skills:
    instruction = await manager.load_instruction(skills[0].name)
    print(instruction.content)

Sandbox Environment

OpenSkills supports executing scripts in an isolated sandbox environment using AIO Sandbox. This provides:

Security: Scripts run in isolated containers
Dependency management: Auto-install Python packages defined in SKILL.md
File synchronization: Automatic upload/download of files

Installing AIO Sandbox

Option 1: Docker (Recommended)

# Pull and run the sandbox container
docker run -d --name aio-sandbox \
  -p 8080:8080 \
  ghcr.io/agent-infra/aio-sandbox:latest

# Verify it's running
curl http://localhost:8080/health

Option 2: Docker Compose

# docker-compose.yml
version: '3.8'
services:
  sandbox:
    image: ghcr.io/agent-infra/aio-sandbox:latest
    ports:
      - "8080:8080"
    volumes:
      - sandbox-data:/home/gem
    restart: unless-stopped

volumes:
  sandbox-data:

docker-compose up -d

Sandbox Features

Automatic Dependency Installation

Define dependencies in SKILL.md frontmatter:

dependency:
  python:
    - PyMuPDF==1.23.8
    - pandas>=2.0.0
  system:
    - mkdir -p output/images

Dependencies are installed automatically when the skill is initialized.

Automatic File Synchronization

Upload: Local file paths in script input are auto-uploaded to /home/gem/uploads/
Download: Specify output directories in script config to auto-download results

scripts:
  - name: process_file
    path: scripts/process.py
    description: Process uploaded files
    timeout: 120
    outputs:
      - /home/gem/output  # Auto-sync to local skill_dir/output/

Sandbox Client API

For advanced use cases, use the SandboxClient directly:

from openskills.sandbox import SandboxClient

async with SandboxClient("http:

...

twwch/openskills

README