Skill Runner

A unified execution framework for AI agent skills

Skill Runner wraps mature AI agent CLIs — Codex, Gemini CLI, OpenCode, Claude Code, Qwen, Kilo Code, and CodeBuddy — behind a unified Skill protocol, providing deterministic execution, structured artifact management, and a built-in web admin UI.

✨ Highlights

🧩 Pluggable Skills
Drop-in skill packages
_{Schema-validated I/O}

🤖 Multi-Engine
Codex · Gemini · OpenCode · Claude Code · Qwen · Kilo Code · CodeBuddy
_{Unified adapter protocol}

🔄 Dual Mode
Auto & Interactive execution
_{Multi-turn conversations}

📦 Structured Output
JSON + artifacts + bundle
_{Isolated, contract-driven runs}

🧩 Pluggable Skill Design

Skill Runner's core advantage is its pluggable skill architecture — every automation task is packaged as a self-contained, engine-agnostic skill that can be installed, shared, and executed without modification.

What is a Skill?

Skill Runner skills are built on the Open Agent Skills standard — the same format used by Claude Code, Codex CLI, Cursor, and more. Skill Runner extends this standard into an AutoSkill superset by adding an execution contract (runner.json) and schema validation files:

my-skill/
├── SKILL.md                 # Prompt instructions (Open Agent Skills standard)
├── assets/
│   ├── runner.json          # Execution contract (Skill Runner extension)
│   ├── input.schema.json    # Input schema (JSON Schema)
│   ├── parameter.schema.json
│   └── output.schema.json   # Output schema — validated after execution
├── references/              # Reference documents (optional)
└── scripts/                 # Helper scripts (optional)

Any standard Open Agent Skills package (a folder with SKILL.md) can run on Skill Runner. Adding assets/runner.json + schemas promotes it to an AutoSkill — enabling automatic execution, schema validation, and reproducible results.

Why It Matters

Standards-based: Compatible with the Open Agent Skills ecosystem — skills are portable across platforms.
Engine-agnostic: Write once, run on any supported engine. The same skill works with Codex, Gemini, OpenCode, Claude Code, Qwen, Kilo Code, or CodeBuddy.
Schema-driven I/O: Input, parameter, and output are all defined by JSON Schema — the runner validates automatically.
Isolated execution: Each run gets its own workspace with standardized I/O contracts — no cross-run interference.
Zero-integration install: Drop a skill directory into user dir skills/ (or upload via API/UI) and it's immediately available. Built-in skills ship in skills_builtin/.
Cache reuse: Identical inputs and parameters can reuse previous results — no redundant engine invocations.

Execution Modes

Every skill declares its supported execution modes in runner.json:

auto — Fully autonomous. The engine runs the prompt to completion without human intervention.
interactive — Multi-turn conversation. The engine may pause to ask questions; the user (or an upstream system) provides replies via the interaction API.

📖 Full specification: AutoSkill Package Guide · File Protocol

🚀 Quick Start

Docker (recommended)

mkdir -p data
docker compose up -d --build

API: http://localhost:9813/v1
Admin UI: http://localhost:9813/ui
Docker Compose defaults to bind mount ./skills:/app/skills for user skills.
Built-in skills are bundled in-image at /app/skills_builtin and are not overridden by this path.

Or run independently:

docker run --rm -p 9813:9813 -p 17681:17681 \
  -v "$(pwd)/skills:/app/skills" \
  -v skillrunner_cache:/opt/cache \
  leike0813/skill-runner:latest

Local Deployment

# Linux / macOS
./scripts/deploy_local.sh

# Windows (PowerShell)
.\scripts\deploy_local.ps1

Prerequisites:

uv
Node.js and npm
ttyd (optional, required only for Inline TUI in /ui/engines)

Plugin-oriented control CLI:

