Pre-release

This release is a pre-release and may not be stable for production use.

Skiller.run

A runtime for agentic workflows.

Skiller runs agentic flows as durable executions with persistent state, safe resume, and full observability logs.

What It Does

Runs durable YAML flows that can include agents
Pauses and resumes flows from persisted waiting states
Provides CLI to observe and manage persisted runs
Includes a TUI for chatting with agents, launching flows, and managing runs

name: mono
description: "Terminal agent chat with shell and file access"
version: "0.1"
start: ask_user

inputs: {}

steps:
  - wait_input: ask_user
    prompt: "Write a task or message. Type exit, quit, or bye to stop."
    next: decide_exit

  - switch: decide_exit
    value: '{{output_value("ask_user").payload.text}}'
    cases:
      exit: done
      quit: done
      bye: done
    default: mono_agent

  - agent: mono_agent
    system: |
      You are a concise assistant for this flow.
    instructions:
      - "solve-task-style"
      - "response-style"
    task: '{{output_value("ask_user").payload.text}}'
    tools:
      - shell
      - files
    max_turns: 50
    next: ask_user

  - assign: done
    values:
      status: "closed"

Install

For regular CLI usage, install it with pipx:

pipx install skiller

STUI for chat and launch runs

Use skiller when you want an interactive terminal UI to chat, launch runs, and manage persisted runs.

skiller

Use CLI to run flows

Run a packaged, local, or configured flow reference:

skiller run @flows
skiller run @group/name

Direct paths are also supported:

skiller run ./my-flow.yaml
skiller run ~/flows/my-flow.yaml

Inspect and manage runs:

skiller status <run_id>
skiller logs <run_id>
skiller delete <run_id>

Flow Steps

Deterministic:

assign
notify
switch
when

Execution:

agent
shell

Waiting:

wait_input
wait_webhook

Persistence

Skiller persists:

run state
step outputs
runtime log events
waiting states
external event receipts
persisted output bodies

Waiting is persisted, not simulated in memory. A run can stop in WAITING and resume later from stored state.

How Mono Is Built

mono is a regular YAML-defined agent with local runtime configuration beside it. The flow is intentionally small:

wait for terminal input with wait_input
stop on exit, quit, or bye with switch
send every other message to an agent step
let that agent use its configured shell and files tools
loop back to wait_input

Minimal shape:

name: mono
start: ask_user

steps:
  - wait_input: ask_user
    next: decide_exit

  - switch: decide_exit
    default: support_agent

  - agent: support_agent
    tools:
      - shell
      - files
    next: ask_user

The full prompt and step definition live in apps/agents/mono/agent.yaml. The provider, loop limits, shell allowlist, and file roots live in apps/agents/mono/agent.json.

Project Layout

packages/skiller/src/skiller: runtime and CLI code
apps/agents/mono: bundled terminal agent
packages/skiller/docs: runtime and CLI documentation
packages/skiller/tests: runtime, CLI, and integration tests
apps/tui: Textual UI app

Documentation

Core guides:

Step references:

Development

Run the main checks:

./.venv/bin/python -m ruff check packages/skiller/src apps/tui/src packages/skiller/tests apps/tui/tests
./.venv/bin/python -m pytest packages/skiller/tests apps/tui/tests
./.venv/bin/python -m build --no-isolation

Manual CLI E2E flows live in packages/skiller/tests/e2e/cli_*.sh. Use them when you need to exercise the real CLI path without mixing those checks into the default pytest suite.

License

Apache-2.0. See LICENSE.

Disclaimer

This project is provided "as is", without warranties of any kind. The authors and contributors are not responsible for production incidents, data loss, service interruptions, security issues, regulatory non-compliance, third-party integration failures, or any direct or indirect damages resulting from its use.

Metadata

Release files for skiller 0.1.0b38

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for skiller 0.1.0b38
File	Size	Uploaded
skiller-0.1.0b38.tar.gz	319.4 kB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for skiller 0.1.0b38
File	Interpreter	ABI	Platform	Reset
skiller-0.1.0b38-py3-none-any.whl 539.5 kB Sep 10, 2026	Python 3	none	any	Details

Total release size: 858.9 kB

Release files / skiller-0.1.0b38.tar.gz

Download URL	skiller-0.1.0b38.tar.gz
Size	319.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`33b45c94c9f105700c774e376aa9dd30b9bc301dd5c2cc398e95ab2e2b23514a`
BLAKE2b-256 checksum How to use checksums	`04d3d3b93d77c369ab5dce8c066aaadf80d347040be0808f3bd70d13d711d053`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/fredycampino/skiller
Publishing commit: github.com/fredycampino/skiller/tree/6bbfa9d14925424221432b818ac406a762a87f19

Workflow

Publishing configuration: github.com/fredycampino/skiller/blob/6bbfa9d14925424221432b818ac406a762a87f19/.github/workflows/publish.yml
Publishing logs: github.com/fredycampino/skiller/actions/runs/34506411092/attempts/1

Artifact

Subject: skiller-0.1.0b38.tar.gz
SHA-256 checksum: 33b45c94c9f105700c774e376aa9dd30b9bc301dd5c2cc398e95ab2e2b23514a Verifying attestations

Release files / skiller-0.1.0b38-py3-none-any.whl

Download URL	skiller-0.1.0b38-py3-none-any.whl
Size	539.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ea5f06884c6ad419bda81ca7ef9a5f5f208d189bcb5345d3c338c109a58991b3`
BLAKE2b-256 checksum How to use checksums	`68f7ed7311ed40f63aef3e550348a6cce31315df3406e60920096c22f2cdeb75`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/fredycampino/skiller
Publishing commit: github.com/fredycampino/skiller/tree/6bbfa9d14925424221432b818ac406a762a87f19

Workflow

Publishing configuration: github.com/fredycampino/skiller/blob/6bbfa9d14925424221432b818ac406a762a87f19/.github/workflows/publish.yml
Publishing logs: github.com/fredycampino/skiller/actions/runs/34506411092/attempts/1

Artifact

Subject: skiller-0.1.0b38-py3-none-any.whl
SHA-256 checksum: ea5f06884c6ad419bda81ca7ef9a5f5f208d189bcb5345d3c338c109a58991b3 Verifying attestations