Skillscript: A Declarative, Sandboxed Language for Tool Orchestration

Skillscript is a lightweight, declarative language designed specifically for the creation of agentic workflows. Essentially, it is a language for agents to write themselves in.

🚀 Quick Start

To get started, run the following commands in your terminal: npm install -g skillscript-runtime $\rightarrow$ skillfile init $\rightarrow$ skillfile dashboard

---

🚩 The Problem: The Transience of AI Agents

Currently, AI agents suffer from a lack of persistence in their capabilities. An agent that performs a task today—such as summarizing a specific thread—will likely approach the same task tomorrow by reasoning from the ground up. It burns expensive frontier-model inference on a procedure that already has a known shape, a predictable output, and established failure modes.

This inefficiency manifests in three primary ways:

1. Financial Cost: Routine tasks are routed through the most expensive reasoning layers.
2. Latency: Every execution incurs the full "thought" time of the LLM.
3. Drift: Without a fixed template, the same task yields slightly different results every time.

Mathematically, the waste can be viewed as: $\text{Total Waste} = \sum (\text{Inference Cost} \times \text{Frequency of Routine Task})$

The core issue is that agents lack a substrate to record their learned behaviors. While most infrastructure focuses on memory (episodic recall or RAG), they answer "what the agent knows" rather than "what the agent can do" in a persistent, executable format.

---

🖼️ The Frame: Agents as Code

"Agents are code, and skillscript is the language they write themselves in."

In this context, "code" refers to named, typed, and composable artifacts that represent a specific capability. A skillscript skill is a declarative recipe—a small program consisting of a dependency Directed Acyclic Graph (DAG) of typed operations. An agent authors the skill once, and the runtime executes it repeatedly.

Unlike procedural code (e.g., TypeScript or Python), skillscript is orchestration-only. It focuses on composing calls to tools, models, and data stores via swappable connector contracts.

Example: A Basic Skill

# Skill: hello 
# Status: Approved 
# Description: The canonical first-run example.

Hello, {{ user_name }}! Welcome to Skillscript.

In this example, there is no boilerplate or emit() function. The runtime simply renders the body using the skill's variables and publishes the result. This scales from simple text to complex DAGs that handle classification, branching, and sub-agent orchestration.

---

❓ Why a New Language?

One might ask: Why not just let the agent write Python?

Python is powerful and Turing-complete, which is great for exploratory work. However, for autonomous, persistent automation (e.g., cron jobs or event triggers), Python's strengths become liabilities.

Comparison: Python vs. Skillscript

The Risks of Agent-Authored Python:

• Security: An agent might inadvertently write code that is dangerous to the host.
• Stability: Broken scripts shipped to production may fail silently at 3 AM.
• Integrity: Agents can install compromised packages via pip without human oversight.

Skillscript eliminates these risks by restricting the agent's ability to eval, subprocess, or import arbitrary code.

---

🛠️ Technical Overview

Core Components

• Connector Model: Standardized contracts for interacting with external tools.
• Configuration Knobs: Security settings to control the sandbox environment.
• CLI & MCP: A command-line interface and Model Context Protocol server surface for integration.

Project Status & Contribution

• Current Status: Pre-1.0
• License: MIT
• Contributing: See CONTRIBUTING.md in the repository.

Repository Structure:

• /src: Core runtime logic.
• /examples: Sample skills and workflows.
• /docs: Deep dive architecture documentation.
• ARCHITECTURE.md: Detailed system design.