developer docs · orchestration

Multi-Agent Orchestration with State Management.

SkiPaks are not just bundles. In sequential and sequential_pipe modes, each skill's output threads into the next skill's input via a shared session state — hosted, secured, and auditable inside the skil.ski execution environment.

why this matters

The LangChain / CrewAI gap

LangChain and CrewAI require you to host your own orchestration infra: state stores, retry logic, per-agent secrets, and audit trails. Teams spend more time wiring the pipeline than building the capabilities inside it.

skil.ski flips this. Each Skilski is a verified, independently deployable capability unit. The SkiRun engine threads them together — state lives in a RLS-protected session row with a 24-hour TTL and a full audit trail. You get multi-agent pipelines without running a single orchestration server.

"A specialized research agent utilizing a skil.ski-hosted Exa web search skill can seamlessly hand off its structured, extracted data to a separate financial modeling agent running a localized Monte Carlo simulation skill — all securely managed within the skil.ski execution environment."

skirun modes

Three execution modes

paralleldefault

All skills run simultaneously.

Promise.all fan-out. Results are keyed by slug in the final state. Ideal when skills are independent — analytics dashboard, audit sweep, broad research.

Latency = slowest skill

sequentialordered

Skills run one after another.

Each skill receives the original caller input. Order matters for dependency chains where step N must finish before step N+1 starts — but output is not piped.

Latency = sum of all steps

sequential_pipestateful

Output of step N becomes input of step N+1.

The previous skill's text response is forwarded as `context` to the next skill. This is the multi-agent handoff mode — structured extraction feeding a modeling skill.

Latency = sum of all steps

session state shape

What the state JSON looks like

Each step appends its result under its own slug key. The _errors array records best-effort failures without aborting the run. The _input key preserves the original caller payload for traceability.

final_state shape (sequential_pipe example)

{
  "_input": { "context": "<original caller input>" },

  // Each skill result is keyed by its slug:
  "receipt-to-ledger": {
    "text": "# Receipt to Ledger\n...",
    "slug": "receipt-to-ledger",
    "tier": "elite",
    "display_name": "Receipt to Ledger"
  },

  // The next skill in sequential_pipe received the above text as its context:
  "bank-reconciliation-matcher": {
    "text": "# Bank Reconciliation Matcher\n...",
    "slug": "bank-reconciliation-matcher"
  },

  // Failed steps are best-effort — run continues, error recorded here:
  "_errors": [
    { "slug": "some-skill", "step": 3, "error": "Skilski not in catalog" }
  ]
}

api reference

Run a pak

POST /api/orchestration/run — request

POST https://skill.ski/api/orchestration/run
Authorization: Bearer <session-cookie>   (or Supabase JWT)
Content-Type: application/json

{
  "pak_slug": "elite_regtech_surge",
  "input": {
    "context": "ACME Corp — BSA/AML review Q1 2026. Jurisdiction: US + EU."
  }
}

response

{
  "session_id": "a3f8c1d2-...",
  "status": "complete",
  "final_state": {
    "_input": {
      "context": "ACME Corp — BSA/AML review Q1 2026. Jurisdiction: US + EU."
    },
    "accounting-client-onboarding": {
      "text": "# Accounting Client Onboarding\n...",
      "slug": "accounting-client-onboarding",
      "tier": "elite"
    },
    "tax-prep-document-checklist": {
      "text": "# Tax Prep Document Checklist\n...",
      "slug": "tax-prep-document-checklist",
      "tier": "elite"
    },
    "_errors": []
  },
  "step_count": 10,
  "latency_ms": 312
}

Inspect a session

Sessions are RLS-protected — you can only read sessions you own. Use the session id returned from the run endpoint to resume inspection or verify step completion.

GET /api/orchestration/sessions/:id — response

GET https://skill.ski/api/orchestration/sessions/a3f8c1d2-...

{
  "id": "a3f8c1d2-...",
  "user_id": "uuid",
  "pak_slug": "elite_regtech_surge",
  "state": { ... },
  "step_index": 10,
  "status": "complete",
  "error": null,
  "started_at": "2026-05-04T14:00:00Z",
  "ended_at": "2026-05-04T14:00:00.312Z",
  "ttl_at": "2026-05-05T14:00:00Z"
}

