Example of a leaner README for skillscript

Safe, reusable automation authored by agents.

What is Skillscript?

Skillscript is a constrained language and runtime for turning agent reasoning into persistent, inspectable automation.

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 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.

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.

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 and writes a skill as Draft.
Review: A human inspects, lints, and approves the skill. Secured mode 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 a draft 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

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.

thedatadavis/lean_skillscript_readme.md

Select an option

No results found