From f762f80b4bfe85cf95710ed02412e836083e3d8d Mon Sep 17 00:00:00 2001
From: MAnasLatif <104300600+MAnasLatif@users.noreply.github.com>
Date: Fri, 1 May 2026 03:23:28 +0500
Subject: [PATCH 1/3] feat: Add comprehensive documentation for usehooks-ts
 including skills, composition recipes, hook catalog, SSR guidance, and
 testing pitfalls

---
 skills/usehooks-ts/SKILL.md                   | 108 +++++++++
 .../references/composition-recipes.md         | 216 ++++++++++++++++++
 skills/usehooks-ts/references/hook-catalog.md |  76 ++++++
 .../usehooks-ts/references/ssr-frameworks.md  | 148 ++++++++++++
 .../references/testing-pitfalls.md            | 138 +++++++++++
 5 files changed, 686 insertions(+)
 create mode 100644 skills/usehooks-ts/SKILL.md
 create mode 100644 skills/usehooks-ts/references/composition-recipes.md
 create mode 100644 skills/usehooks-ts/references/hook-catalog.md
 create mode 100644 skills/usehooks-ts/references/ssr-frameworks.md
 create mode 100644 skills/usehooks-ts/references/testing-pitfalls.md

diff --git a/skills/usehooks-ts/SKILL.md b/skills/usehooks-ts/SKILL.md
new file mode 100644
index 00000000..8214a9d8
--- /dev/null
+++ b/skills/usehooks-ts/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: usehooks-ts
+description: Practical guidance for using the usehooks-ts React hook library in TypeScript projects. Use when choosing hooks, installing or importing usehooks-ts, integrating hooks in React or Next.js components, handling SSR and hydration issues, replacing removed v2 hooks, composing hooks into UI behavior, testing components that use the package, or auditing existing usehooks-ts usage.
+---
+
+# usehooks-ts
+
+## Overview
+
+Use this skill to integrate `usehooks-ts` v3-style APIs into React applications safely and idiomatically. Prefer the package's existing hooks over custom hook code when the requested behavior matches a supported hook.
+
+## Fast Workflow
+
+1. Inspect the app context: React version, framework, package manager, TypeScript settings, routing model, and whether the target file runs on the server or client.
+2. Confirm the package is installed. If absent, use the project's package manager:
+
+```bash
+npm install usehooks-ts
+pnpm add usehooks-ts
+yarn add usehooks-ts
+bun add usehooks-ts
+```
+
+3. Import hooks as named exports from the package root:
+
+```tsx
+import { useLocalStorage, useMediaQuery } from 'usehooks-ts'
+```
+
+4. Choose the hook by intent. Read `references/hook-catalog.md` when choosing among hooks or when exact return shapes matter.
+5. Apply SSR rules before editing Next.js, Remix, Astro, Gatsby, or any server-rendered React app. Read `references/ssr-frameworks.md` for those cases.
+6. Use recipe references for common UI tasks. Read `references/composition-recipes.md` when implementing behavior rather than just naming a hook.
+7. For tests, migrations, or existing code reviews, read `references/testing-pitfalls.md`.
+8. Validate with the local app's normal commands: typecheck, lint, focused tests, and a browser check when behavior depends on DOM events, storage, viewport, media queries, clipboard, timers, observers, or scripts.
+
+## Core Rules
+
+- Use named imports from `usehooks-ts`; do not deep-import from `usehooks-ts/dist` or internal package paths.
+- In Next.js App Router, any component that calls these hooks must be a Client Component. Add `'use client'` at the top of the component file or move hook usage into a client child.
+- For hooks that read browser-only APIs during initial render, prefer `initializeWithValue: false` when server-rendered markup must match client hydration.
+- Treat `useLocalStorage`, `useSessionStorage`, and `useReadLocalStorage` as JSON-based by default. Use `serializer` and `deserializer` for `Date`, `Map`, `Set`, classes, lossy values, or custom formats.
+- Prefer `useEventCallback`, `useEventListener`, `useInterval`, and `useTimeout` for stale-closure-prone event or timer work.
+- Prefer `useDebounceValue` for debounced state and `useDebounceCallback` for debounced side effects.
+- Prefer framework-native or cache-aware data fetching. Do not replace React Query, SWR, loaders, or Server Components with removed `useFetch` patterns.
+- Avoid wrapping every library hook in a project-local hook unless it centralizes a real policy, storage key, serializer, or UI convention.
+
+## Hook Choice Snapshot
+
+- State utilities: `useBoolean`, `useCounter`, `useMap`, `useStep`, `useToggle`.
+- Browser storage: `useLocalStorage`, `useSessionStorage`, `useReadLocalStorage`.
+- DOM events and element interaction: `useEventListener`, `useOnClickOutside`, `useClickAnyWhere`, `useHover`.
+- Timers and debounce: `useInterval`, `useTimeout`, `useDebounceValue`, `useDebounceCallback`, `useCountdown`.
+- Layout and environment: `useWindowSize`, `useScreen`, `useMediaQuery`, `useResizeObserver`, `useIntersectionObserver`, `useIsClient`, `useIsMounted`, `useIsomorphicLayoutEffect`.
+- App utilities: `useCopyToClipboard`, `useDarkMode`, `useTernaryDarkMode`, `useDocumentTitle`, `useScript`, `useScrollLock`, `useUnmount`, `useEventCallback`.
+
+## Common Patterns
+
+Persistent state:
+
+```tsx
+const [value, setValue, removeValue] = useLocalStorage('settings', initial, {
+  initializeWithValue: false,
+})
+```
+
+Responsive rendering:
+
+```tsx
+const isDesktop = useMediaQuery('(min-width: 1024px)', {
+  initializeWithValue: false,
+})
+```
+
+Stable DOM listener:
+
+```tsx
+useEventListener('keydown', event => {
+  if (event.key === 'Escape') close()
+})
+```
+
+Click outside:
+
+```tsx
+const panelRef = useRef<HTMLDivElement>(null)
+useOnClickOutside(panelRef, close, 'mousedown')
+```
+
+Debounced input:
+
+```tsx
+const [query, setQuery] = useState('')
+const [debouncedQuery] = useDebounceValue(query, 300)
+```
+
+## Bundled Resources
+
+- `references/hook-catalog.md`: hook-by-hook selection guide and API notes.
+- `references/ssr-frameworks.md`: SSR, hydration, Next.js App Router, and browser API guidance.
+- `references/composition-recipes.md`: reusable implementation recipes.
+- `references/testing-pitfalls.md`: test setup, mocks, migrations, and sharp edges.
+- `scripts/audit_usehooks_ts_usage.py`: scan a project for common import, SSR, migration, and client-component issues.
+
+Run the audit script from a project root when reviewing existing code:
+
+```bash
+python3 /path/to/skills/usehooks-ts/scripts/audit_usehooks_ts_usage.py .
+```
diff --git a/skills/usehooks-ts/references/composition-recipes.md b/skills/usehooks-ts/references/composition-recipes.md
new file mode 100644
index 00000000..7907b972
--- /dev/null
+++ b/skills/usehooks-ts/references/composition-recipes.md
@@ -0,0 +1,216 @@
+# Composition Recipes
+
+Use these examples as starting points. Adapt names, storage keys, and UI components to the project.
+
+## Persistent Form Draft
+
+```tsx
+'use client'
+
+import { useLocalStorage } from 'usehooks-ts'
+
+type Draft = {
+  title: string
+  body: string
+}
+
+export function DraftEditor() {
+  const [draft, setDraft, clearDraft] = useLocalStorage<Draft>(
+    'post-draft',
+    { title: '', body: '' },
+    { initializeWithValue: false },
+  )
+
+  return (
+    <form>
+      <input
+        value={draft.title}
+        onChange={event =>
+          setDraft(current => ({ ...current, title: event.target.value }))
+        }
+      />
+      <textarea
+        value={draft.body}
+        onChange={event =>
+          setDraft(current => ({ ...current, body: event.target.value }))
+        }
+      />
+      <button type="button" onClick={clearDraft}>
+        Clear
+      </button>
+    </form>
+  )
+}
+```
+
+## Debounced Search
+
+Use `useDebounceValue` when state should lag user input:
+
+```tsx
+const [query, setQuery] = useState('')
+const [debouncedQuery] = useDebounceValue(query, 300)
+
+useEffect(() => {
+  if (!debouncedQuery) return
+  void search(debouncedQuery)
+}, [debouncedQuery])
+```
+
+Use `useDebounceCallback` when the side effect itself should be debounced:
+
+```tsx
+const saveDraft = useDebounceCallback(async (value: Draft) => {
+  await api.saveDraft(value)
+}, 500)
+
+useEffect(() => {
+  saveDraft(draft)
+}, [draft, saveDraft])
+```
+
+Cancel or flush if the UX requires it:
+
+```tsx
+useUnmount(() => {
+  saveDraft.flush()
+})
+```
+
+## Dismissible Popover
+
+```tsx
+const popoverRef = useRef<HTMLDivElement>(null)
+const { value: open, setFalse: close, toggle } = useBoolean(false)
+
+useOnClickOutside(popoverRef, close)
+
+return (
+  <>
+    <button onClick={toggle}>Menu</button>
+    {open && <div ref={popoverRef}>...</div>}
+  </>
+)
+```
+
+For keyboard dismissal:
+
+```tsx
+useEventListener('keydown', event => {
+  if (event.key === 'Escape') close()
+})
+```
+
+## Copy Button
+
+```tsx
+const [copiedText, copy] = useCopyToClipboard()
+const [copied, setCopied] = useState(false)
+
+async function handleCopy(value: string) {
+  const ok = await copy(value)
+  if (!ok) return
+  setCopied(true)
+  window.setTimeout(() => setCopied(false), 1500)
+}
+```
+
+Handle failure because clipboard access can be blocked.
+
+## Scroll-Locked Overlay
+
+```tsx
+function Modal({ open, onClose }: Props) {
+  useScrollLock({ autoLock: open })
+
+  if (!open) return null
+  return <div role="dialog">...</div>
+}
+```
+
+For manual control:
+
+```tsx
+const { isLocked, lock, unlock } = useScrollLock({ autoLock: false })
+```
+
+## Responsive Behavior
+
+```tsx
+const isDesktop = useMediaQuery('(min-width: 1024px)', {
+  defaultValue: false,
+  initializeWithValue: false,
+})
+
+return isDesktop ? <DesktopNav /> : <MobileNav />
+```
+
+Prefer CSS for styling-only changes. Use this only when component behavior changes.
+
+## Element Measurement
+
+```tsx
+const ref = useRef<HTMLDivElement>(null)
+const { width = 0 } = useResizeObserver({ ref })
+
+return <div ref={ref}>{width > 480 ? <Wide /> : <Compact />}</div>
+```
+
+Use `onResize` for expensive updates that should avoid rerendering the measuring component:
+
+```tsx
+useResizeObserver({
+  ref,
+  onResize: size => reportSize(size),
+})
+```
+
+## Lazy Reveal
+
+```tsx
+const { ref, isIntersecting } = useIntersectionObserver({
+  threshold: 0.25,
+  freezeOnceVisible: true,
+})
+
+return <section ref={ref}>{isIntersecting ? <Chart /> : null}</section>
+```
+
+## Countdown
+
+```tsx
+const [count, controls] = useCountdown({
+  countStart: 10,
+  countStop: 0,
+  intervalMs: 1000,
+})
+
+return (
+  <>
+    <span>{count}</span>
+    <button onClick={controls.startCountdown}>Start</button>
+    <button onClick={controls.stopCountdown}>Stop</button>
+    <button onClick={controls.resetCountdown}>Reset</button>
+  </>
+)
+```
+
+## Document Title
+
+```tsx
+useDocumentTitle(project.name)
+```
+
+Keep title construction near route or page components, not deeply nested widgets, unless the widget owns the page-level state.
+
+## External Script Status
+
+```tsx
+const status = useScript('https://cdn.example.com/sdk.js', {
+  id: 'example-sdk',
+})
+
+if (status === 'loading') return <Spinner />
+if (status === 'error') return <RetryMessage />
+return <Widget />
+```
diff --git a/skills/usehooks-ts/references/hook-catalog.md b/skills/usehooks-ts/references/hook-catalog.md
new file mode 100644
index 00000000..5205f675
--- /dev/null
+++ b/skills/usehooks-ts/references/hook-catalog.md
@@ -0,0 +1,76 @@
+# Hook Catalog
+
+Use this file when selecting a hook or checking return shapes. Target the v3 API represented by this repository. If the user asks for the latest npm version, verify against the project's lockfile or npm before relying on exact version claims.
+
+## Selection Table
+
+| Hook | Use for | API notes |
+| --- | --- | --- |
+| `useBoolean` | Boolean state plus `setTrue`, `setFalse`, `toggle` helpers. | Returns `{ value, setValue, setTrue, setFalse, toggle }`. Throws if the default value is not boolean. |
+| `useClickAnyWhere` | Handling document-wide click events. | Use for global click behavior, not outside-click detection. |
+| `useCopyToClipboard` | Copying text with the Clipboard API. | Returns copied value state and a copy function. Must run in a browser and may fail without permissions or secure context. |
+| `useCountdown` | Start, stop, reset countdown or count-up behavior. | Returns `[count, { startCountdown, stopCountdown, resetCountdown }]`. Uses `useInterval`. |
+| `useCounter` | Numeric counter state. | Returns `{ count, increment, decrement, reset, setCount }`. |
+| `useDarkMode` | Boolean dark mode preference backed by local storage and OS preference. | Returns `{ isDarkMode, toggle, enable, disable, set }`. Use `initializeWithValue: false` in SSR-sensitive components. |
+| `useDebounceCallback` | Debouncing a callback or side effect. | Returns a debounced function with `cancel`, `flush`, and `isPending`. Depends on `lodash.debounce`. |
+| `useDebounceValue` | Debouncing a changing value. | Returns `[debouncedValue, updateDebouncedValue]`. Supports `equalityFn`. |
+| `useDocumentTitle` | Setting `document.title`. | Use only in client-rendered components. Check options for reset-on-unmount behavior in codebase docs if needed. |
+| `useEventCallback` | Stable event callbacks without stale closures. | Use inside custom hooks or event/timer work. Do not call the returned handler during render. |
+| `useEventListener` | Window, document, element, SVG, or `MediaQueryList` event listeners. | Saves latest handler in a ref. Pass a ref for non-window targets. |
+| `useHover` | Hover state for an element ref. | Use when CSS hover is insufficient because React state must change. |
+| `useIntersectionObserver` | Observing visibility in viewport or a root. | Returns tuple and object fields: `[ref, isIntersecting, entry]` plus `.ref`, `.isIntersecting`, `.entry`. |
+| `useInterval` | Intervals with fresh callback semantics. | Pass `null` delay to stop. `0` is valid. |
+| `useIsClient` | Knowing whether code has reached the client. | Helpful for conditional rendering after hydration. |
+| `useIsMounted` | Checking mounted status from async callbacks. | Returns a function, usually called before setting state after async work. |
+| `useIsomorphicLayoutEffect` | `useLayoutEffect` on client and `useEffect` on server. | Use inside hooks that need layout behavior without SSR warnings. |
+| `useLocalStorage` | Persistent state in `localStorage`. | Returns `[value, setValue, removeValue]`. Supports custom serializer/deserializer and `initializeWithValue`. |
+| `useMap` | React state around a `Map`. | Use when callers need `set`, `remove`, `reset`, or map-like state updates. |
+| `useMediaQuery` | Match media query state. | Options: `defaultValue`, `initializeWithValue`. Uses legacy `addListener` fallback for older Safari. |
+| `useOnClickOutside` | Dismiss popovers, menus, dialogs when clicking outside one or more refs. | Supports mouse, touch, focus events, and listener options. |
+| `useReadLocalStorage` | Read-only subscription to a `localStorage` key. | Use when a component should react to storage changes but not write. |
+| `useResizeObserver` | Observing element size changes. | Pass `{ ref, box, onResize }`. If `onResize` is set, the hook does not rerender for size changes. |
+| `useScreen` | Tracking `window.screen` dimensions and properties. | SSR-sensitive. Prefer `initializeWithValue: false` when server rendered. |
+| `useScript` | Loading an external script and tracking status. | Returns `idle`, `loading`, `ready`, or `error`. Mounts scripts in `document.body`. |
+| `useScrollLock` | Locking page or element scroll, usually for overlays. | Returns `{ isLocked, lock, unlock }`. Defaults to auto-locking `document.body`. |
+| `useSessionStorage` | Persistent state in `sessionStorage`. | Same shape as `useLocalStorage`: `[value, setValue, removeValue]`. |
+| `useStep` | Multi-step workflows. | Use for bounded step navigation. Check max step behavior in the hook before assuming wraparound. |
+| `useTernaryDarkMode` | `system`, `dark`, `light` theme mode. | Returns `{ isDarkMode, ternaryDarkMode, setTernaryDarkMode, toggleTernaryDarkMode }`. |
+| `useTimeout` | Timeouts with fresh callback semantics. | Pass `null` delay to stop. |
+| `useToggle` | Boolean toggle state. | Simpler than `useBoolean`; use when only value and toggling are needed. |
+| `useUnmount` | Running cleanup when component unmounts. | Often used to cancel pending debounced callbacks or subscriptions. |
+| `useWindowSize` | Tracking viewport width and height. | Options include `initializeWithValue` and `debounceDelay`. |
+
+## Removed v2 Hooks And Replacements
+
+- `useDebounce`: use `useDebounceValue` for debounced state or `useDebounceCallback` for debounced functions.
+- `useElementSize`: use `useResizeObserver`.
+- `useLockedBody`: use `useScrollLock`.
+- `useFetch`: use framework data fetching, Server Components, loaders, SWR, React Query, or another cache-aware approach.
+- `useIsFirstRender`: avoid. Prefer explicit state/effect logic.
+- `useSsr`: avoid. It was not a hook.
+- `useEffectOnce` and `useUpdateEffect`: prefer built-in React effects with clear dependencies.
+- `useImageOnLoad`: avoid or implement app-specific image behavior.
+
+## Import Guidance
+
+Use package-root named imports:
+
+```tsx
+import { useBoolean, useLocalStorage } from 'usehooks-ts'
+```
+
+Avoid these patterns:
+
+```tsx
+import useBoolean from 'usehooks-ts'
+import { useBoolean } from 'usehooks-ts/dist/useBoolean'
+```
+
+## Choosing Between Similar Hooks
+
+- `useToggle` vs `useBoolean`: use `useToggle` for a compact boolean toggle; use `useBoolean` when explicit `setTrue` and `setFalse` improve call-site clarity.
+- `useLocalStorage` vs `useReadLocalStorage`: use `useLocalStorage` when the component owns writes; use `useReadLocalStorage` for passive readers.
+- `useDarkMode` vs `useTernaryDarkMode`: use `useDarkMode` for boolean dark/light; use `useTernaryDarkMode` when the user can choose system preference.
+- `useWindowSize` vs `useMediaQuery`: use `useMediaQuery` for layout breakpoints; use `useWindowSize` when exact dimensions are needed.
+- `useResizeObserver` vs `useWindowSize`: use `useResizeObserver` for element dimensions; use `useWindowSize` for viewport dimensions.
+- `useEventListener` vs React `onClick`: use React props for component-local events; use `useEventListener` for window, document, refs, media query lists, or dynamic external targets.
diff --git a/skills/usehooks-ts/references/ssr-frameworks.md b/skills/usehooks-ts/references/ssr-frameworks.md
new file mode 100644
index 00000000..a06f5eab
--- /dev/null
+++ b/skills/usehooks-ts/references/ssr-frameworks.md
@@ -0,0 +1,148 @@
+# SSR And Framework Guidance
+
+Use this file for Next.js, Remix, Astro, Gatsby, React Server Components, server rendering, or hydration problems.
+
+## Next.js App Router
+
+Components that call `usehooks-ts` hooks are client components:
+
+```tsx
+'use client'
+
+import { useLocalStorage } from 'usehooks-ts'
+
+export function Preferences() {
+  const [theme, setTheme] = useLocalStorage('theme', 'system', {
+    initializeWithValue: false,
+  })
+
+  return <button onClick={() => setTheme('dark')}>{theme}</button>
+}
+```
+
+Keep data fetching and static content in Server Components. Move only interactive behavior into a client child:
+
+```tsx
+// Server component
+import { PreferencesClient } from './preferences-client'
+
+export default async function SettingsPage() {
+  const settings = await loadSettings()
+  return <PreferencesClient initialName={settings.name} />
+}
+```
+
+## Hydration-Sensitive Hooks
+
+Use `initializeWithValue: false` when the server cannot know the client value and mismatched markup would matter:
+
+- `useLocalStorage`
+- `useSessionStorage`
+- `useReadLocalStorage`
+- `useMediaQuery`
+- `useWindowSize`
+- `useScreen`
+- `useDarkMode`
+- `useTernaryDarkMode`
+
+Use `defaultValue` where available to keep first render deterministic:
+
+```tsx
+const prefersDesktop = useMediaQuery('(min-width: 1024px)', {
+  defaultValue: false,
+  initializeWithValue: false,
+})
+```
+
+## Browser-Only APIs
+
+These hooks depend on browser APIs and should not be called in Server Components:
+
+- Clipboard: `useCopyToClipboard`
+- DOM events: `useEventListener`, `useOnClickOutside`, `useClickAnyWhere`, `useHover`
+- Observers: `useResizeObserver`, `useIntersectionObserver`
+- Window/screen/media: `useWindowSize`, `useScreen`, `useMediaQuery`
+- Storage: `useLocalStorage`, `useSessionStorage`, `useReadLocalStorage`
+- Document/script/scroll: `useDocumentTitle`, `useScript`, `useScrollLock`
+
+If a page needs server output plus browser behavior, split files. The server file imports a client component; the client component imports `usehooks-ts`.
+
+## Storage Hooks
+
+Storage hooks serialize with JSON by default:
+
+```tsx
+const [filters, setFilters, clearFilters] = useLocalStorage(
+  'filters',
+  { sort: 'recent' },
+  { initializeWithValue: false },
+)
+```
+
+Use custom serializers for non-plain values:
+
+```tsx
+const [lastSeen, setLastSeen] = useLocalStorage<Date>(
+  'last-seen',
+  new Date(0),
+  {
+    initializeWithValue: false,
+    serializer: value => value.toISOString(),
+    deserializer: value => new Date(value),
+  },
+)
+```
+
+Use stable, namespaced keys:
+
+```tsx
+const key = `acme:dashboard:${userId}:filters`
+```
+
+When a value includes user or tenant scope, include that scope in the key or reset state when the scope changes.
+
+## Media And Layout
+
+Prefer CSS for pure styling. Use hooks only when JavaScript logic must change:
+
+- Use CSS media queries for layout and visibility.
+- Use `useMediaQuery` when component behavior or data changes by breakpoint.
+- Use `useWindowSize` for exact viewport measurement.
+- Use `useResizeObserver` for element measurement.
+
+Avoid rendering entirely different server markup based on client-only viewport values. If necessary, render a neutral shell first, then enhance after hydration.
+
+## External Scripts
+
+Use `useScript` when a component must load a script and react to load status:
+
+```tsx
+const status = useScript('https://example.com/widget.js', {
+  id: 'example-widget',
+  removeOnUnmount: true,
+})
+```
+
+The package hook appends to `document.body`. If the script must be mounted inside a specific container, write a local hook or component for that vendor.
+
+## Dark Mode
+
+For simple dark/light state:
+
+```tsx
+const { isDarkMode, toggle } = useDarkMode({
+  initializeWithValue: false,
+})
+```
+
+For user-selectable system/dark/light:
+
+```tsx
+const {
+  isDarkMode,
+  ternaryDarkMode,
+  setTernaryDarkMode,
+} = useTernaryDarkMode({ initializeWithValue: false })
+```
+
+The hooks return state and controllers; they do not automatically apply a `class="dark"` policy to your app. Apply the returned state to your theme provider, document class, or design system convention.
diff --git a/skills/usehooks-ts/references/testing-pitfalls.md b/skills/usehooks-ts/references/testing-pitfalls.md
new file mode 100644
index 00000000..667306a4
--- /dev/null
+++ b/skills/usehooks-ts/references/testing-pitfalls.md
@@ -0,0 +1,138 @@
+# Testing, Migration, And Pitfalls
+
+Use this file when adding tests, reviewing existing usage, or migrating old code.
+
+## Testing Hooks And Components
+
+Use the app's existing test runner. With Testing Library:
+
+```tsx
+import { act, renderHook } from '@testing-library/react'
+import { useBoolean } from 'usehooks-ts'
+
+it('toggles', () => {
+  const { result } = renderHook(() => useBoolean(false))
+
+  act(() => {
+    result.current.toggle()
+  })
+
+  expect(result.current.value).toBe(true)
+})
+```
+
+Use fake timers for timer and debounce hooks:
+
+```tsx
+vi.useFakeTimers()
+
+const callback = vi.fn()
+renderHook(() => useTimeout(callback, 500))
+
+act(() => {
+  vi.advanceTimersByTime(500)
+})
+
+expect(callback).toHaveBeenCalled()
+```
+
+Always restore timers after the test if the project setup does not do it globally.
+
+## Browser API Mocks
+
+Mock `matchMedia` for `useMediaQuery`, `useDarkMode`, and `useTernaryDarkMode`:
+
+```tsx
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })),
+})
+```
+
+Mock storage when jsdom behavior is insufficient or when isolation matters:
+
+```tsx
+window.localStorage.clear()
+```
+
+Mock observers for `useResizeObserver` and `useIntersectionObserver`:
+
+```tsx
+class ResizeObserverMock {
+  observe = vi.fn()
+  unobserve = vi.fn()
+  disconnect = vi.fn()
+}
+
+window.ResizeObserver = ResizeObserverMock as unknown as typeof ResizeObserver
+```
+
+Mock clipboard:
+
+```tsx
+Object.assign(navigator, {
+  clipboard: {
+    writeText: vi.fn().mockResolvedValue(undefined),
+  },
+})
+```
+
+## Common Pitfalls
+
+- Missing `'use client'` in Next.js App Router files that call hooks.
+- Rendering viewport, media query, storage, or screen values on the server without `initializeWithValue: false`.
+- Assuming JSON serialization preserves `Date`, `Map`, `Set`, class instances, functions, or `undefined` in nested structures.
+- Using `useWindowSize` for style-only responsive UI that CSS can handle better.
+- Using `useOnClickOutside` when the target ref can be `null` forever; ensure the element actually receives the ref.
+- Forgetting that clipboard and external script behavior can fail because of browser policy, network, CSP, or secure-context requirements.
+- Recreating listener options objects inline in hot paths when it causes unnecessary add/remove cycles.
+- Using old removed hooks from v2 examples.
+
+## Migration Replacements
+
+Use these replacements when old code or blog examples mention removed hooks:
+
+```tsx
+// old: useDebounce(value, delay)
+const [debouncedValue] = useDebounceValue(value, delay)
+
+// old: useDebounce(callback, delay)
+const debouncedCallback = useDebounceCallback(callback, delay)
+```
+
+```tsx
+// old: useElementSize(ref)
+const size = useResizeObserver({ ref })
+```
+
+```tsx
+// old: useLockedBody()
+const { lock, unlock, isLocked } = useScrollLock()
+```
+
+For old `useFetch`, choose a project-native data layer instead of rebuilding it with hooks:
+
+- Next.js Server Components or route handlers
+- Remix loaders and actions
+- SWR
+- TanStack Query
+- Apollo, Relay, urql, or the app's existing GraphQL/data client
+
+## Review Checklist
+
+- The package is imported from `usehooks-ts` as named exports.
+- The file is a Client Component when using Next.js App Router.
+- SSR-sensitive hooks use deterministic first-render options when needed.
+- Storage keys are stable and scoped correctly.
+- Non-JSON values have custom serialization.
+- Timer, debounce, observer, and event behavior has focused tests when business-critical.
+- Accessibility behavior still exists around interactive UI: focus management, Escape key, ARIA roles, keyboard access, and reduced-motion expectations where relevant.

