@skillstate/claude 2.0.1 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @skillstate/claude
|
|
4
|
+
|
|
5
|
+
**Claude Code platform adapter for the @skillstate/core runtime — state injection and persistence via hook scripts.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@skillstate/claude)
|
|
8
|
+
[](https://www.npmjs.com/package/@skillstate/claude)
|
|
9
|
+
[](https://github.com/vitalykuzyaev/skillstate)
|
|
10
|
+
[](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
`@skillstate/claude` bridges the paper-exact core ([`@skillstate/core`](../core))
|
|
17
|
+
into **Claude Code** sessions. It emits self-contained CommonJS hook scripts
|
|
18
|
+
(run via `node script.cjs`) that inject the persisted skill state into tool
|
|
19
|
+
context and extract a validated `state_patch` from the model's response.
|
|
20
|
+
|
|
21
|
+
> **@non-paper** — no adapters exist in arXiv 2608.26263v3. This adapter is an
|
|
22
|
+
> additive integration, not part of the paper.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm i @skillstate/core @skillstate/claude
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Requires Node.js >= 20. TypeScript types are bundled.
|
|
31
|
+
|
|
32
|
+
## Quick start
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { ClaudeAdapter } from '@skillstate/claude';
|
|
36
|
+
import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
|
|
37
|
+
|
|
38
|
+
const adapter = new ClaudeAdapter();
|
|
39
|
+
|
|
40
|
+
// System-prompt boilerplate that turns any Claude Code session into
|
|
41
|
+
// state-based execution mode:
|
|
42
|
+
const modePrompt = adapter.generateAppendPrompt();
|
|
43
|
+
|
|
44
|
+
// PreToolUse: injects the persisted state into the tool call's additionalContext.
|
|
45
|
+
const pre = adapter.generateHookScript('PreToolUse', './.skillstate.json');
|
|
46
|
+
|
|
47
|
+
// PostToolUse: extracts state_patch from the response, validates it against the
|
|
48
|
+
// embedded schema, applies the null-deletion ⊕ merge, and saves the state file.
|
|
49
|
+
const post = adapter.generateHookScript(
|
|
50
|
+
'PostToolUse',
|
|
51
|
+
'./.skillstate.json',
|
|
52
|
+
INTERCODE_CTF_SPEC.schema,
|
|
53
|
+
);
|
|
54
|
+
|
|
55
|
+
// PreCompact + SessionStart(compact): the best available O(1)-friendly pair.
|
|
56
|
+
const hooks = adapter.generateAllHooksScripts('./.skillstate.json', INTERCODE_CTF_SPEC.schema);
|
|
57
|
+
// hooks.preCompact -> injects state + diff into compaction summary
|
|
58
|
+
// hooks.sessionStartCompact -> re-injects state after compaction
|
|
59
|
+
|
|
60
|
+
// Persist a hook script to disk (atomic tmp + fsync + rename), returns path:
|
|
61
|
+
const saved = await adapter.saveHookScript(
|
|
62
|
+
'./hooks/post-tool-use.cjs',
|
|
63
|
+
'PostToolUse',
|
|
64
|
+
'./.skillstate.json',
|
|
65
|
+
INTERCODE_CTF_SPEC.schema,
|
|
66
|
+
);
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## API / Exports
|
|
70
|
+
|
|
71
|
+
Root path `@skillstate/claude` exports one thing: `ClaudeAdapter`.
|
|
72
|
+
|
|
73
|
+
- `new ClaudeAdapter()` — implements `PlatformAdapter` (`name = 'claude'`).
|
|
74
|
+
- `generateHookScript(eventType, statePath, schema?): string` — where
|
|
75
|
+
`eventType` is `'PreToolUse' | 'PostToolUse'`. Accepts a raw path or a
|
|
76
|
+
`{ root, name }` ref confined by `resolveStatePath` (`..` escapes throw).
|
|
77
|
+
- `generateCompactHookScript(statePath, schema?): string` — PreCompact script
|
|
78
|
+
injecting the current state + a diff since the last compact snapshot.
|
|
79
|
+
- `generateSessionStartHookScript(statePath): string` — SessionStart hook with
|
|
80
|
+
a `source: "compact"` matcher.
|
|
81
|
+
- `generateAllHooksScripts(statePath, schema?): { preCompact; sessionStartCompact }`.
|
|
82
|
+
- `generateAppendPrompt(): string` — mode-switch prompt boilerplate.
|
|
83
|
+
- `injectState(state, spec): string` / `formatPrompt(state, observation, spec): string`.
|
|
84
|
+
- `extractPatch(response): StatePatch | null` / `extractAction(response): string | null`.
|
|
85
|
+
- `saveHookScript(target, eventType, statePath, schema?): Promise<string>` —
|
|
86
|
+
generates a hook script and persists it atomically; returns the destination.
|
|
87
|
+
|
|
88
|
+
## Notes
|
|
89
|
+
|
|
90
|
+
- **Honest limitation.** Claude Code hooks are **append-only** — history cannot
|
|
91
|
+
be trimmed from hooks, so true O(1) is not possible. The hooks inject state
|
|
92
|
+
into the compaction summary (PreCompact) and re-inject it after compaction
|
|
93
|
+
(SessionStart), but the conversation history keeps growing until the host
|
|
94
|
+
trims it.
|
|
95
|
+
- The generated scripts are self-contained CommonJS and embed the schema, so
|
|
96
|
+
unknown keys / wrong types are rejected and **malformed outputs are never
|
|
97
|
+
persisted** — state corruption by a bad patch is impossible.
|
|
98
|
+
- Depends on [`@skillstate/core`](../core) for the ⊕ merge semantics
|
|
99
|
+
(`mergeState`), `PromptTransformer`, `atomicWriteFile`, and `resolveStatePath`.
|
|
100
|
+
|
|
101
|
+
## Related
|
|
102
|
+
|
|
103
|
+
- Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263).
|
|
104
|
+
- Core runtime: [`@skillstate/core`](../core).
|
|
105
|
+
- [`state.md`](../../state.md) — design notes.
|
|
106
|
+
- Other adapters: `@skillstate/opencode`, `@skillstate/codex`, `@skillstate/mcp`.
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
[MIT](LICENSE) © 2026 Vitaly Kuzyaev
|