skillstate-kit 0.1.1__tar.gz

skillstate_kit-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+.venv-*/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+htmlcov/
+.skillstate/local/
+.env
+.env.*
+research/skill-state-minimal/
+research/probe_results.json
+*.sqlite3*
+.test-workspaces/
+.artifacts/

skillstate_kit-0.1.1/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.1 — public distribution
+
+- Self-contained PyPI package description with installation and SDK examples.
+- GitHub OIDC publishing workflow: full test matrix, clean installation, optional TestPyPI rehearsal, PyPI and downloaded package verification.
+- Verify registry file hashes against the tested artifacts before installation.
+- No changes to the runtime or storage contract from 0.1.0.
+
+## 0.1.0 — initial alpha
+
+- Source-preserving SKILL.md conversion and Python test tracking profile.
+- Source-bound semantic proposal preparation/validation and optional stateless JSON model adapter.
+- Immutable skill definitions and source drift detection.
+- SQLite revisions, ownership handoff, operation intents and explicit reconciliation.
+- Managed async runtime with bounded context and tool argument validation.
+- Project-scoped Codex, Claude Code and Antigravity skill/MCP installers.
+- STDIO MCP server, protocol smoke test, CLI and text artifact store.
+- Offline examples, cross-platform CI and package checks.
+
+Not included: native transcript replacement, arbitrary code rewriting, live certification of every host version, distributed multi-tenant storage, automatic external-effect rollback or reproduced paper benchmarks.

skillstate_kit-0.1.1/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "Cite this repository and the SKILL.state paper that inspired its explicit-state execution pattern."
+title: "skillstate-kit"
+type: software
+version: 0.1.1
+license: MIT
+authors:
+  - name: "Atakan Emre"
+repository-code: "https://github.com/Atakan-Emre/skillstate-kit"
+references:
+  - type: article
+    title: "SKILL.state: Scalable Long-Horizon Agent Skills"
+    authors:
+      - family-names: Badhe
+        given-names: Sanket
+      - family-names: Tiwari
+        given-names: Priyanka
+      - family-names: Chung
+        given-names: Jonghyun
+    year: 2026
+    url: "https://arxiv.org/abs/2608.26263"

skillstate_kit-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Keep public contracts small, explicit and testable. New behavior should include a realistic failure case as well as a successful example. Do not add compatibility or benchmark claims that have not been measured.
+
+## Setup
+
+```bash
+python -m pip install uv
+uv sync --locked --extra dev
+```
+
+Run `uv run ruff check src tests examples`, `uv run ruff format --check src tests examples`, and `uv run pytest --cov=skillstate --cov-fail-under=85`. For packaging changes, also run `uv run python -m build` and `uv run twine check dist/*`.
+
+## Invariants
+
+- Validate candidate state before committing it.
+- Reserve external operations before execution; never retry uncertain effects automatically.
+- Keep SQLite transactions outside model/tool calls.
+- Preserve the original observation during rejected-decision retries.
+- Keep definitions immutable for existing runs.
+- Preserve user-authored source and host configuration.
+- Distinguish agent-reported evidence from observed tool results and business truth.
+- Keep audit records outside context and enforce explicit budgets.
+
+Describe the concrete problem, resulting behavior and validation in changes. Document protocol/schema migrations. Examples should run without credentials unless labeled otherwise. Keep optional integrations optional.
+
+For host integrations, distinguish file generation, configuration validation, live MCP transport, live host discovery and actual agent behavior. Passing one level does not prove the others.
+
+Do not commit credentials, real task data, machine-specific interpreter paths or research checkouts. Report security concerns through SECURITY.md.

skillstate_kit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Emre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillstate_kit-0.1.1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: skillstate-kit
+Version: 0.1.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<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
+
+**Portable, validated execution state for agent skills.**
+
+Convert an existing `SKILL.md` into a state-backed skill, retain durable checkpoints, and integrate the same execution engine into a Python application.
+
+Python 3.11+ · MIT license · Initial alpha
+
+## Install
+
+```bash
+python -m pip install "skillstate-kit[mcp,http]"
+skillstate demo
+```
+
+The core package requires no model account. The demo uses an explicitly scripted model and local tools; it is not a benchmark of real-model performance.
+
+Optional extras:
+
+- `mcp`: a project-scoped STDIO MCP server and connection diagnostics.
+- `http`: a stateless adapter for a configured JSON-compatible chat-completions endpoint.
+
+## 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.
+
+## 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.