From 41e914f13279b8167bc20111f012e4f018c8ff22 Mon Sep 17 00:00:00 2001
From: MAnasLatif <104300600+MAnasLatif@users.noreply.github.com>
Date: Fri, 1 May 2026 03:49:46 +0500
Subject: [PATCH 2/3] feat: Add new agent YAML files and audit script for
 usehooks-ts integration issues

---
 skills/usehooks-ts/agents/aider.yaml          |  21 ++
 skills/usehooks-ts/agents/claude-code.yaml    |  21 ++
 skills/usehooks-ts/agents/cline.yaml          |  21 ++
 skills/usehooks-ts/agents/codex.yaml          |  21 ++
 skills/usehooks-ts/agents/copilot.yaml        |  21 ++
 skills/usehooks-ts/agents/cursor.yaml         |  21 ++
 skills/usehooks-ts/agents/gemini.yaml         |  21 ++
 skills/usehooks-ts/agents/generic.yaml        |  21 ++
 skills/usehooks-ts/agents/openai.yaml         |  21 ++
 skills/usehooks-ts/agents/roo-code.yaml       |  21 ++
 skills/usehooks-ts/agents/windsurf.yaml       |  21 ++
 .../scripts/audit_usehooks_ts_usage.py        | 211 ++++++++++++++++++
 12 files changed, 442 insertions(+)
 create mode 100644 skills/usehooks-ts/agents/aider.yaml
 create mode 100644 skills/usehooks-ts/agents/claude-code.yaml
 create mode 100644 skills/usehooks-ts/agents/cline.yaml
 create mode 100644 skills/usehooks-ts/agents/codex.yaml
 create mode 100644 skills/usehooks-ts/agents/copilot.yaml
 create mode 100644 skills/usehooks-ts/agents/cursor.yaml
 create mode 100644 skills/usehooks-ts/agents/gemini.yaml
 create mode 100644 skills/usehooks-ts/agents/generic.yaml
 create mode 100644 skills/usehooks-ts/agents/openai.yaml
 create mode 100644 skills/usehooks-ts/agents/roo-code.yaml
 create mode 100644 skills/usehooks-ts/agents/windsurf.yaml
 create mode 100644 skills/usehooks-ts/scripts/audit_usehooks_ts_usage.py

