Jotai 技能用于编写、审查、重构或调试 React 与 TypeScript 中符合 Jotai 惯用法的状态代码。其目标是让 Jotai 代码保持原子化、可组合、对 React 友好，优先采用小状态边界、派生原子、只写动作原子、稳定的原子引用和窄订阅，而不是 store 形状的对象和组件大范围重渲染。
用途
该技能适用于涉及 Jotai 原子的工作，包括派生原子、只写动作原子等。常见请求包括：审查 Jotai 原子设计；将 Context/useReducer 状态重构为 Jotai；让组件不再因无关原子变化而重渲染；将异步获取/更新流程迁移为惯用 Jotai 原子；为表单、表格、待办列表、编辑器、向导或缓存设计原子；将 atomFamily 从 jotai/utils 迁移到 jotai-family；将项目从 Jotai v2 升级到 v3；替换已移除的 loadable / setSelf / delay 选项；为 Jotai 状态行为编写测试。
主要能力
工作流程方面，技能要求在修改前先检查目标代码，识别现有状态归属、更新路径、渲染热点、异步行为、测试覆盖和已安装的 Jotai 主版本。状态建模上，将状态建模为原子：当值独立变化时拆分，用只读原子派生计算值，将命令移入只写原子。React 钩子选择上，使用最窄的钩子：读取优先 useAtomValue，写入优先 useSetAtom，仅当组件确实同时需要读写时才用 useAtom。原子配置需保持稳定：尽量在模块作用域定义原子；若在渲染期间创建，则用 useMemo、useRef 或 useState 进行记忆化。工具选择上，仅当工具匹配问题形状时才使用；优先使用普通派生原子，当 splitAtom、focusAtom、atomWithStorage、atomWithReset、unwrap 或相关辅助函数能真正消除复杂度时再使用。验证方面，尽量从面向用户的表面验证行为；仅对难以通过组件测试的逻辑添加聚焦的原子级测试。
参考路由
技能按任务匹配参考文件：references/atom-modeling.md 用于决定原子边界、派生原子、动作原子、可写适配器、重置、存储和 family 风格参数化原子；references/react-usage.md 用于钩子选择、Provider/store 作用域、水合、动态原子创建和组件架构；references/async-and-side-effects.md 用于 Suspense、异步读取、异步动作、中止信号、非 Suspense 状态、刷新流程和外部副作用；references/performance-and-large-state.md 用于渲染调优、selectAtom、focusAtom、splitAtom、大对象、列表和依赖图深度；references/typescript-and-testing.md 用于 TypeScript 推断、可写原子参数类型、ExtractAtomValue 和测试策略；references/utilities-decision-guide.md 用于选择内置工具，如存储、SSR 水合、可重置/默认原子、惰性原子、回调、reducer、select、split 和 family 迁移；references/extensions-decision-guide.md 用于选择扩展包，如 TanStack Query、optics、Immer、effects、location、scope、cache、XState、GraphQL/RPC 和外部 store 桥接；references/tools-and-debugging.md 用于选择 Devtools、Babel、SWC 和 Rolldown 支持，以进行调试、标签、React Refresh 和打包器集成；references/recipes-decision-guide.md 用于决定何时使用或改编官方配方，如 debounce、listeners、broadcast、compare、toggle、自定义钩子、reducer 钩子和原子效果；references/version-migration.md 用于 v2 与 v3 差异：提高的 React/TypeScript/Node 要求、仅 ESM 打包、v3 中移除的 API 及其替代品、v3 useAtomValue 挂载时机变化，以及 jotai/vanilla/internals 变动。
版本意识
该技能中的原子模型在 Jotai v2 和 v3 上相同，仅少量 API 和要求不同，因此在给出对版本敏感的建议前需确定已安装的主版本。Jotai v3 是一次现代化发布：仅 ESM 打包，最低要求 React 18 / TypeScript 5.5 / Node 22.12，并移除了 v2 后期已弃用的 API——atomFamily（移至 jotai-family）、loadable、jotai/babel（移至 jotai-babel）、read 函数的 setSelf 选项和 delay 钩子选项。它还新增了高级读取钩子 useAtomValueRaw 和 useAtomValueRawSync，并改变 useAtomValue 以跳过挂载后的重渲染。无论版本如何，新代码都应针对替代品编写：它们在 v2 上也可用，不会留下后续迁移工作。升级、已移除 API 的替代品和版本特定调试请阅读 references/version-migration.md。
Jotai 风格审查启发式
审查和重构时倾向于以下更改：当字段独立更新或渲染时，用更小的原子替换单体应用状态原子；当值被共享或属于状态图时，用只读派生原子替换重复的组件本地派生；当动作可代码分割或独立使用时，用聚焦的只写动作原子替换 reducer 形状的 dispatch 原子；在模块作用域隐藏实现原子，并导出有意的读取/动作原子以澄清公共状态 API；当组件只写入时，用 useSetAtom(valueAtom) 替换 const [, setValue] = useAtom(valueAtom)；当组件只读取时，用 useAtomValue(valueAtom) 替换 const [value] = useAtom(valueAtom)；避免在渲染中内联创建原子而不进行记忆化；将 selectAtom 视为相等性或前一片段需求的逃生舱，而非派生值的默认方式；对于需要项级订阅或更新的动态列表，优先使用 splitAtom；避免非常深的派生原子链，保持依赖图宽，并在一个读取/动作内计算归约；即使项目仍在 v2 且只看到弃用警告，也用后继 API 替换版本意识下列出的 API；保持 useAtomValue 为默认读取钩子，将 useAtomValueRaw 和 useAtomValueRawSync 视为有意的逃生舱，而非习惯性使用的替代品。
兼容性与来源验证
此修订版针对 Jotai 3.0.1 编写，并在两者不同之处覆盖 Jotai 2.20.x。在给出对版本敏感的 API 指导前，需确定目标项目已安装的 Jotai 和扩展包版本，然后检查其导出的类型、源码或匹配的文档和测试。不要假设当前文档与已安装版本一致。