skillstate_kit-0.1.1/README.md

@@ -0,0 +1,167 @@
+# skillstate-kit
+
+**Portable, validated execution state for agent skills.**
+
+Turn an existing `SKILL.md` into a state-backed skill, use it from Codex, Claude Code or Antigravity, and resume work from a durable checkpoint. Embed the same runtime in Python when you need to control every model input and tool operation.
+
+[![CI](https://github.com/Atakan-Emre/skillstate-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Atakan-Emre/skillstate-kit/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**Release status:** `0.1.1` is an initial alpha. The development repository is private; public package installation uses PyPI. Tested local adapters are not live certification of every host application.
+
+[Türkçe başlangıç](docs/README_TR.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Compatibility](docs/compatibility.md) · [Validation](docs/validation.md)
+
+## What you get
+
+- **Source-preserving conversion.** Generate bounded tracking state without changing the original procedure.
+- **Semantic generation.** Use your coding agent or a configured JSON-capable model endpoint to propose domain-specific state. Validate proposals against source fingerprints before applying them.
+- **Durable state.** SQLite transactions, revision checks, ownership handoff and a persistent operation journal.
+- **Controlled execution.** Validate state and tool arguments, retain observations during retries, and stop ambiguous operations from being replayed automatically.
+- **Three host adapters.** Project-scoped skills and optional STDIO MCP configuration for Codex, Claude Code and Antigravity.
+- **A Python SDK.** Bring your own model and tool functions. The core package requires no API key.
+
+## Quick start
+
+```bash
+python -m pip install "skillstate-kit[mcp,http]"
+skillstate demo
+```
+
+Then, inside your target project (replace `skills/qa/SKILL.md` with your skill):
+
+```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 installing the package, run `init` and `generate` in your target project. `--project PATH` can also be placed **before** a subcommand. Generated MCP configurations use this machine's Python/project paths; keep them local. See [installation and compatibility](docs/compatibility.md).
+
+After the host discovers `generate-skill-state`, ask:
+
+> Generate skill state from my existing QA skill and install it in this project.
+
+The generator skill can prepare a source inventory, propose domain-specific state, then submit the proposal for deterministic validation. A standalone terminal process cannot silently borrow the host's model session or subscription.
+
+### Try it without a model account
+
+```bash
+skillstate demo
+```
+
+The demo explicitly uses a **scripted model** and local tools. It completes five operations and reports prompt sizes in UTF-8 **bytes**, not tokens. It is an executable example, not a reproduction of the paper's benchmarks.
+
+## Two execution modes
+
+| Mode | Model and tools run in | What the package controls |
+|---|---|---|
+| Native skill | Your coding agent | Validated state, checkpoints, explicit operation records, bounded returned context |
+| Managed runtime | Your Python application | Model context, decision validation, registered tools, retries and operation outcomes |
+
+Native skills do **not** replace the host's conversation history or intercept every native tool. For the paper's history-free model-input structure, use the managed runtime with a stateless model adapter. Instructions, state, tool schemas and observations must fit their configured budgets.
+
+## Python integration
+
+```python
+from skillstate import Skill, SkillRuntime, SQLiteStore, Tool, ToolResult
+
+skill = Skill(
+    name="record-job",
+    instructions="Record the requested job. Finish after its result is confirmed.",
+    state_schema={
+        "type": "object",
+        "properties": {"recorded": {"type": "boolean"}},
+        "required": ["recorded"],
+        "additionalProperties": False,
+    },
+    initial_state={"recorded": False},
+)
+
+def record(arguments, operation_id):
+    # Replace with your service call. Forward operation_id to its idempotency
+    # facility if supported, and inspect the actual result before success.
+    return ToolResult(True, {"recorded": True})
+
+tool = Tool("record", "Record a job",
+            {"type": "object", "additionalProperties": False}, record)
+
+async def run(model):
+    with SQLiteStore("jobs.sqlite3") as store:
+        store.create("job-001", skill, "worker", {"job": "example"})
+        runtime = SkillRuntime(store, model, [tool],
+                              completion_check=lambda s: s["recorded"] is True)
+        return await runtime.run("job-001", "worker", max_steps=10)
+```
+
+Pass your synchronous or asynchronous model callback to `run`. See [the complete runnable example](examples/managed_runtime.py). A repeated `create` rejects an existing run; resume by opening the same database and calling `runtime.run` on its existing ID.
+
+### Decision contract
+
+```json
+{
+  "patch": [{"op": "set", "path": "/recorded", "value": true}],
+  "action": {"name": "record", "arguments": {}},
+  "done": false
+}
+```
+
+Use `{"patch": [], "action": null, "done": true}` to finish. Explicit `set`/`delete` operations use JSON Pointer paths. Setting `null` does not delete a key. No reasoning-trace field is accepted.
+
+## How generation works
+
+```mermaid
+flowchart LR
+    Source[Existing skill or Python project] --> Scan[Bounded source inventory]
+    Scan --> IR[Tracking profile or semantic proposal]
+    IR --> Validate[Schema and source validation]
+    Validate --> Bundle[Immutable skill bundle]
+    Bundle --> Hosts[Codex / Claude Code / Antigravity]
+    Bundle --> SDK[Python runtime]
+    Hosts <--> State[SQLite state and operation journal]
+    SDK <--> State
+```
+
+Default conversion preserves the procedure and adds generic bounded progress state. It does **not** infer every business invariant. Semantic proposals can supply domain-specific fields and steps; structural validation still needs to be followed by application tests.
+
+Definitions live under `.skillstate/definitions/`. Run data and artifacts live under `.skillstate/local/`. Original files remain unchanged. Source changes are detected before new runs; existing runs retain their pinned definition and expose drift.
+
+## Failure behavior
+
+| Event | Behavior |
+|---|---|
+| Invalid JSON, state or tool arguments | Reject before tool execution |
+| Stale revision or wrong owner | Reject; require a fresh read/handoff |
+| Tool reports failure | Keep prior state and record its observation |
+| Timeout, exception or invalid tool result | Mark `unknown`; require reconciliation |
+| Process exits after reserving an operation | Retain the pending intent; do not replay automatically |
+| Event write fails during result commit | Roll back state, operation outcome and event together |
+| User edits installed files/configuration | Preserve changes and report a conflict |
+
+SQLite does not create a distributed transaction with external APIs. A checkpoint cannot undo an external side effect. Owner IDs coordinate local clients; they are not an authentication boundary. Read [the execution contract](docs/architecture.md) before using mutating tools.
+
+## Development
+
+```bash
+python -m pip install uv
+uv sync --locked --extra dev
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest --cov=skillstate --cov-fail-under=85
+uv run python -m build
+uv run twine check dist/*
+```
+
+CI tests the Python/OS matrix, builds distributions and checks wheel installation. Tests include real MCP sessions, competing connections, crash recovery, configuration preservation, invalid schemas and source drift. Coverage is a regression signal, not proof of correctness.
+
+## Research and attribution
+
+An **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. Not affiliated with or endorsed by the authors or their institutions.
+
+The managed runtime follows the explicit-state input pattern. Our compiler, host adapters, explicit patch format and operation journal are engineering extensions. No paper benchmark scores are claimed. [skill-state-minimal](https://github.com/kissishka/skill-state-minimal) was inspected as a comparison; its source is not bundled here.
+
+## License and contributing
+
+[MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CHANGELOG.md](CHANGELOG.md) and [release guidance](docs/releasing.md).

skillstate_kit-0.1.1/SECURITY.md

@@ -0,0 +1,25 @@
+# Security and trust boundaries
+
+## Reporting
+
+Use GitHub private vulnerability reporting when available. While the repo is private, contact the maintainer through an existing private channel. Do not put credentials or exploitable production details in an issue or test another person's services.
+
+## Scope
+
+This library is not a sandbox. Python model/tool callbacks execute with the embedding application's permissions. Native tools remain subject to their host's permissions. Valid JSON is not business authorization.
+
+- Owner IDs coordinate cooperating clients; they do not authenticate tenants.
+- The MCP server is STDIO-only. Do not expose it through an unauthenticated network bridge.
+- Scanner paths are confined to the selected project; symlinks/junctions, known secret filenames and ignored files are excluded/rejected. Redaction is best effort. Inspect prepared inventories before sending sensitive projects to a remote generator.
+- Python scanning uses AST, not imports or execution.
+- JSON inputs are bounded. Duplicate keys, non-finite values and unsupported objects are rejected. Schema references and unrestricted regex patterns are disabled.
+- State/artifacts can contain sensitive data. Keep `.skillstate/local/` out of version control and use OS permissions and an appropriate retention policy.
+- Generated MCP configuration contains local paths; keep it local and respect host trust policies.
+
+## External effects
+
+`pending` and `unknown` operations require inspection of the external system before reconciliation. They are not permission to repeat a deployment, payment, mutation or message.
+
+Timeouts cancel waiting, not necessarily the external operation. A synchronous handler running in a thread can continue after timeout. Prefer cancellable asynchronous clients and service-level idempotency for production integrations.
+
+Supply application-level authorization, argument constraints, result validation, completion checks and recovery procedures. A local transaction cannot guarantee exactly-once effects across arbitrary remote systems.

skillstate_kit-0.1.1/docs/PYPI_README.md

@@ -0,0 +1,118 @@
+# skillstate-kit
+
+**Portable, validated execution state for agent skills.**
+
+Convert an existing `SKILL.md` into a state-backed skill, retain durable checkpoints, and integrate the same execution engine into a Python application.
+
+Python 3.11+ · MIT license · Initial alpha
+
+## Install
+
+```bash
+python -m pip install "skillstate-kit[mcp,http]"
+skillstate demo
+```
+
+The core package requires no model account. The demo uses an explicitly scripted model and local tools; it is not a benchmark of real-model performance.
+
+Optional extras:
+
+- `mcp`: a project-scoped STDIO MCP server and connection diagnostics.
+- `http`: a stateless adapter for a configured JSON-compatible chat-completions endpoint.
+
+## 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.
+
+## 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.

skillstate_kit-0.1.1/docs/README_TR.md

@@ -0,0 +1,43 @@
+# Türkçe başlangıç
+
+skillstate-kit, mevcut agent skill'lerini kalıcı ve doğrulanan görev durumuyla kullanmanızı sağlar. Sürüm alpha durumundadır; geliştirme deposu private kalırken paket PyPI üzerinden dağıtılır.
+
+## Kurulum
+
+Python 3.11 veya üzeri bir ortamda:
+
+```text
+python -m pip install "skillstate-kit[mcp,http]"
+skillstate demo
+```
+
+Ardından kullanacağınız projenin klasöründe:
+
+```text
+skillstate init --host codex --host claude-code --host antigravity --mcp
+skillstate generate skills/qa/SKILL.md --install
+skillstate validate qa-state
+skillstate doctor --mcp
+```
+
+`skills/qa/SKILL.md` yerine kendi dosyanızı kullanın. Yalnızca kullandığınız host'ları seçebilirsiniz. `--mcp` opsiyoneldir; temel kullanım CLI üzerinden çalışır. MCP ayarları bu makineye ait Python/proje yollarını içerir.
+
+## Otomatik üretim
+
+Kurulumdan sonra agent'a “Generate skill state; bu skill'i durum yapısına dönüştür” diyebilirsiniz. Üretici kaynak envanterini hazırlayıp agent'ın önerdiği şemayı doğrular.
+
+Doğrudan `generate`, yönergeleri koruyan sınırlı bir genel ilerleme şeması oluşturur. Alana özel dönüşüm için agent destekli `--prepare`/`--proposal` akışı veya yapılandırılmış `--base-url`/`--model` kullanılır. Terminal, IDE model hesabını otomatik kullanmaz.
+
+## Çalıştırma ve devam
+
+Üretilen skill, state açma, okuma, güncelleme, işlem sonucu kaydetme ve ortamlar arasında devretme adımlarını içerir. Python projeleri `SkillRuntime` ile bütün model/araç döngüsünü yönetebilir.
+
+Native skill host'un konuşma geçmişini silmez. Makaledeki geçmiş taşımayan model girdisini kurmak için stateless adapter ile managed runtime kullanın.
+
+`pending` veya `unknown` bir dış işlemin sonucunun belirsiz olduğunu gösterir. Tekrarlamadan önce dış sistemden sonucu kontrol edin ve açıkça uzlaştırın. Checkpoint dış dünyadaki işlemi geri almaz.
+
+## Doğrulama
+
+`skillstate demo` model hesabı gerektirmeyen kontrollü örnektir. `doctor --mcp` gerçek yerel MCP bağlantısı kurar. Bunlar bütün IDE sürümlerinin davranışını veya makalenin performans sonuçlarını doğrulamaz.
+
+Ayrıntılar: [CLI](cli.md), [mimari](architecture.md), [ortam desteği](compatibility.md), [test matrisi](validation.md).