diff --git a/skills/usehooks-ts/agents/aider.yaml b/skills/usehooks-ts/agents/aider.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/aider.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/claude-code.yaml b/skills/usehooks-ts/agents/claude-code.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/claude-code.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/cline.yaml b/skills/usehooks-ts/agents/cline.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/cline.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/codex.yaml b/skills/usehooks-ts/agents/codex.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/codex.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/copilot.yaml b/skills/usehooks-ts/agents/copilot.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/copilot.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/cursor.yaml b/skills/usehooks-ts/agents/cursor.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/cursor.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/gemini.yaml b/skills/usehooks-ts/agents/gemini.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/gemini.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/generic.yaml b/skills/usehooks-ts/agents/generic.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/generic.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/openai.yaml b/skills/usehooks-ts/agents/openai.yaml
new file mode 100644
index 00000000..2c1cffd8
--- /dev/null
+++ b/skills/usehooks-ts/agents/openai.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use $usehooks-ts to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/roo-code.yaml b/skills/usehooks-ts/agents/roo-code.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/roo-code.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/agents/windsurf.yaml b/skills/usehooks-ts/agents/windsurf.yaml
new file mode 100644
index 00000000..a6d3aa86
--- /dev/null
+++ b/skills/usehooks-ts/agents/windsurf.yaml
@@ -0,0 +1,21 @@
+interface:
+  display_name: "usehooks-ts"
+  short_description: "Use React hooks from usehooks-ts well"
+  default_prompt: "Use the usehooks-ts skill at ../SKILL.md to choose and integrate the right React hook for this component."
+skill:
+  name: "usehooks-ts"
+  entrypoint: "../SKILL.md"
+  references:
+    - "../references/hook-catalog.md"
+    - "../references/ssr-frameworks.md"
+    - "../references/composition-recipes.md"
+    - "../references/testing-pitfalls.md"
+  scripts:
+    - "../scripts/audit_usehooks_ts_usage.py"
+  triggers:
+    - "usehooks-ts"
+    - "React hooks"
+    - "Next.js hydration"
+    - "localStorage hook"
+    - "debounce hook"
+    - "media query hook"
diff --git a/skills/usehooks-ts/scripts/audit_usehooks_ts_usage.py b/skills/usehooks-ts/scripts/audit_usehooks_ts_usage.py
new file mode 100644
index 00000000..9597e8c3
--- /dev/null
+++ b/skills/usehooks-ts/scripts/audit_usehooks_ts_usage.py
@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Audit common usehooks-ts integration issues in a React project."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+IGNORE_DIRS = {
+    ".git",
+    ".next",
+    ".turbo",
+    "build",
+    "coverage",
+    "dist",
+    "generated",
+    "node_modules",
+    "out",
+}
+
+SOURCE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx", ".mdx"}
+
+REMOVED_HOOKS = {
+    "useDebounce": "useDebounceValue or useDebounceCallback",
+    "useElementSize": "useResizeObserver",
+    "useFetch": "framework data fetching, SWR, or TanStack Query",
+    "useLockedBody": "useScrollLock",
+    "useIsFirstRender": "explicit state/effect logic",
+    "useSsr": "framework SSR/client boundaries",
+    "useEffectOnce": "React useEffect",
+    "useUpdateEffect": "React useEffect with explicit guards",
+    "useImageOnLoad": "app-specific image loading behavior",
+}
+
+SSR_SENSITIVE_HOOKS = {
+    "useLocalStorage",
+    "useSessionStorage",
+    "useReadLocalStorage",
+    "useMediaQuery",
+    "useWindowSize",
+    "useScreen",
+    "useDarkMode",
+    "useTernaryDarkMode",
+}
+
+IMPORT_STATEMENT_RE = re.compile(
+    r"import\s+[\s\S]*?\s+from\s+['\"][^'\"]+['\"]\s*;?",
+    re.MULTILINE,
+)
+
+FROM_RE = re.compile(
+    r"import\s+(?P<clause>[\s\S]*?)\s+from\s+['\"](?P<source>usehooks-ts[^'\"]*)['\"]",
+    re.MULTILINE,
+)
+
+NAMED_IMPORT_RE = re.compile(r"\{(?P<named>[\s\S]*?)\}")
+
+
+@dataclass
+class Finding:
+    severity: str
+    path: Path
+    message: str
+
+
+def iter_source_files(root: Path):
+    for path in root.rglob("*"):
+        if path.is_dir():
+            continue
+        if any(part in IGNORE_DIRS for part in path.parts):
+            continue
+        if path.suffix in SOURCE_EXTENSIONS:
+            yield path
+
+
+def has_use_client_directive(text: str) -> bool:
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("//"):
+            continue
+        return line in {"'use client'", '"use client"', "'use client';", '"use client";'}
+    return False
+
+
+def is_next_app_file(path: Path) -> bool:
+    normalized = path.as_posix()
+    return "/app/" in normalized or normalized.startswith("app/")
+
+
+def parse_named_imports(clause: str) -> set[str]:
+    match = NAMED_IMPORT_RE.search(clause)
+    if not match:
+        return set()
+    names = set()
+    for item in match.group("named").split(","):
+        raw = item.strip()
+        if not raw:
+            continue
+        name = raw.split(" as ")[0].strip()
+        if name.startswith("type "):
+            name = name.removeprefix("type ").strip()
+        names.add(name)
+    return names
+
+
+def audit_file(path: Path, root: Path) -> list[Finding]:
+    rel = path.relative_to(root)
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    findings: list[Finding] = []
+
+    matches = []
+    for statement in IMPORT_STATEMENT_RE.finditer(text):
+        match = FROM_RE.search(statement.group(0))
+        if match:
+            matches.append(match)
+    if not matches:
+        return findings
+
+    imported_hooks: set[str] = set()
+
+    for match in matches:
+        source = match.group("source")
+        clause = match.group("clause")
+
+        if source != "usehooks-ts":
+            findings.append(
+                Finding(
+                    "error",
+                    rel,
+                    f"Deep import from '{source}'. Import named hooks from 'usehooks-ts'.",
+                )
+            )
+
+        normalized_clause = clause.strip().removeprefix("type ").strip()
+        if normalized_clause and not normalized_clause.startswith("{"):
+            findings.append(
+                Finding(
+                    "warning",
+                    rel,
+                    "Possible default or namespace import. Prefer named imports from 'usehooks-ts'.",
+                )
+            )
+
+        imported_hooks.update(parse_named_imports(clause))
+
+    for hook, replacement in sorted(REMOVED_HOOKS.items()):
+        if hook in imported_hooks:
+            findings.append(
+                Finding(
+                    "error",
+                    rel,
+                    f"{hook} was removed from v3. Use {replacement}.",
+                )
+            )
+
+    if is_next_app_file(rel) and not has_use_client_directive(text):
+        findings.append(
+            Finding(
+                "warning",
+                rel,
+                "Next.js App Router file imports usehooks-ts but lacks a top-level 'use client' directive.",
+            )
+        )
+
+    sensitive_used = imported_hooks & SSR_SENSITIVE_HOOKS
+    if sensitive_used and "initializeWithValue" not in text:
+        hooks = ", ".join(sorted(sensitive_used))
+        findings.append(
+            Finding(
+                "info",
+                rel,
+                f"SSR-sensitive hook(s) used without visible initializeWithValue option: {hooks}. Check hydration behavior.",
+            )
+        )
+
+    return findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Audit common usehooks-ts usage issues in a project."
+    )
+    parser.add_argument("root", nargs="?", default=".", help="Project root to scan")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    if not root.exists():
+        parser.error(f"Path does not exist: {root}")
+
+    findings: list[Finding] = []
+    for path in iter_source_files(root):
+        findings.extend(audit_file(path, root))
+
+    if not findings:
+        print("No obvious usehooks-ts issues found.")
+        return 0
+
+    order = {"error": 0, "warning": 1, "info": 2}
+    findings.sort(key=lambda item: (order.get(item.severity, 99), str(item.path)))
+
+    for finding in findings:
+        print(f"[{finding.severity.upper()}] {finding.path}: {finding.message}")
+
+    return 1 if any(item.severity == "error" for item in findings) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From ca993f60a7425cbea80d6c16b473de2b3671b514 Mon Sep 17 00:00:00 2001
From: MAnasLatif <104300600+MAnasLatif@users.noreply.github.com>
Date: Fri, 1 May 2026 03:49:53 +0500
Subject: [PATCH 3/3] feat: Add AI Agent Skill section to README with
 installation instructions

