Metadata-Version: 2.4
Name: skillstate-kit
Version: 0.2.1
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<10,>=9.0.3; 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

**Portable execution state for AI agents.**

Keep task progress, observations, evidence and operation outcomes outside conversational history. Use the same Python engine through the SDK, CLI or MCP, with project integrations for Codex and Claude.

[PyPI](https://pypi.org/project/skillstate-kit/) · [Documentation](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/integrations.md) · [Research alignment](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/paper-alignment.md) · [Validation](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/validation.md)

## Quick start

Requires Python 3.11 or newer. Run inside the project you want to integrate:

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

Restart or reload your agent's project discovery, then give it a normal task:

> Implement duration parsing and verify it with regression tests.

Installed instructions guide the agent to find the intended run, continue from current state, record evidence and validate completion. Host support and instruction-following remain necessary. No custom Python agent is required for this integration.

The base `pip install skillstate-kit` also supports `skillstate init` using the CLI. MCP is an optional extra; `http` adds a stateless JSON model adapter.

## Choose the state model

| Requirement | Interface |
|---|---|
| Track a multi-step coding task | Built-in task profile with evidence-backed milestones |
| Represent domain facts and procedural rules | Generate a task-specific semantic skill schema |
| Control every model input and registered tool call | Python `SkillRuntime` with a stateless model callback |

The task profile records the goal, active/completed/remaining steps, blockers and artifact references. It does not replace a domain model for inventory, invoices or other business rules.

### Use an existing skill

```bash
skillstate generate skills/qa/SKILL.md --name qa-state --install
skillstate validate qa-state
```

Replace the source path with your existing file. Direct generation preserves instructions and adds tracking state. For domain-specific fields, use the installed `generate-skill-state` skill or the source-bound `--prepare` / `--proposal` workflow. Generated proposals undergo structural and source-integrity checks; generation does not execute or certify the task.

For Python test tracking without an existing skill file:

```bash
skillstate generate . --profile python-tests --name tests-state --install
```

See the [generation and CLI reference](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/cli.md).

## Task lifecycle

```text
Find intended run → Read current state → Execute active work
                         ↑                       ↓
                    Continue ← Record verified milestone
                                      ↓
                           Validate and complete
```

- `task_start` creates an ordered plan or resumes an identical intended task.
- `task_checkpoint` records artifact-backed milestones and resource fingerprints.
- Repeating a completed milestone requires an explicit revalidation reason.
- `task_complete` checks required steps, evidence integrity, freshness and blockers.
- Generic task updates can change blockers; they cannot replace milestone progress.
- Pending or uncertain operations require reconciliation before further work.

Inspect progress with `skillstate run find` and `skillstate run context RUN_ID`.
Use `skillstate run events RUN_ID` for audit history. An intentionally new task
needs a new run ID; resuming an existing task never requires resetting it.

Evidence validates what was recorded and whether referenced resources changed.
Applications must still verify business outcomes. Native host tools are not
universally intercepted or sandboxed by this library.

## Host integrations

| Host | Project setup |
|---|---|
| Codex | `skillstate init --host codex --mcp` |
| Claude Code | `skillstate init --host claude-code --mcp` |
| Claude Desktop Chat | `skillstate connect claude-desktop` |
| Antigravity | `skillstate init --host antigravity --mcp` |

`skillstate hosts detect` reports discovery evidence. `skillstate doctor codex`
checks a selected adapter. Claude Desktop uses a separate application-level
connection and requires a full restart. Keep machine-specific MCP configuration
local. Detection or a healthy local server does not establish live host acceptance.

Installation preserves unrelated configuration and managed instruction blocks.
`skillstate disconnect HOST` removes owned integration settings while retaining
state. [Setup, thin plugins and host limitations](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/integrations.md).

## Python integration

This runnable example uses a **scripted model and a simulated tool**. It requires
no credentials. Replace the callbacks with your application integrations:

```python
import asyncio

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

async def main():
    skill = Skill(
        "record-job",
        "Record the job; finish after its result is confirmed.",
        {
            "type": "object",
            "properties": {"recorded": {"type": "boolean"}},
            "required": ["recorded"],
            "additionalProperties": False,
        },
        {"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):
        return ToolResult(True, {"recorded": True, "operation_id": operation_id})

    tool = Tool("record", "Record a job", {"type": "object", "additionalProperties": False}, record)
    with SQLiteStore() as store:
        store.create("example", skill, "worker", {"job": "example"})
        runtime = SkillRuntime(store, model, [tool], completion_check=lambda s: s["recorded"])
        result = await runtime.run("example", "worker")
        print(result["status"], result["state"])

if __name__ == "__main__":
    asyncio.run(main())
```

Expected output:

```text
completed {'recorded': True}
```

Replace `model(context)` with your synchronous or asynchronous model callback, and `record` with a real tool that checks its result. Forward `operation_id` to the external service's idempotency facility when supported.

The example uses an in-memory store for easy reruns. Use `SQLiteStore("jobs.sqlite3")` for durable storage. Create each run once; resume by reopening that database and calling `runtime.run` with the existing run ID and owner. See the [runnable source](https://github.com/Atakan-Emre/skillstate-kit/blob/main/examples/managed_runtime.py) and [runtime contract](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/architecture.md).

### Model decision contract

```json
{
  "patch": [{"op": "set", "path": "/recorded", "value": true}],
  "action": {"name": "record", "arguments": {}},
  "done": false
}
```

Finish with `{"patch": [], "action": null, "done": true}`. State updates use explicit `set`/`delete` operations and JSON Pointer paths. Setting `null` does not delete a key. No reasoning-trace field is accepted.


## Execution guarantees and boundaries

| Concern | Contract |
|---|---|
| Invalid decisions | Validate state patches and registered tool arguments before effects |
| Concurrent writes | Reject stale revisions and wrong owners |
| Failed or uncertain tools | Preserve the checkpoint; require explicit reconciliation when uncertain |
| Completed task progress | Use evidence-backed lifecycle calls and explicit revalidation |
| Application context | Enforce byte budgets; keep audit history outside ordinary model context |
| Persistence | Shared SQLite store, immutable skill definitions and integrity-checked artifacts |

The managed runtime supplies current instructions, state and latest observation
plus fixed tool/schema contracts. A stateless model callback is required to avoid
reintroducing history. Native Codex/Claude integrations retain the host's own
conversation behavior and do not guarantee lower provider token usage.

Owner IDs coordinate trusted local clients; they are not authentication. Python
callbacks run with application permissions. SQLite cannot atomically roll back
remote side effects. [Security boundaries](https://github.com/Atakan-Emre/skillstate-kit/blob/main/SECURITY.md) · [Execution contract](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/execution-state.md).

## Validation and performance

The test suite covers schema rejection, persistence, concurrent revisions,
uncertain operations, artifact integrity, installer preservation and real MCP
transport. See [release validation](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/validation.md) for exact tested versions.

Reproducible experiments are documented separately:

- [External smolagents correctness and forced-process continuation](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/smolagents-acceptance.md).
- [Paired Codex coding experiment: correctness, repeated work, actual tokens and latency](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/benchmarks/coding-agent.md).
- [Host acceptance and scope](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/host-acceptance.md).

The recorded small coding trial incurred additional token and latency overhead.
Performance depends on workload and host behavior; universal savings are not claimed.

## Research

Independent implementation inspired by [SKILL.state: Scalable Long-Horizon Agent Skills](https://arxiv.org/abs/2608.26263), by Sanket Badhe, Priyanka Tiwari and Jonghyun Chung. No affiliation or endorsement is implied.

The [research alignment document](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/paper-alignment.md) distinguishes the managed runtime from native-host integration, maps implemented contracts to tests and records intentional differences. Paper benchmark results are not claimed for this package.

## Development

```bash
python -m pip install uv
uv sync --locked --extra dev
uv run ruff check src tests examples scripts
uv run ruff format --check src tests examples scripts
uv run pytest --cov=skillstate --cov-fail-under=85
uv run python -m build
uv run twine check dist/*
```

Python/OS tests and clean-package checks run in CI. The package is alpha.
[MIT license](https://github.com/Atakan-Emre/skillstate-kit/blob/main/LICENSE) · [Contributing](https://github.com/Atakan-Emre/skillstate-kit/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/Atakan-Emre/skillstate-kit/blob/main/CHANGELOG.md) · [Security reporting](https://github.com/Atakan-Emre/skillstate-kit/blob/main/SECURITY.md).
