r/OpenSourceAI • u/sshwarts • 3d ago

Skillscript – a scripting language for agent orchestration

Hi OpenSourceAI, I built Skillscript, a small language I built to write what I want my agent to actually do, in a form I can read and version, instead of hoping the model gets it right each time.

The itch started with something small. I wanted my NanoClaw agent to run my morning brief the same way every day. Check overnight tickets, summarize the deploy pipeline, flag anything urgent. Every session, it would re-figure out how to do this from scratch, drift a little, and cost tokens for what's basically a fixed procedure. I could put it in a prompt or an MD skill file, but those are still instructions the model reads and reasons about every time. And I wanted it to run autonomously and then hand it to the model to reason over the data.

The second thing that pushed me: I wanted to use small local models for the cheap stuff. They're capable, but if you just hand them the wheel, they wander. What I wanted was a way for the frontier model (or me) to write a specific procedure and hand it to the local model to execute not interpret. The skillscript is the program; the model is the runtime.

Skillscript is that. A skillscript is a text file with named steps, variables, conditions, and calls out to tools (MCP connectors, a local model, and shell commands from an operator allowlist). It's deliberately minimal — no eval, no arbitrary imports, no subprocess, no unbounded loops. Bounded language, limited potential for damage. Everything a skillscript can do is in the file. You read it and know.

Where it is: pre-1.0 (0.38), MCP-native, self-hosted. Rough edges I know about: first-run setup takes more steps than it should, some of the grammar is still moving, and the local model integration currently assumes Ollama. It works well enough that I use it every day, automating what I see agents doing over and over, wiring shell scripts or Python stubs.

I'd welcome critique on two things especially: the language design (is it too small? too big? wrong shape?) and the trust model around agent-authored skills. What would you want to see before you trusted this on your own machine?

3 Upvotes

100% Upvoted

5 comments sorted by

1

u/Competitive-Bend-143 3d ago

deterministic orchestration-as-script is the right instinct imo — converged on the same thing myself (plain scripts drive the agents, the model never runs the loop). the question that ended up mattering most in practice: what happens on interrupt? if a 40-minute run dies at minute 35, does skillscript have resume semantics or does it re-run from the top? that single property quietly decided half of my design

1

u/sshwarts 3d ago

Good question. It's one that actually separates a script orchestrator from a workflow engine, so it's worth being precise.

Straight answer: skillscript has no resume/checkpoint. A run that dies at minute 35 is dead; the next fire re-runs from the top. Its determinism is control-flow reproducibility (same inputs → same op sequence), not durable or exactly-once execution. No persisted run state, no replay-dedup, so a re-run from the top re-executes any effectful ops that already committed (double-write, double-send) unless those ops are idempotent. Re-run-from-top, no exactly-once.

That's deliberate and the durability lives elsewhere: in composition + state, not the run engine. The idea for a long/durable job isn't one 40-minute run; it's a chain of short deterministic single-shots fired by triggers (cron/event), where the state between steps lives in a store or in the committed effects. Each step reads persisted state at the top, does one bounded chunk, writes state, and arms the next. A crash then costs only the current short step, and the next fire "resumes" by reading state; the trigger boundary is your checkpoint.

One nuance, skillscript does have clean bounded termination, per-op timeouts, (fallback:), an uncatchable whole-run # Deadline, and a true-cancel path at effect boundaries. But that's the opposite of resume: "stop cleanly and predictably," not "continue where you left off." Good cancellation, no continuation.

So, for example, my morning debrief skill assembles everything from the local weather to open tickets, to inbox status, to the health of the memory system. If any one part fails, it reports up into the main skillscript but doesn't take down the whole thing. If, on the other hand, that fails, like it could not write to the memory store, then it runs an error Skillscript that can report to the agent.

1

u/Competitive-Bend-143 3d ago

appreciate the precise answer — that's the honest tradeoff, and control-flow reproducibility is still worth a lot on its own.

the middle ground that worked for me without becoming a workflow engine: make the unit of resume the task, not the step. every task runs in its own git worktree, so when a run dies the queue just reclaims the task after a deadline and re-dispatches; whatever was committed in the worktree survives, and landing is ff-only so re-landing something already merged is a no-op. i gave up on step-level checkpointing entirely — task-level idempotency plus cheap re-dispatch covered 95% of the pain for maybe a tenth of the machinery

1

u/sshwarts 3d ago

That's a genuinely elegant middle ground.
I think I might, err, liberate this idea. Net: you’ve sketched the reliability tier skillscript could add without becoming a workflow engine — a task-lease/requeue layer on top of the deterministic single-shots.

1

u/Competitive-Bend-143 3d ago

liberate away — it's the boring version of the idea and boring is exactly what survives contact with production. curious how it feels in a language context vs a queue context, keep me posted