Safe, reusable automation authored by agents.
TL;DR —
npm install -g skillscript-runtime && skillfile init && skillfile dashboard. See Quickstart.
What is Skillscript?
Skillscript came from asking: what would a Makefile look like if it built skills instead of binaries? The answer is a constrained language, inspired by Make, and a runtime that turns an agent's reasoning into persistent, inspectable automation. The agent writes the skill, you approve what it can do, and it runs the same way every time.
It is built for teams that want agents to create and run recurring workflows without giving them unrestricted shell access, arbitrary package installation, or direct control of production credentials.
An agent writes a skill. A human reviews and approves it. The runtime executes it through configured connectors, allowlists, and security policies.
npm install -g skillscript-runtime skillfile init skillfile dashboard
Then connect your agent to the MCP: http://localhost:7878/rpc and ask it to author a skill.
Why use it?
Agents usually re-derive routine tasks from scratch. That increases cost, latency, and behavioral drift.
Skillscript lets an agent crystallize a learned procedure into a named, reusable artifact that can be:
- executed repeatedly without re-planning the entire task
- inspected and versioned by humans
- validated before it is admitted
- limited to approved tools, files, commands, and credentials
- composed with other skills
Skillscript is orchestration-only. Computation stays inside tools and connectors; skills coordinate those capabilities through a small declarative grammar. This can meaningfully cut frontier-model token usage in recurring workflows: the reasoning cost is paid once when the skill is authored, and each run after that executes deterministically, with routine sub-tasks handed to cheaper local models.
Why not Python or Bash?
Python and Bash remain useful for implementation work. The risk is allowing agent-authored scripts to run unattended with unrestricted access to the host.
Skillscript narrows that execution surface:
- no arbitrary imports, package installation,
eval, or subprocess escape - connector-mediated access to external systems
- default-deny shell and filesystem allowlists
- static validation before execution
- optional operator signatures for effectful skills
- credentials held by the runtime rather than embedded in the skill
The goal is not to replace scripts. It is to place scripts and APIs behind capabilities the operator explicitly exposes.
There is also a scaling reason. Reviewing arbitrary code means auditing everything it could do, which takes a skilled reader. A skillscript puts its full effect surface on the page, so approval stays tractable even when agents author faster than anyone can read code, and the operator who knows what their systems should allow can approve on the declared effects rather than by re-reading logic.
A skill
A skill is a typed, declarative workflow with variables, operations, dependencies, and an output template.
# Skill: hello
# Status: Approved
# Description: Greet someone by name.
# Vars: WHO=world
Hello, ${WHO}!
That is a complete, runnable skill. The body is rendered as its output.
Skills can also call connectors, branch, loop, run other skills, respond to events, and execute on schedules:
# Skill: daily-disk-check
# Status: Approved
# Triggers: cron:"0 6 * * *"
# Autonomous: true
Snapshot written for ${NOW}.
snapshot:
shell(command="df -h --output=source,pcent,target") -> USAGE
file_write(
path="/var/log/skillscript/disk-${EVENT.fired_at_unix}.txt",
content="${USAGE}"
)
default: snapshot
The runtime will refuse the shell command and file write until the operator allowlists the binary and path.
How it works
- Author: An MCP-connected agent discovers the available tools, writes a skill, and lints it. In secured mode it arrives as
Draft, inert until you approve it. - Review: A human inspects and approves the skill. In secured mode, approval signs the approved content with an operator-held key.
- Run: The skill executes from the CLI, MCP, cron, an HTTP event, or another skill.
- Observe: The runtime records traces, outputs, failures, and blocked operations.
Skills can serve three roles:
| Kind | Purpose |
|---|---|
| Headless | Runs autonomously and sends output to a system or human |
| Augmenting | Prepares context for a frontier agent |
| Template | Gives an agent a reusable procedure to follow |
Quickstart
1. Install and start the runtime
npm install -g skillscript-runtime skillfile init skillfile dashboard --host 127.0.0.1 --port 7878
Open http://localhost:7878.
Use --host 0.0.0.0 only when another container or machine must reach the runtime, and protect exposed ingress appropriately.
2. Add the MCP server to your agent
{
"mcpServers": {
"skillscript": {
"type": "http",
"url": "http://localhost:7878/rpc"
}
}
}3. Ask the agent to build a skill
Author a skill that greets someone by name.
The agent writes the skill through MCP. Approve it in the dashboard or CLI:
skillfile approve hello skillfile execute hello
Connectors and security
Skills access external systems through configured connectors rather than direct credentials. Connectors can expose MCP tools, data stores, local models, agent delivery channels, or custom runtime capabilities.
Important operator controls:
| Setting | Default |
|---|---|
SKILLSCRIPT_SHELL_ALLOWLIST |
deny all binaries |
SKILLSCRIPT_FS_ALLOWLIST |
deny all paths |
SKILLSCRIPT_SECURED_MODE |
off |
SKILLSCRIPT_SECRET_<NAME> |
unset |
Secrets are resolved by the runtime and passed only to approved sinks. Skills cannot print or inspect their raw values.
See the configuration guide and connector reference.
Common commands
skillfile lint <skill> skillfile compile <skill> skillfile execute <skill> skillfile approve <skill> skillfile diagram <skill> skillfile fires <skill> skillfile replay <trace_id> skillfile health
Run skillfile <command> --help for options.
Documentation
- Language reference
- Configuration
- Adopter playbook
- Adopter agent guide
- Connector contracts
- Upgrading
- Examples
- Additional examples on the website
Status
Skillscript is pre-1.0. The core language and connector contracts are stabilizing; external adoption and distribution work are ongoing.
Contributing
Bug reports and feature requests are welcome through Issues. Open an Issue before proposing grammar changes so the design can be discussed first.
License
MIT. See LICENSE.