SSP
EN ZH

Skill State Protocol

State that routes. Context that lasts.

A minimal, file based contract for skill orchestration. SSP keeps progress deterministic and makes handoffs between stages explicit.

Read the protocol Quickstart

Two file runtime contract

v0.1 draft
state.json Routing, phase, outputs, timestamps
context.json Facts, configs, results, artifacts
Read state Run stage Write context Update state

Intro

SSP defines a small, stable interface for multi stage workflows. State stays predictable, context stays durable, and every stage can read what came before it without guessing.

Design intent

Separate routing state from shared facts so teams can evolve stage logic without breaking the pipeline.

Why SSP

Skill workflows break when handoffs are implicit. SSP makes routing explicit and keeps shared facts in one durable place.

Portable handoff

Any orchestrator can resume with the same state root.

Traceable outputs

Every stage records artifacts for audit and replay.

Minimal overhead

Two files, JSON schemas, no server required.

Ecosystem impact

A shared state contract makes workflow data interoperable. At scale, this can unlock more reliable orchestration patterns and faster iteration across tools.

Quickstart

  1. Create a state root at .skill-state/.
  2. Add state.json and context.json.
  3. Update phase to route work.
  4. Write stage outputs into context.json.
  5. Validate with the JSON Schemas.

Core files

state.json

Routing state and stage outputs.

  • phase
  • current_skill
  • outputs.stage.status
  • timestamps

context.json

Facts, configs, and results shared across stages.

  • project brief
  • service configs
  • validation results
  • artifacts

Lifecycle

01

Read state

Orchestrator loads phase and outputs to decide next stage.

02

Execute stage

Stage reads context, performs work, writes new facts.

03

Update state

Record status, artifacts, and timestamps for auditability.

Propagation

SSP treats the state root as the portable unit of work. Copying state.json and context.json (and referenced artifacts) should be enough for another orchestrator to continue.

Portable handoff rules

  • Do not rely on hidden runtime state.
  • List required artifacts in outputs.*.files.
  • Keep handoffs deterministic and auditable.

SSP vs MCP / Spec-driven

SSP vs MCP

  • MCP defines tool capabilities and calling patterns.
  • SSP defines runtime state and handoff semantics.
  • They complement each other in real workflows.

SSP vs spec-driven tasks

  • Spec-driven focuses on task contracts and APIs.
  • SSP focuses on workflow continuity and outputs.
  • SSP stays minimal and profile-defined.

Protocol highlights

Required fields

state.json must include:

  • phase
  • created_at
  • last_updated
  • current_skill
  • outputs

Status values

Stage output status must be one of:

  • pending
  • in_progress
  • completed
  • blocked
  • failed
state.json template
{
  "protocol_version": "0.1",
  "phase": "idle",
  "created_at": null,
  "last_updated": null,
  "current_skill": null,
  "env": {
    "registry": ".skill-state/env.json",
    "local": ".skill-state/env.local.json"
  },
  "outputs": {
    "plan": {"status": "pending", "files": []},
    "build": {"status": "pending", "files": []},
    "verify": {"status": "pending", "last_check": null}
  }
}

Schemas

Use the JSON Schemas to validate SSP files and prevent drift.

State schema

schemas/state.schema.json

Context schema

schemas/context.schema.json

Profiles

Profiles describe stage names and expected context keys. The base protocol stays the same, only the profile varies.

Example profile (non-normative)

See profiles/three-stage in the repo for a concrete mapping.

  • trend2work: project brief and planning outputs
  • tech-dev: integrations and configuration
  • iterate-check: validation reports

Examples

Sample files live in the examples/ directory.

state.json

examples/state.json

context.json

examples/context.json

FAQ

Is SSP just two JSON files?

The files are the interface, but the protocol defines required fields, output tracking, and handoff guarantees. The simplicity is the point.

Does SSP replace MCP?

No. MCP defines tool integration. SSP defines workflow state and continuity. They work best together.

Can phases be arbitrary?

The protocol allows any string. Profiles or orchestrators can enforce allowed phases and transitions.

Why not store this in a database?

You can. SSP is about the contract, not the storage medium. File-based state is portable, versionable, and easy to diff.

Conformance

  • State root contains state.json and context.json.
  • state.json keeps required fields and output status.
  • context.json avoids secrets and stores only shared facts.
  • Validation uses schemas/ as the source of truth.

Security

Secrets stay out

Use env registries or secret managers, not SSP files.

PII control

Document retention rules if context contains user data.

v0.2 Extensions (Draft)

These are optional enhancements that build on the core protocol.

  • Phase policy and allowed transitions.
  • Propagation metadata for handoffs.
  • Provenance for outputs and actors.
  • Validation hooks and gating rules.
  • Profile registry and discovery.

Roadmap

  • Reference validators and tooling
  • Profile registry
  • Conformance tests