Use when modifying anything under features/files/, app/(core)/files/, app/(public)/share/, or any caller that uploads, downloads, lists, moves, renames, shares, or previews user files.
インストールする前に、エージェントに与えられる指示の中身を確認できます。
This skill enforces the architecture established in features/files/FEATURE.md. Read it first. This skill is the checklist version.
cloud_get_user_file_tree. No REST calls for reads unless the endpoint returns bytes.cloudFiles Redux slice. No local useState for file data. No new Redux slices for files — extend the existing one.fileId. Never cache by file_path — paths move with renames.requestId on every mutation.Drawer not Dialog; push-nav not tabs; dvh not vh; pb-safe on fixed bottoms; 16px inputs.FieldFlags<K> not Set<K> in Redux state (JSON-serializability).app/(core)/files/ routes follow app/(core)/_read_first_route_rules/RULES.md. SSR-first, zero layout shift; 'use cache' is NOT available (cacheComponents off — see CLAUDE.md).Read, in this order:
/Users/armanisadeghi/code/common-docs/systems/files/file-service/WIRE_CONTRACT.md — the backend contract (routes, shapes, quotas, TUS, share tokens).For route work under app/(core)/files/, additionally run these skills before writing code:
.claude/skills/nextjs-ssr-architecture/SKILL.md.claude/skills/ssr-zero-layout-shift/SKILL.md.claude/skills/ios-mobile-first/SKILL.md (for any mobile branch)import { useAppDispatch } from '@/lib/redux/hooks';
import { uploadFiles } from '@/features/files/redux/thunks';
const dispatch = useAppDispatch();
await dispatch(
uploadFiles({ files: [file], parentFolderId, visibility: 'private' })
).unwrap();
<img> / <video>import { useMediaResolution } from "@ai-matrx/media/core";
// Prefer <InlineMediaRef ref={{ file_id }} /> from @ai-matrx/media/react.
const src = useMediaResolution(fileId).resolution?.src ?? null;
return <img src={src ?? undefined} />;
import { openFilePicker } from '@/features/files/components/pickers/FilePicker';
const [file] = await openFilePicker({ multi: false });
import { useFolderContents } from '@/features/files/hooks/useFolderContents';
const { files, folders, loading } = useFolderContents(folderId);
import { useSharing } from '@/features/files/hooks/useSharing';
const { createShareLink } = useSharing();
const link = await createShareLink(fileId, {
permission_level: 'read',
expires_at: '2026-12-31T23:59:59Z',
max_uses: 50,
});
// link.share_token → https://app.aidream.com/share/${link.share_token}
cloudFiles.CloudFile, CloudFolder, etc. Import from features/files/index.ts.window.alert / confirm / prompt. Use components/ui/alert-dialog.Dialog on mobile. Branch via useIsMobile() to Drawer.h-screen / vh under app/(core)/files/ — use dvh, --header-height, pb-safe.Set in Redux state. Use FieldFlags<K> from @ai-matrx/agents/field-flags.components/core/FileTree/internal/*. Consume from the barrel.requestId. The realtime middleware will not be able to dedup, and you will see visual flicker.| Symptom | Likely cause |
|---|---|
| Optimistic update flickers/reverts after a second | Missing requestId on the REST write. Realtime echo is overwriting state. |
| Uploads succeed but don't appear in tree | Realtime middleware not attached. Check <CloudFilesRealtimeProvider> is mounted under the user-scoped layout. |
| Signed URL returns 403 | Expired. Use useFileSrc (the handler's expiry-wheel auto-refreshes). Never cache raw signed URLs across mounts. |
| Tree shows stale state after reconnect | reconcileTree() dispatch missing from the realtime middleware's SUBSCRIBED-after-error handler. |
Type error on CloudFile.metadata | You're using an inline type somewhere. Delete it and import from types.ts. |
| 413 on upload | File >tier cap (or >100MB free). For >100MB uploads, use the TUS endpoint at /files/upload/tus (transport is chosen in upload/cloudUpload.ts). |
After any non-trivial change:
/Users/armanisadeghi/code/common-docs/systems/files/file-service/HANDOFF.md.Treat docs as weight-equal to code. Stale docs cascade across every future agent touching this system.
まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
Admin debug system wiring for the floating AdminIndicator's live debug data and Copy Full Context. Use when adding debug visibility to a route or feature, wiring useDebugContext or the debug panel, capturing console errors, or enabling the copy-context workflow for a page.
日本語の概要は準備中です。原文の説明を表示しています。
Compact two-icon Copy / Copy-for-AI controls (components/agent-copy). Use when adding copy buttons to a row, card, list, or record; merging duplicate Copy/JSON/AI controls; continuing the copy rollout; or writing a Copy-for-AI payload. NOT for markdown content actions (use rich-document-actions).
日本語の概要は準備中です。原文の説明を表示しています。
Disclosing a surface's existing fixed AI jobs in the shell's top Agents menu. Use when a page, panel, overlay, or window already runs a mandate behind a button, assist, automatic action, or mode; when the agent-disclosure guard names a file; or during a surface check.
日本語の概要は準備中です。原文の説明を表示しています。
The watch-fix-rerun method for making an existing platform agent or automated process efficient and correct: baseline its ledger, run one unit yourself, fix the class behind every wasted call, rerun, record. Use when asked to improve, optimize, watch, or 'make efficient' an agent, a sandbox session, a sync job, or any recurring automated process.
日本語の概要は準備中です。原文の説明を表示しています。
Redux state for agent execution and firing agent shortcuts. Use when editing features/agents/redux/, building agent UI, creating a conversation, touching assembleRequest or NDJSON stream state, wiring agent-state selectors, adding a per-conversation capability, or triggering a shortcut from a button, menu, or code (useShortcutTrigger, launchAgentExecution).
日本語の概要は準備中です。原文の説明を表示しています。
The provision for a call site: the exhaustive menu of values that place in the code can realistically produce. Use before creating or fixing a mandate or agent that reasons about more than its own input, when deciding whether an agent can answer at all with what it is sent, or when its output 'looks right' but nobody checked it could be. NOT for building the agent (use create-agent).
日本語の概要は準備中です。原文の説明を表示しています。