The Complete Production SOP: How to Deploy and Run Jotai Bottom-Up Atomic State & Async Derived Atoms in Autonomous AI Agents
Production SOP to install and run Jotai atomic & async derived state skills in Codex, Claude Code, Cursor, and Windsurf. Includes prompts, sandboxes & fixes.
Technical Overview & Architectural Context
Autonomous coding agents frequently default to legacy top-down state patterns when refactoring complex React applications. Without structural boundaries, agents hallucinate heavyweight context providers, introduce circular atom dependencies, improperly trigger React Suspense watermarks inside client components, or create redundant parent re-renders through naive prop drilling instead of bottom-up composition. When handling asynchronous reads and atom families (atomFamily), unguided LLMs often generate memory leaks by instantiating new atom instances inside render loops rather than stabilizing atom identities. The 'jotai-atomic-derived-state' skill provides autonomous agents (such as OpenAI Codex, Claude Code, Cursor, and Windsurf) with a strict procedural standard operating procedure (SOP). By enforcing declarative primitive boundaries, read-only vs. read-write derived atom structures, and deterministic cache invalidation with atomFamily and Suspense boundaries, this skill ensures that agents generate performant, leak-free, and type-safe Jotai state graphs every single time.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into agent runtimes.
Autonomous runtimes like Claude Code, Codex, and Cursor discover skill manifests from either local repository root configurations (.cursor/rules, .claude/skills) or user-level registries (~/.agents/skills). Mounting the SKILL.md for jotai-atomic-derived-state ensures that natural language invocations like 'create jotai derived atom' or 'atomfamily jotai' load the deterministic state machine instructions directly into the agent's execution planner.
mkdir -p .cursor/rules/jotai-state ~/.agents/skills/jotai-atomic-derived-state && curl -fsSL https://askills.dev/api/skills/jotai-atomic-derived-state/raw -o .cursor/rules/jotai-state/SKILL.md---
name: "jotai-atomic-derived-state"
description: "Build flexible, bottom-up React state architectures using minimal primitive and derived atoms."
metadata:
author: "Poimandres"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create jotai derived atom"
- "async atom jotai suspense"
- "atomfamily jotai"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Place the SKILL.md file inside the workspace root under '.agents/skills/' rather than global user directories to ensure consistent reproducibility across CI/CD and team developer environments.
Ensure fs_write permissions remain restricted to 'workspace'. Granting broad file write permissions can lead to agents altering node_modules or overwriting unrelated config files during atomic refactors.
Dependency Validation & Jotai Peer Dependencies
Validate workspace dependencies ensuring Jotai core and required utilities are present without missing peer links.
For Jotai derived async workflows, both 'jotai' and React 18/19 are mandatory. If atomFamily or async utilities are required, 'jotai/utils' must be imported correctly from subpaths. Agents must verify that TypeScript's moduleResolution is set to 'bundler' or 'node16' to prevent resolution failures during atom compilation.
pnpm add jotai && pnpm exec tsc --noEmitInstruct your agent to utilize 'jotai/utils' for atomFamily rather than building manual Map caches to prevent unbounded memory growth during high-churn UI events.
Watch out for React versions mismatching across monorepos; ensure multiple Jotai package versions do not create dual-store contexts, which causes useAtom to fail silently.
Deterministic Trigger Invocation & Prompt Anchoring
Trigger the skill deterministically using standardized prompt phrasing matching frontmatter triggers.
Agent planners index triggers such as 'create jotai derived atom' or 'async atom jotai suspense'. By providing a clear prompt that specifies primitive inputs, derived business logic, and setter transformations, the agent applies the 4-step execution SOP without improvising global singletons or unnecessary React contexts.
Always specify whether the derived atom requires a custom write function (read-write) or remains read-only to save LLM reasoning tokens and prevent recursive setter bugs.
Do not declare atom creation inside React component bodies. Ensure the agent writes top-level atom declarations or uses custom hook hooks like 'useMemo(() => atom(...), [])' strictly when parameterized on mount.
Verification, Linting & Output Quality Gate
Execute automated type-checking and linter gates to guarantee zero unhandled promises or stale re-renders.
The skill mandates that the agent must execute automated validation steps before finishing. For Jotai, this requires running the TypeScript compiler to ensure read-only atoms are not passed to writeable useAtom hooks, and validating that async atoms are consumed within Suspense or loadable wrappers.
pnpm eslint src/state --ext .ts,.tsx && pnpm tsc --noEmitRun 'git diff --stat' directly after agent code modifications to ensure only targeted state files and component consumers were touched.
Async read atoms without Suspense will cause React to suspend abruptly without an ErrorBoundary, crashing the entire UI tree in production.
Real-World Scenario: Refactoring Monolithic Order Checkout State to Bottom-Up Jotai Derived Atoms with Async Validation
“create jotai derived atom for calculating order discounts and an async atom jotai suspense for inventory check. Extract this from the monolithic CartProvider in src/context/CartContext.tsx into src/state/cartAtoms.ts.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent authored a derived atom whose read function calls get(atom) on an atom that transitively references the derived atom itself, or a write function that synchronously reads and sets the same atom in an uncontrolled loop.
// Break cyclic chain by separating primary state from downstream projection:
export const baseQueryAtom = atom('');
export const resultsAtom = atom(async (get) => {
const query = get(baseQueryAtom);
return query ? await fetchResults(query) : [];
});
// DO NOT call get(resultsAtom) inside baseQueryAtom setter!Root Cause: The agent bound an async derived atom directly using useAtomValue(asyncAtom) inside a consumer component that lacks an ancestor <Suspense> boundary.
import { loadable } from 'jotai/utils';
// Option 1: Wrap component with <Suspense fallback={<Spinner />} />
// Option 2: Use loadable utility to avoid suspense crashes in non-suspense trees:
export const loadableInventoryAtom = loadable(inventoryCheckAtom);
// In component: const value = useAtomValue(loadableInventoryAtom); if (value.state === 'loading') { ... }Frequently Asked Questions (Jotai Bottom-Up Atomic State & Async Derived Atoms SOP)
Q:Can I use Jotai Bottom-Up Atomic State & Async Derived Atoms across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Runtimes parse the frontmatter triggers and SOP instructions identically, allowing developers to switch between CLI agents (Claude Code) and IDE extensions (Cursor, Windsurf, Codex) without re-configuring rules.
Q:How does Jotai Bottom-Up Atomic State & Async Derived Atoms prevent context window overflow during long agent sessions?
The skill enforces modular atom definitions and strict boundary rules (4-step SOP), eliminating lengthy recursive LLM retry loops caused by React re-render bugs and Suspense edge cases. This keeps the agent's context focused strictly on the files being touched.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires workspace-level file access (fs_read: true, fs_write: 'workspace') and requires zero network access (net_access: false) or shell execution privileges during state generation.
Ready to equip your autonomous agent with Jotai Bottom-Up Atomic State & Async Derived Atoms?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.