Agent skill
iii-state-reactions
Registers state-type triggers that automatically fire functions when key-value state is created, updated, or deleted within a scope. Use when building reactive side effects, change watchers, audit logs, cache invalidation, notification dispatchers, or any observer pattern where data changes should trigger downstream processing.
Install this agent skill to your Project
npx add-skill https://github.com/iii-hq/iii/tree/main/skills/iii-state-reactions
SKILL.md
State Reactions
Comparable to: Firebase onSnapshot, Convex mutations
Key Concepts
Use the concepts below when they fit the task. Not every state reaction needs all of them.
- A state trigger fires whenever a value changes within a watched scope
- The handler receives
{ new_value, old_value, key, event_type }describing the change - condition_function_id gates execution — the reaction only fires if the condition returns truthy
- Multiple reactions can independently watch the same scope
- Reactions fire on
state::set,state::update, andstate::deleteoperations
Architecture
state::set, state::update, or state::delete
→ iii-state emits change event
→ registerTrigger type:'state' (scope match)
→ condition_function_id check (if configured)
→ registerFunction handler ({ new_value, old_value, key, event_type })
iii Primitives Used
| Primitive | Purpose |
|---|---|
registerFunction |
Define the reaction handler |
registerTrigger({ type: 'state' }) |
Watch a scope for changes |
config: { scope, key, condition_function_id } |
Scope filter and optional condition gate |
Event payload: { new_value, old_value, key, event_type } |
Change details passed to the handler |
Reference Implementation
See ../references/state-reactions.js for the full working example — a reaction that watches a state scope and fires side effects when values change, with an optional condition gate.
Also available in Python: ../references/state-reactions.py
Also available in Rust: ../references/state-reactions.rs
Common Patterns
Code using this pattern commonly includes, when relevant:
registerWorker(url, { workerName })— worker initializationregisterFunction(id, handler)— define the reaction handlerregisterTrigger({ type: 'state', function_id, config: { scope, key, condition_function_id } })— watch for changespayload.new_value/payload.old_value— compare before and afterpayload.event_type— distinguish between set, update, and delete eventstrigger({ function_id: 'state::set', payload })— write derived state from the reactionconst logger = new Logger()— structured logging per reaction
Adapting This Pattern
Use the adaptations below when they apply to the task.
- Set
scopeto watch a specific domain (e.g.orders,user-profiles) - Use
keyto narrow reactions to a single key within a scope - Add a
condition_function_idto filter — only react when the condition function returns truthy - Chain reactions by writing state in one handler that triggers another reaction on a different scope
Engine Configuration
iii-state must be enabled in iii-config.yaml for state triggers to fire. See ../references/iii-config.yaml for the full annotated config reference.
Pattern Boundaries
- If the task is about directly reading or writing state without reactions, prefer
iii-state-management. - If the task needs conditional trigger logic shared across trigger types, prefer
iii-trigger-conditions. - Stay with
iii-state-reactionswhen the primary need is automatic side effects on state changes.
When to Use
- Use this skill when the task is primarily about
iii-state-reactionsin the iii engine. - Use this skill 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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
iii-dead-letter-queues
Inspects and redrives jobs that exhausted all retries. Use when handling failed queue jobs, debugging processing errors, or implementing retry strategies.
iii-cron-scheduling
Registers cron triggers with 7-field expressions to run functions on recurring schedules. Use when scheduling periodic jobs, timed automation, crontab replacements, cleanup routines, report generation, health checks, batch processing, or any task that should run every N seconds, minutes, hours, or on a weekly/monthly calendar.
iii-http-invoked-functions
Registers external HTTP endpoints as iii functions using registerFunction(id, HttpInvocationConfig). Use when adapting legacy APIs, third-party webhooks, or immutable services into triggerable iii functions, especially when prompts ask for endpoint maps like { path, id } iterated into registerFunction calls.
iii-channels
Binary streaming between workers via channels. Use when building data pipelines, file transfers, streaming responses, or any pattern requiring binary data transfer between functions.
iii-event-driven-cqrs
Implements CQRS with event sourcing on the iii engine. Use when building command/query separation, event-sourced systems, or fan-out architectures where commands publish domain events and multiple read model projections subscribe independently.
iii-agentic-backend
Creates and orchestrates multi-agent pipelines on the iii engine. Use when building AI agent collaboration, agent orchestration, research/review/synthesis chains, or any system where specialized agents hand off work through queues and shared state.
Didn't find tool you were looking for?