Skip to content
Skills Library
Programming · Building & coding

client-methods

/client-methods

Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.

Original author description

Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.

How it works

  1. Rule
  2. Why
  3. How
  4. Exceptions
  5. Don't
  6. Related Skills
  7. References
Original SKILL.md headings · 107 lines, 583 words
SKILL.md preview
---
name: client-methods
description: >-
  Client method surface rules. Use when wiring browser/client code to actions,
  application state, framework routes, app APIs, uploads, auth, or settings.
scope: dev
metadata:
  internal: true
---

# Client Methods

## Rule

Browser/client code imports named methods, hooks, or client modules instead of
hand-writing REST calls to framework or app routes.

## Why

Route shapes are transport details. If components and docs call
`fetch("/_agent-native/...")` or template `/api/*` routes directly, every caller
has to rediscover auth, base paths, request-source headers, JSON parsing, error
handling, optimistic updates, sync invalidation, and route quirks. A named client
method gives the UI, docs, and future agents one stable contract.

## How

1. Look for an existing client API first.

   | Need | Use |
   | --- | --- |
   | App action reads/writes | `useActionQuery` / `useActionMutation` from `@agent-native/core/client/hooks` |
   | Imperative action calls | `callAction` from `@agent-native/core/client/hooks` |
   | Browser application state | `readClientAppState`, `writeClientAppState`, `setClientAppState`, `deleteClientAppState` from `@agent-native/core/client/hooks` |
   | Navigation/app-state sync | `useAgentRouteState` / `useSemanticNavigationState` from `@agent-native/core/client/navigation` |
   | Agent chat context | Agent chat helpers from `@agent-native/core/client/agent-chat` |
   | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client/agent-chat` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
   | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` from `@agent-native/core/client/hooks` |
   | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |

   Action fetch behavior: every `useActionQuery` / `useActionMutation` /
   `callAction` request is bounded by a 60s timeout, and timeouts surface as
   errors instead of retrying silently. `useActionQuery` cancels superseded
   requests automatically via React Query's abort signal. For imperative
   calls, `callAction(name, params, { method, signal, timeoutMs })` accepts an
   `AbortSignal` and a `timeoutMs` override for legitimately long operations.

2. If no client API exists, add the narrowest helper at the boundary.

   - Put shared framework helpers in `packages/core/src/client/*`.
   - Put template-local helpers in `templates/<app>/app/hooks/*`,
     `templates/<app>/app/lib/*`, or an existing local client module.
   - Export reusable core helpers from the focused `@agent-native/core/client/*`
     entry for their domain. Never recommend the deprecated broad
     `@agent-native/core/client` barrel in new code.
   - Keep raw `fetch`, `agentNativePath`, and route paths inside that helper,
     not scattered through components or docs.
   - Add focused tests for URL construction, headers, response parsing, error
     shape, and any sync invalidation.

3. Teach the helper, not the route.

   Docs, skills, examples, and generated code should show:

   ```ts
   await setClientAppState("selection", selection, { keepalive: true });
   ```

   not:

   ```ts
   await fetch("/_agent-native/application-state/selection", {
     method: "PUT",
     body: JSON.stringify(selection),
   });
   ```

## Exceptions

Raw route calls are acceptable only inside low-level client helpers or for
route-shaped protocols that cannot be hidden cleanly:

- multipart uploads
- streaming/SSE/WebSocket transports
- OAuth redirects and callback URL construction
- webhooks and external provider callbacks
- extension sandbox `appFetch` / `extensionFetch`, which are themselves exposed
  client methods
- tests that assert route construction

Even for exceptions, prefer a named helper as soon as more than one caller needs
the behavior.

## Don't

- Don't put `fetch("/_agent-native/...")`, `fetch(agentNativePath(...))`, or
  template `/api/*` calls directly in React components for normal app data,
  actions, settings, or application state.
- Don't document route calls as the way client code should do work.
- Don't add pass-through `/api/*` routes just to make client fetches look
  simpler; expose an action and call it with action hooks.
- Don't duplicate auth/session/base-path/request-source/error parsing logic in
  every component.

## Related Skills

- `actions` — app operations shared by UI and agent.
- `context-awareness` — application-state navigation and selection helpers.
- `real-time-sync` — keeping helper-backed UI reads fresh.
- `server-plugins` — when a new route is actually warranted.

## References

- `references/legacy-client-fetch-audit-2026-06-03.md` — known legacy cleanup
  targets found when this rule was added.
Files in this package (2)
  • SKILL.md 5 KB
  • references/legacy-client-fetch-audit-2026-06-03.md 3 KB

Versions

The database has no other skills named client-methods.

Database snapshot: 13.11.2026 · package version 6bf3de20a2cb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-check
    Compare frontend API requests and consumers with backend routes to find mismatches in methods, paths, field names, response shapes, and error handling. Use for API integration reviews and debugging frontend/backend contract incompatibilities; report exact mismatches with file references.
  • 100nextjs-code-review
    Provides comprehensive code review capability for Next.js applications, validates Server Components, Client Components, Server Actions, caching strategies, metadata, API routes, middleware, and performance patterns. Use when reviewing Next.js App Router code changes, before…
  • 100nextjs-app-router
    Builds and reviews Next.js App Router code - server/client component boundaries, data fetching, caching and revalidation choices, streaming with Suspense, and Server Action mutations - and delivers routes where every dynamic-vs-cached decision is explicit. Use when someone asks…
  • 100nextjs
    Use when building Next.js applications with the App Router. Covers server and client component boundaries, data fetching and caching, server actions, streaming, and rendering strategy. Trigger on "server or client component", "page shows stale data after a mutation", "route is…
  • 95nextjs-expert
    Comprehensive Next.js expertise across App Router, server/client boundaries, data and caching patterns, and production operations. Use when building, debugging, or optimizing a Next.js app, deciding server vs client components, or resolving App Router gotchas.
  • 100nextjs-client-audit
    Audit a Next.js App Router project for unnecessary or misplaced "use client" directives, measure how much code each one drags into the browser bundle, and give a concrete, safe fix (REMOVE, PUSH_DOWN, CHILDREN_PATTERN, MOVE_FETCH) with Before/After code from the user's own…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.