security

RLS-protected sessions

Each session row is protected by Postgres Row Level Security. You can only read or write your own sessions.

Prompt Shield on inputs

All skill inputs pass through the same injection scanner as direct MCP calls — jailbreak, exfiltration, and role-override patterns are blocked before execution.

24-hour TTL

Session rows expire after 24 hours. State is not persisted indefinitely — use the session_id within the window to inspect or replay.

Best-effort failure isolation

A failed skill step is recorded in _errors but never crashes the run. Partial results are always returned so the calling agent can decide how to proceed.

roadmap

This is the foundation layer — session state + sequential execution. Visual DAG builder, conditional branching, and cross-session state replay are planned follow-ups. The data model is designed to support DAG shapes without schema changes.

Back to developer docs →

The LangChain / CrewAI gap

Three execution modes

paralleldefault

All skills run simultaneously.

Promise.all fan-out. Results are keyed by slug in the final state. Ideal when skills are independent — analytics dashboard, audit sweep, broad research.

Latency = slowest skill

sequentialordered

Skills run one after another.

Each skill receives the original caller input. Order matters for dependency chains where step N must finish before step N+1 starts — but output is not piped.

Latency = sum of all steps

sequential_pipestateful

Output of step N becomes input of step N+1.

The previous skill's text response is forwarded as `context` to the next skill. This is the multi-agent handoff mode — structured extraction feeding a modeling skill.

Latency = sum of all steps

What the state JSON looks like

final_state shape (sequential_pipe example)

{
  "_input": { "context": "<original caller input>" },

  // Each skill result is keyed by its slug:
  "receipt-to-ledger": {
    "text": "# Receipt to Ledger\n...",
    "slug": "receipt-to-ledger",
    "tier": "elite",
    "display_name": "Receipt to Ledger"
  },

  // The next skill in sequential_pipe received the above text as its context:
  "bank-reconciliation-matcher": {
    "text": "# Bank Reconciliation Matcher\n...",
    "slug": "bank-reconciliation-matcher"
  },

  // Failed steps are best-effort — run continues, error recorded here:
  "_errors": [
    { "slug": "some-skill", "step": 3, "error": "Skilski not in catalog" }
  ]
}

Run a pak

POST /api/orchestration/run — request

POST https://skill.ski/api/orchestration/run
Authorization: Bearer <session-cookie>   (or Supabase JWT)
Content-Type: application/json

{
  "pak_slug": "elite_regtech_surge",
  "input": {
    "context": "ACME Corp — BSA/AML review Q1 2026. Jurisdiction: US + EU."
  }
}

response

{
  "session_id": "a3f8c1d2-...",
  "status": "complete",
  "final_state": {
    "_input": {
      "context": "ACME Corp — BSA/AML review Q1 2026. Jurisdiction: US + EU."
    },
    "accounting-client-onboarding": {
      "text": "# Accounting Client Onboarding\n...",
      "slug": "accounting-client-onboarding",
      "tier": "elite"
    },
    "tax-prep-document-checklist": {
      "text": "# Tax Prep Document Checklist\n...",
      "slug": "tax-prep-document-checklist",
      "tier": "elite"
    },
    "_errors": []
  },
  "step_count": 10,
  "latency_ms": 312
}

Inspect a session

Sessions are RLS-protected — you can only read sessions you own. Use the session id returned from the run endpoint to resume inspection or verify step completion.

GET /api/orchestration/sessions/:id — response

GET https://skill.ski/api/orchestration/sessions/a3f8c1d2-...

{
  "id": "a3f8c1d2-...",
  "user_id": "uuid",
  "pak_slug": "elite_regtech_surge",
  "state": { ... },
  "step_index": 10,
  "status": "complete",
  "error": null,
  "started_at": "2026-05-04T14:00:00Z",
  "ended_at": "2026-05-04T14:00:00.312Z",
  "ttl_at": "2026-05-05T14:00:00Z"
}