# Linux / macOS
./scripts/skill-runnerctl status --mode local --json
./scripts/skill-runnerctl up --mode local --json
./scripts/skill-runnerctl down --mode local --json
sh ./scripts/skill-runner-uninstall.sh --json
sh ./scripts/skill-runner-uninstall.sh --clear-data --clear-agent-home --json

# Windows (PowerShell)
.\scripts\skill-runnerctl.ps1 status --mode local --json
.\scripts\skill-runner-uninstall.ps1 -Json
.\scripts\skill-runner-uninstall.ps1 -ClearData -ClearAgentHome -Json

skill-runnerctl local mode defaults to a platform local root ($HOME/.local/share/skill-runner on Linux/macOS, %LOCALAPPDATA%\SkillRunner on Windows), with data under <LocalRoot>/data.
skill-runnerctl local mode default port is 29813 with fallback scan 29813-29823 (configurable via SKILL_RUNNER_LOCAL_PORT / SKILL_RUNNER_LOCAL_PORT_FALLBACK_SPAN).
Service general default port remains 9813 (for deploy_local.* / container entrypoint when PORT is not set).
deploy_local.* keeps its existing PROJECT_ROOT/data default unless overridden by env vars.

Release installers (for fixed-tag assets + SHA256 verification):

# Linux / macOS
./scripts/skill-runner-install.sh --version v0.4.3

# Windows (PowerShell)
.\scripts\skill-runner-install.ps1 -Version v0.4.3

The installers download these GitHub Release assets for the selected tag:

skill-runner-<version>.tar.gz
skill-runner-<version>.tar.gz.sha256

Deploy directly from a release compose asset:

VERSION=v0.7.0
curl -fL -o docker-compose.release.yml \
  "https://github.com/leike0813/Skill-Runner/releases/download/${VERSION}/docker-compose.release.yml"
curl -fL -o docker-compose.release.yml.sha256 \
  "https://github.com/leike0813/Skill-Runner/releases/download/${VERSION}/docker-compose.release.yml.sha256"
# Optional integrity check:
sha256sum -c docker-compose.release.yml.sha256
docker compose -f docker-compose.release.yml up -d

Containerized harness entrypoint:

TUI Mode

./scripts/agent_harness_container.sh start codex

Non-interactive Mode (or requiring parameter passthrough)

./scripts/agent_harness_container.sh start codex -- --json --full-auto "hello"

📋 Advanced Configuration

Environment Variables

Variable	Description	Default
`SKILL_RUNNER_DATA_DIR`	Run data directory	`skill-runnerctl`: `<LocalRoot>/data`; `deploy_local.*`: `data/`
`SKILL_RUNNER_AGENT_HOME`	Isolated agent config home	auto
`SKILL_RUNNER_AGENT_CACHE_DIR`	Agent cache root	auto
`SKILL_RUNNER_NPM_PREFIX`	Managed CLI install prefix	auto
`ZOTERO_BRIDGE_BIN`	Managed Zotero Bridge CLI executable path	`<SKILL_RUNNER_NPM_PREFIX>/bin/zotero-bridge`
`SKILL_RUNNER_RUNTIME_MODE`	`local` or `container`	auto
`SKILL_RUNNER_LOCAL_PORT`	`skill-runnerctl` local default port	`29813`
`SKILL_RUNNER_LOCAL_PORT_FALLBACK_SPAN`	`skill-runnerctl` local fallback span	`10`

UI Basic Auth

docker run --rm -p 9813:9813 -p 17681:17681 \
  -v "$(pwd)/skills:/app/skills" \
  -v skillrunner_cache:/opt/cache \
  -e UI_BASIC_AUTH_ENABLED=true \
  -e UI_BASIC_AUTH_USERNAME=admin \
  -e UI_BASIC_AUTH_PASSWORD=change-me \
  leike0813/skill-runner:latest

🖥️ Web Admin UI

Access the built-in management interface at /ui:

