skillstate-kit

A portable, validated execution-state layer for long-running AI agents.

Maintain task progress, observations, artifacts and operation state outside conversational history. Use your existing coding agent through CLI/MCP and project integrations, or embed the same canonical engine in Python. Semantic generation from existing skills remains supported. No custom Python agent is required for host integration.

Python 3.11+ · MIT license · Alpha

Install

python -m pip install "skillstate-kit[mcp]"
skillstate init
skillstate doctor --mcp

Run setup in your project. Host detection installs the applicable project lifecycle and generator skills; unrelated instructions/configuration are preserved. After reloading discovery, use your agent normally. The integration guides it to inspect compatible runs, preserve completed work, record evidence and validate completion.

The base package also supports pip install skillstate-kit and skillstate init through CLI instructions. MCP is optional. The core requires no model account; your host supplies its model. skillstate demo is an explicitly scripted offline example.

Optional extras:

• mcp: a project-scoped STDIO MCP server and connection diagnostics.
• http: a stateless adapter for a configured JSON-compatible chat-completions endpoint.

Task lifecycle

The optional task profile provides task_start, task_checkpoint and task_complete over CLI/MCP. Milestones reference artifacts, completion time and resource fingerprints; repeated milestones require an explicit revalidation reason. Completion validates required steps, evidence integrity, blockers and freshness. Agent-reported evidence does not independently prove business truth. Existing semantic state schemas and run APIs remain supported.

skillstate hosts detect lists discovery evidence. skillstate init --host codex --mcp or --host claude-code --mcp selects a project integration. skillstate doctor codex checks that integration. skillstate disconnect codex reverses its owned setup while retaining state.

Execution-state optimization does not remove a host's native transcript. Token, latency and cost improvements must be measured independently; smaller application context is not proof of provider savings.

A real paired Codex coding trial passed 29 independent checks in both modes and preserved the integrated run across four fresh sessions. It used more tokens and wall time with SkillState on that small task. See the measurement report.

Use an existing skill

Run these commands in your target project. Replace skills/qa/SKILL.md with your existing skill file:

skillstate init --host codex --host claude-code --host antigravity --mcp
skillstate generate skills/qa/SKILL.md --name qa-state --install
skillstate validate qa-state
skillstate doctor --mcp

After your host discovers the installed generate-skill-state skill, ask it to generate state from an existing skill and install the result. Invoke the generated qa-state skill to run the procedure with checkpoints. Generating a definition does not execute the task.

generate preserves the source procedure and adds bounded progress fields. Domain-specific generation uses the active agent's proposal:

skillstate generate skills/qa/SKILL.md --prepare
skillstate generate skills/qa/SKILL.md --proposal proposal.json --source-hash HASH_FROM_PREPARE --install

The preparation response contains source text, its fingerprint and the proposal schema. The agent writes proposal.json; the library validates it and refuses stale source fingerprints. Structural validation is not proof that every business rule is correct.

You can also supply an explicitly configured endpoint with --base-url and --model. Terminal commands do not borrow your IDE's model credentials.

Claude Desktop Chat

Version 0.1.2 adds an explicit local connection, separate from Claude Code:

skillstate connect claude-desktop
skillstate doctor --mcp

Fully quit and reopen Claude Desktop, use Chat, and approve the tool calls you intend to allow. The installer preserves unrelated settings and uses a separate server name per project. Windows standalone/Microsoft Store and macOS paths are supported; --config PATH selects a custom location. If two Windows configs exist, choose explicitly. Disconnect with skillstate disconnect claude-desktop; run data remains intact.

Live acceptance evidence: Codex used eight real MCP calls to record a synthetic invoice review and hand it to Claude Desktop. After an initial permission/timeout interruption, Desktop resumed the same run, saved a second-review artifact and completed at revision 4. A separate process verified the stored state, both artifacts and the event history. This representative Codex-to-Claude Desktop Chat success does not establish universal desktop compatibility.

Python integration

This complete example uses a scripted model. Replace model and record with your own model and service functions:

import asyncio
from skillstate import Skill, SkillRuntime, SQLiteStore, Tool, ToolResult

skill = Skill(
    name="record-job",
    instructions="Record the job, then finish after its result is confirmed.",
    state_schema={
        "type": "object",
        "properties": {"recorded": {"type": "boolean"}},
        "required": ["recorded"],
        "additionalProperties": False,
    },
    initial_state={"recorded": False},
)

def model(context):
    if context["state"]["recorded"]:
        return {"patch": [], "action": None, "done": True}
    return {
        "patch": [{"op": "set", "path": "/recorded", "value": True}],
        "action": {"name": "record", "arguments": {}},
        "done": False,
    }

def record(arguments, operation_id):
    # For a real API, forward operation_id to its idempotency facility when
    # supported and inspect the actual response before reporting success.
    return ToolResult(True, {"recorded": True})

async def main():
    with SQLiteStore() as store:  # Pass a local file path for durable storage.
        store.create("job-001", skill, "worker")
        tool = Tool("record", "Record a job",
                    {"type": "object", "additionalProperties": False}, record)
        runtime = SkillRuntime(store, model, [tool],
                               completion_check=lambda state: state["recorded"])
        result = await runtime.run("job-001", "worker", max_steps=10)
        print(result["status"], result["state"])

asyncio.run(main())

For persistent storage, pass a database path to SQLiteStore. Reopen the same database and run ID to resume; creating a duplicate run is rejected.

Execution contract

• Explicit set/delete patches with JSON Pointer paths, inline JSON Schema and UTF-8 size limits.
• State and tool arguments validated before a managed tool executes.
• Persistent operation intent before tool execution; atomic state, result and event commit afterward.
• Failed tools retain the prior state. Exceptions, timeouts and ambiguous results block replay until reconciliation.
• Revision checks prevent competing clients from silently overwriting each other.
• Immutable skill definitions, source drift detection and sequential owner handoff.
• Large text artifacts kept outside the active context.

Native host skills provide state and checkpoints. They do not replace host conversation history or intercept every native tool. Use the managed Python runtime with a stateless model for history-free model inputs.

SQLite does not make external APIs transactional. Owner names coordinate local clients; they are not authentication. The library validates reported results but cannot independently prove external business truth. Keep local state private and test recovery behavior for your application.

Compatibility and documentation

Adapters generate project skill files and optional MCP configuration for Codex, Claude Code and Antigravity. They target documented integration surfaces. MCP protocol tests and configuration discovery do not certify every IDE version or live task.

The source distribution includes docs/cli.md, docs/architecture.md, docs/compatibility.md, docs/validation.md, docs/README_TR.md and runnable examples. Download the source archive from this package's files to read them offline. The development repository currently requires collaborator access.

Research

An independent implementation inspired by SKILL.state: Scalable Long-Horizon Agent Skills. Not affiliated with the paper's authors. The compiler, host adapters and operation journal are engineering extensions; no reproduction of the paper's benchmark scores or token savings is claimed.