Iii iii-state-management

install

source · Clone the upstream repo

git clone https://github.com/iii-hq/iii

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/iii-hq/iii "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/iii-state-management" ~/.claude/skills/iii-hq-iii-iii-state-management && rm -rf "$T"

manifest: skills/iii-state-management/SKILL.md

source content

State Management

Comparable to: Redis, DynamoDB, Memcached

Key Concepts

Use the concepts below when they fit the task. Not every state operation needs all of them.

State is a scoped key-value store accessed via built-in trigger functions
state::set writes a value; state::get reads it (returns
```
null
```
for missing keys)
state::list retrieves all keys in a scope; state::delete removes a key
state::update performs a partial merge using an
```
ops
```
array for fine-grained changes
Payloads use
```
scope
```
,
```
key
```
, and
```
value
```
to address state entries
State is shared across all functions — use meaningful scope names to avoid collisions

Architecture

Function
  → trigger('state::set', { scope, key, value })
  → trigger('state::get', { scope, key })
  → trigger('state::update', { scope, key, ops })
  → trigger('state::delete', { scope, key })
  → trigger('state::list', { scope })
    → iii-state → KvStore / Redis adapter

iii Primitives Used

Primitive	Purpose
`trigger({ function_id: 'state::set', payload })`	Write a value to state
`trigger({ function_id: 'state::get', payload })`	Read a value from state
`trigger({ function_id: 'state::list', payload })`	List all keys in a scope
`trigger({ function_id: 'state::delete', payload })`	Remove a key from state
`trigger({ function_id: 'state::update', payload: { ops } })`	Partial merge with operations array

Reference Implementation

See ../references/state-management.js for the full working example — functions that read, write, update, and delete state entries across a shared scope.

Also available in Python: ../references/state-management.py

Also available in Rust: ../references/state-management.rs

Common Patterns

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

trigger({ function_id: 'state::set', payload: { scope, key, value } })

— write state

trigger({ function_id: 'state::get', payload: { scope, key } })

— read state (returns

null

if missing)

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

— partial merge

trigger({ function_id: 'state::list', payload: { scope } })

— enumerate keys

trigger({ function_id: 'state::delete', payload: { scope, key } })

— remove entry

```
const logger = new Logger()
```
— structured logging

Adapting This Pattern

Use the adaptations below when they apply to the task.

Name scopes after your domain (e.g.
```
user-sessions
```
,
```
order-data
```
,
```
config
```
)
Use
```
state::get
```
with a
```
null
```
check to handle missing keys gracefully
Use
```
state::update
```
with
```
ops
```
for partial updates instead of read-modify-write cycles
Combine with
```
iii-queue-processing
```
to persist results after async job completion

Engine Configuration

iii-state must be enabled in iii-config.yaml with either the

kv

adapter (file-based or in-memory) or the separate

redis

adapter. See ../references/iii-config.yaml for the full annotated config reference.

Pattern Boundaries

If the task needs reactive side effects when state changes, prefer
```
iii-state-reactions
```
.
If the task needs real-time client push when data updates, prefer
```
iii-realtime-streams
```
.
Stay with
```
iii-state-management
```
when the primary need is reading and writing persistent key-value data.

When to Use

Use this skill when the task is primarily about
```
iii-state-management
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.