Skill Browser — View installed skills, inspect package structure and files
Engine Management — Monitor engine status, trigger upgrades, view logs
Model Catalog — Browse and manage engine model snapshots
Inline TUI — Launch engine terminals directly in the browser (single managed session, requires ttyd)

🔑 Engine Authentication

Skill Runner provides multiple authentication methods, from fully managed to manual.

Recommended: OAuth Proxy (via Admin UI)

The preferred approach — authenticate engines through the built-in OAuth Proxy in the Admin UI (/ui/engines):

Open the engine management page.
If the target engine is not installed yet, use the same per-engine action button to install it first.
Select an engine and choose OAuth Proxy as the auth method.
Complete the browser-based OAuth flow.
Credentials are automatically stored and managed.

This also works during active runs: if an engine requires authentication mid-execution, the frontend can present an in-session auth challenge — the run pauses, the user completes OAuth, and execution resumes automatically.

CodeBuddy providers: choose CodeBuddy 国内版 (codebuddy-cn) or CodeBuddy 国际版 (codebuddy-global) before logging in. Their credentials and persistent CLI state are isolated; models come from the engine-local provider-qualified static manifest. Missing, expired, or runtime-rejected credentials enter the existing browser authentication flow and automatically resume after success. The management UI shows only a redacted credential status, supports clearing one provider at a time, and can start the built-in TUI only after the operator explicitly selects a signed-in provider. CodeBuddy runs and TUI sessions use strict run-local MCP configuration; callers should use runtime_options.no_cache=true when account identity must not reuse a cached result.

⚠️ High-risk notice (OpenCode + Google/Antigravity):
For opencode with provider_id=google (Antigravity path, using third-party plugin opencode-antigravity-auth), both oauth_proxy and cli_delegate are considered a high-risk third-party login route. This path may violate Google policy and could lead to account suspension.

Alternative: CLI Delegate

CLI Delegate orchestration launches the engine's native login flow. Compared to OAuth Proxy, it offers:

Native fidelity — uses the engine's built-in auth exactly as designed.
Lower risk — no proxy layer; credentials flow directly to the engine.

Available from the same Admin UI engine management interface.

Other Methods

Click to expand legacy methods

Inline TUI — The Admin UI embeds engine terminals (/ui/engines) where you can run CLI login commands directly in the browser (requires ttyd).

Container CLI login:

docker exec -it <container_id> /bin/bash
# Run the CLI login flow inside the container

Import credential files via UI — In /ui/engines, open the engine auth menu and choose Import Credentials. Skill Runner validates the uploaded files and writes them into the isolated Agent Home paths automatically.

📡 API & Client Design

# List available skills
curl -sS http://localhost:9813/v1/skills

# Create a job
curl -sS -X POST http://localhost:9813/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "demo-bible-verse",
    "engine": "gemini",
    "parameter": { "language": "en" },
    "model": "gemini-3-pro-preview"
  }'

# Get results
curl -sS http://localhost:9813/v1/jobs/<request_id>/result

Building a Frontend

Skill Runner exposes two SSE channels for real-time run observation:

Channel	Endpoint	Purpose
Chat	`GET /v1/jobs/{id}/chat?cursor=N`	Pre-projected chat bubbles — ideal for conversation UIs
Events	`GET /v1/jobs/{id}/events?cursor=N`	Full FCMP protocol events — ideal for admin/debugger tools

Both channels support cursor-based reconnection and history queries (/chat/history, /events/history) for disconnect compensation.

The typical frontend flow:

POST /v1/jobs → (optional upload) → SSE /chat → render bubbles
                                   ↕ waiting_user → POST /interaction/reply
                                   → terminal → GET /result + /bundle

📖 Full frontend design guide: Frontend Design Guide 📖 API reference: API Reference

🏗️ Architecture

