whale-agent-lab/flowscript

FlowScript Skill Runtime is an experimental tool for turning a skill written in plain Markdown into a workflow that runs in a fixed, predictable order rather than letting an AI model decide what to do next on its own. The idea is to keep a skill file readable by a person or by an ordinary AI agent, while also giving it an explicit, machine enforced set of steps written in a small workflow language stored in a file called FLOWSCRIPT.md. The runtime reads that workflow definition and executes a sequence of nodes: some call a language model, some run validator checks, and some run plain Python scripts. A component called the WorkflowEngine is solely responsible for deciding execution order, which script runs, and which branch is taken next, based on structured status files rather than anything the model says freely. This means the model is used for interpreting and structuring information, not for choosing what happens next in the process. Every important step and exchange gets recorded into a file called skill_agent_context.json, which is formatted like a normal AI conversation log and can be replayed or inspected afterward. Alongside the core runtime, the repository includes a skill generator and a demo skill that processes CSV style data, each provided in both English and Chinese versions. The demo generates synthetic records, filters and profiles them for data quality, groups them by employee or region, asks a model to interpret the results, validates that interpretation, and produces a Markdown report. To run it, you need Python 3.11 or newer, the PyYAML library, and access to an OpenAI compatible chat completions endpoint, which can be a locally hosted small model server. After creating a virtual environment and installing the package, a command line tool lets you run a skill either from a natural language request or from a structured JSON input file, with support for setting an API token and choosing English or Chinese output. Each run writes its own folder of artifacts, separating files the skill itself produces from files the runtime itself manages. The project describes itself explicitly as an experimental runtime for workflow and trace validation, not a production system or a security sandbox.