From Agent Skills to Controlled Enterprise Workflows.
skill2workflow compiles SKILL.md into workflows that can be validated,
published, paused for human approval, resumed, recovered and audited.
Current maturity is Self-hosted Beta: a self-hosted, single-tenant runtime for one team, with Python 3.9+ standard-library runtime code and SQLite production persistence. Workflow DSL remains the execution source of truth; LiteGraph is an editor and operational view. The runtime does not claim exactly-once execution, hosted multi-tenancy, built-in TLS or automatic reconciliation of unknown external side effects.
Documentation · Changelog · Security · Support · Governance · Contributing · Code of Conduct
The controlled loop is:
SKILL.md -> Skill IR -> Workflow DSL -> Immutable publication
Authenticated service -> Durable run -> Human decision -> Audit / recovery
From a source checkout, install and create a new private workspace:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
skill2workflow quickstart \
--root /tmp/skill2workflow-quickstart \
--port 8080Use a trusted parent and keep the workspace path stable during setup and failure cleanup. The bundled example is compiled, published into SQLite and stops at a human gate. It makes no external connector call. The command never overwrites an existing root and never prints the generated ingress secret.
Ordinary steps and text-only verification nodes record progress; they do not execute the described work or check results. A hard-gate declaration is also descriptive: use a human gate to pause for approval and an explicit connector for an automated action or check. A completed run alone does not prove that the described business work was done.
The JSON result contains run_id, state_dir and secret-free
operator_commands arrays. Inspect the waiting run before making an explicit
approve/reject decision. The installed controlled quickstart
shows the exact inspection, approval and service-start commands.
It also shows how to reject. Local inspection can display business input, so
protect its output; the remote service view is redacted.
To preview your own controlled Skill and non-secret business input, use another unused absolute root:
skill2workflow quickstart \
--root /tmp/skill2workflow-custom \
--skill /absolute/path/to/SKILL.md \
--input /absolute/path/to/input.json \
--port 8080 --dry-runThis preview creates no workspace, run or token. Remove --dry-run only after
reviewing the result. A custom Skill must reach a real human gate before any
non-manual connector on its initial success path; quickstart never inserts
approval into an uncontrolled process. Omit --input only when {} satisfies
the input contract and required mappings.
For executable result checks, declare HTTP JSON assertions. For API calls, declare HTTP actions and typed trigger inputs. Review endpoints, credential handles and response retention before approval.
Already have a reviewed wheel? Install it with python -m pip install /path/to/skill2workflow.whl
and use the same quickstart command above. See the complete guide
for the non-overwrite boundary, custom input and authenticated second trigger.
python3 scripts/demo_bootstrap.py --work-dir /tmp/skill2workflow-demoThis contributor demo automatically resumes its example gate and resets
its work directory by default. It is not the operator approval journey above.
Use --no-reset to keep existing files. See Contributing
for tests and examples for repeatable scenarios.
skill2workflow ui --port 4173Open the editor or the control-plane inspector. The loopback UI bundles its LiteGraph assets locally and needs no CDN.
Choose a local Skill and select Compile SKILL, inspect the draft and validate before publication. Compilation is not execution. The editor can check ephemeral, non-secret input, preserve newer drafts during imports and export allowlisted edits back through Workflow DSL validation. See authoring and installed UI. Live operational views require an explicit service origin and protected token file; the token is not sent to the browser.
The graph is a review/editing surface, not a second execution authority.
Inspect exported snapshots, or connect the installed UI to one authenticated service for bounded live inspection and explicit operator actions.
Skills describe how an agent should work. Operational workflows also need enforced ordering, durable state, approval, retries, versioning and an audit trail. This project makes those controls explicit and inspectable.
Compilation is conservative. It does not turn arbitrary prose into trusted business automation or execute embedded shell/code examples. Review inferred manual steps and use explicit supported declarations for approvals, HTTP calls, input contracts and versions.
| Task | Supported path |
|---|---|
| Write and review a process | Skill input contract, authoring, examples |
| Test business input without running | Workflow preflight, including the canonical 1 MiB input limit |
| Publish an edited Skill as a new immutable version | Skill workflow versions, workflow releases |
| Share reviewed local artifacts | Workflow bundles with verification and separate execution consent |
| Deploy one team instance | Secure service bootstrap, go-live checklist, Docker, systemd |
| Approve, trigger and schedule | Human approval, triggers, recurring scheduling |
| Diagnose and recover | Service Doctor, run detail, backup/restore, interrupted recovery |
| Extend integrations safely | Connectors, credentials, runtime policy |
Use SQLite for the self-hosted production boundary. JSON/JSONL remain available for local examples and evaluation. Business input is durable run data, not a credential store; secrets belong behind credential handles, not in Skills, Workflow DSL or shared fixtures.
Cancellation is cooperative and cannot undo an in-flight external effect. Unknown effects require operator reconciliation, not automatic replay. Public ingress needs separately managed TLS and deployment review.
For a task-oriented route through all features, use the documentation guide; the complete guide reference covers individual contracts, command boundaries and evidence.
The approved five layers are:
- Skill Ingestion / Parser
- DSL Compiler / Validator
- LiteGraph Editor
- Durable Executor
- Enterprise Control Plane
Published workflow versions are immutable. Run state, registry metadata and audit evidence use JSON/JSONL or SQLite; the graph and read-only reports do not override Workflow DSL. See the DSL contract and compatibility policy.
src/skill2workflow/ Python runtime and CLI
web/ Packaged editor and control-plane inspector
examples/ Skills, workflows, connector fixtures and observability
schemas/ Versioned JSON contracts
tests/ Python and editor behavior tests
scripts/ Contributor and release qualification tools
docs/ Task guides, contracts, specs and delivery evidence
CONTRIBUTING.md Setup, tests and contribution workflow
ROADMAP.md Readiness gates and delivery history
Current maturity: Self-hosted Beta. Delivery Loops 1-285 are complete.
Production Baseline remains directional; passing an individual drill does not
promote maturity. Loop 40 completed a paid assisted Pilot under one scoped
Lark/Feishu create_task boundary, not general live SaaS readiness.
See the evidence, pilot boundary
and ROADMAP.md for current decisions and detailed history.
For changes, start with Contributing. For packaged compatibility and release evidence, see stability and the release process.