graph TD
    Client[Client / LLM] -->|HTTP| API[FastAPI]
    
    subgraph Core
        API --> Orchestrator[Job Orchestrator]
        Orchestrator --> Registry[Skill Registry]
        Orchestrator --> Workspace[Workspace Manager]
    end

    subgraph Engines
        Orchestrator --> Codex[Codex Adapter]
        Orchestrator --> Gemini[Gemini Adapter]
        Orchestrator --> OpenCode[OpenCode Adapter]
        Orchestrator --> ClaudeCode[Claude Code Adapter]
        Orchestrator --> Qwen[Qwen Adapter]
        Orchestrator --> KiloCode[Kilo Code Adapter]
    end

    subgraph Storage
        Registry --> BuiltinSkills[skills_builtin/]
        Registry --> UserSkills[skills/]
        Workspace --> Runs[data/runs/]
    end

    Codex --> CodexCLI[Codex CLI]
    Gemini --> GeminiCLI[Gemini CLI]
    OpenCode --> OpenCodeCLI[OpenCode]
    ClaudeCode --> ClaudeCodeCLI[Claude Code CLI]
    Qwen --> QwenCLI[Qwen CLI]
    KiloCode --> KiloCodeCLI[Kilo Code]

Execution Flow: POST /v1/jobs → input upload → engine execution → output validation → GET /v1/jobs/{id}/result

🔌 Supported Engines

Engine	Package
Codex	`@openai/codex`
Gemini CLI	`@google/gemini-cli`
OpenCode	`opencode-ai`
Claude Code	`@anthropic-ai/claude-code`
Qwen	`@qwen-code/qwen-cli`
Kilo Code	`@kilocode/cli`

All engines support both Auto and Interactive execution modes.

📖 Documentation

Document	Description
Architecture Overview	System design and component map
AutoSkill Package Guide	Building skill packages
Adapter Design	Engine adapter protocol (5-phase pipeline)
Execution Flow	End-to-end run lifecycle
API Reference	REST API specification
Frontend Design Guide	Building frontend clients
Containerization	Docker deployment guide
Zotero Plugin Integration Contract	One-click deploy and local lease lifecycle contract
Developer Guide	Contributing and development

⚠️ Disclaimer

Codex, Gemini CLI, OpenCode, Claude Code, Qwen, and Kilo Code are fast-evolving tools. Their config formats, CLI behavior, and API details may change in short cycles. If you encounter compatibility issues with newer CLI versions, please open an issue.

_{Made with ❤️ by Joshua Reed}

Name		Name	Last commit message	Last commit date
.github		.github
agent_harness		agent_harness
artifacts		artifacts
assets		assets
docs		docs
e2e_client		e2e_client
openspec		openspec
plugins		plugins
references		references
scripts		scripts
server		server
skills		skills
skills_builtin		skills_builtin
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
README_FR.md		README_FR.md
README_JA.md		README_JA.md
docker-compose.release.tmpl.yml		docker-compose.release.tmpl.yml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

Skill Runner

✨ Highlights

🧩 Pluggable Skill Design

What is a Skill?

Why It Matters

Execution Modes

🚀 Quick Start

Docker (recommended)

Local Deployment

Environment Variables

UI Basic Auth

🖥️ Web Admin UI

🔑 Engine Authentication

Recommended: OAuth Proxy (via Admin UI)

Alternative: CLI Delegate

Other Methods

📡 API & Client Design

Building a Frontend

🏗️ Architecture

🔌 Supported Engines

📖 Documentation

⚠️ Disclaimer

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Skill Runner

✨ Highlights

🧩 Pluggable Skill Design

What is a Skill?

Why It Matters

Execution Modes

🚀 Quick Start

Docker (recommended)

Local Deployment

Environment Variables

UI Basic Auth

🖥️ Web Admin UI

🔑 Engine Authentication

Recommended: OAuth Proxy (via Admin UI)

Alternative: CLI Delegate

Other Methods

📡 API & Client Design

Building a Frontend

🏗️ Architecture

🔌 Supported Engines

📖 Documentation

⚠️ Disclaimer

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages