Metadata-Version: 2.4
Name: skillstate-kit
Version: 0.2.0
Summary: Compile existing agent skills into portable, validated execution state.
Project-URL: Homepage, https://github.com/Atakan-Emre/skillstate-kit
Project-URL: Repository, https://github.com/Atakan-Emre/skillstate-kit
Project-URL: Documentation, https://github.com/Atakan-Emre/skillstate-kit/tree/main/docs
Project-URL: Issues, https://github.com/Atakan-Emre/skillstate-kit/issues
Author: Atakan Emre
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude,codex,mcp,skills,state
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: pathspec<1,>=0.12
Requires-Dist: pyyaml<7,>=6.0.2
Requires-Dist: tomlkit<1,>=0.13
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: httpx<1,>=0.28; extra == 'dev'
Requires-Dist: hypothesis<7,>=6.120; extra == 'dev'
Requires-Dist: mcp<2,>=1.20; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Provides-Extra: http
Requires-Dist: httpx<1,>=0.28; extra == 'http'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.20; extra == 'mcp'
Description-Content-Type: text/markdown

# 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

```bash
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](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/benchmarks/coding-agent.md).

## Use an existing skill

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

```bash
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:

```bash
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:

```console
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:

```python
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](https://arxiv.org/abs/2608.26263). 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.