---
 README.md                      | 19 +++++++++++++++++++
 packages/usehooks-ts/README.md | 19 +++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 48dc0486..1ffc2e2a 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,25 @@ function Component() {
 }
 ```
 
+## 🤖 AI Agent Skill
+
+This repository includes a `usehooks-ts` skill for AI coding agents. Install it
+with the [skills.sh](https://skills.sh) CLI:
+
+```shell
+npx skills add https://github.com/juliencrn/usehooks-ts --skill usehooks-ts
+```
+
+From a local checkout, you can install the bundled skill directly:
+
+```shell
+npx skills add ./skills/usehooks-ts
+```
+
+Agent metadata is included in `skills/usehooks-ts/agents` for OpenAI, Codex,
+Claude Code, Cursor, Windsurf, Gemini, Copilot, Aider, Cline, Roo Code, and
+generic agent loaders.
+
 ## 🪝 Available Hooks
 
 <!-- HOOKS:START -->
diff --git a/packages/usehooks-ts/README.md b/packages/usehooks-ts/README.md
index 48dc0486..1ffc2e2a 100644
--- a/packages/usehooks-ts/README.md
+++ b/packages/usehooks-ts/README.md
@@ -51,6 +51,25 @@ function Component() {
 }
 ```
 
+## 🤖 AI Agent Skill
+
+This repository includes a `usehooks-ts` skill for AI coding agents. Install it
+with the [skills.sh](https://skills.sh) CLI:
+
+```shell
+npx skills add https://github.com/juliencrn/usehooks-ts --skill usehooks-ts
+```
+
+From a local checkout, you can install the bundled skill directly:
+
+```shell
+npx skills add ./skills/usehooks-ts
+```
+
+Agent metadata is included in `skills/usehooks-ts/agents` for OpenAI, Codex,
+Claude Code, Cursor, Windsurf, Gemini, Copilot, Aider, Cline, Roo Code, and
+generic agent loaders.
+
 ## 🪝 Available Hooks
 
 <!-- HOOKS:START -->