Qwik Core Development
Use this skill for packages/qwik/** work. Keep the normal repo-wide instructions from .ruler/AGENTS.md in force.
Fast Path
- Identify the touched subsystem before editing: reactive primitives, VNode/client diffing, cursor, QRL/serialization, SSR, hooks, or tests.
- Read the smallest relevant source and tests before making changes.
- Find the invariant that must stay true across SSR, resume, client render, and serialization when
the touched code crosses those boundaries.
- After implementation changes, immediately run the closest focused Vitest file with
pnpm vitest run <path>. Do not use pnpm test.unit.
- If touching Rust optimizer code, load
qwik-optimizer-development instead of treating the change as TypeScript-only.
When to Load Detailed Notes
Read references/core-notes.md only when the task involves:
- async signals, computed signals, polling, or signal invalidation;
- QRL creation,
$ transform behavior, or serialization issues;
- VNode, cursor, or DOM diff behavior;
- Qwik core tests that use
$(), retryOnPromise, or private runtime state;
- an unfamiliar pattern in
packages/qwik/src/core.
Do not load the reference for simple docs, package metadata, formatting, or unrelated monorepo work.
Core Reminders
- Prefer existing Qwik runtime patterns over new abstractions.
- Keep state ownership explicit. For serialized or streamed data, update emit and consume paths
together and add a round-trip or regression test.
- Preserve compatibility deliberately. If deprecated input remains accepted, test both deprecated and
current behavior.
- Use
$-suffixed functions and $() in tests when a QRL boundary is expected.
- Avoid manual QRL construction unless nearby code already does it for the same reason.
- Keep tests focused and close to the behavior that changed; add e2e coverage only when browser,
streaming, navigation, or integration timing is the behavior under test.
- If the change affects public API, run
pnpm api.update after the focused tests pass.
- If this skill or
references/core-notes.md is stale after your source inspection, update it before
finishing or record why guidance edits were out of scope.
1---2name: qwik-core-development3description: Use when modifying or reviewing Qwik core package code under packages/qwik, especially reactive primitives, signals, VNodes, cursor behavior, QRLs, optimizer-facing runtime behavior, or Qwik core tests.4---56# Qwik Core Development78Use this skill for `packages/qwik/**` work. Keep the normal repo-wide instructions from `.ruler/AGENTS.md` in force.910## Fast Path11121. Identify the touched subsystem before editing: reactive primitives, VNode/client diffing, cursor, QRL/serialization, SSR, hooks, or tests.132. Read the smallest relevant source and tests before making changes.143. Find the invariant that must stay true across SSR, resume, client render, and serialization when15 the touched code crosses those boundaries.164. After implementation changes, immediately run the closest focused Vitest file with `pnpm vitest run <path>`. Do not use `pnpm test.unit`.175. If touching Rust optimizer code, load `qwik-optimizer-development` instead of treating the change as TypeScript-only.1819## When to Load Detailed Notes2021Read `references/core-notes.md` only when the task involves:2223- async signals, computed signals, polling, or signal invalidation;24- QRL creation, `$` transform behavior, or serialization issues;25- VNode, cursor, or DOM diff behavior;26- Qwik core tests that use `$()`, `retryOnPromise`, or private runtime state;27- an unfamiliar pattern in `packages/qwik/src/core`.2829Do not load the reference for simple docs, package metadata, formatting, or unrelated monorepo work.3031## Core Reminders3233- Prefer existing Qwik runtime patterns over new abstractions.34- Keep state ownership explicit. For serialized or streamed data, update emit and consume paths35 together and add a round-trip or regression test.36- Preserve compatibility deliberately. If deprecated input remains accepted, test both deprecated and37 current behavior.38- Use `$`-suffixed functions and `$()` in tests when a QRL boundary is expected.39- Avoid manual QRL construction unless nearby code already does it for the same reason.40- Keep tests focused and close to the behavior that changed; add e2e coverage only when browser,41 streaming, navigation, or integration timing is the behavior under test.42- If the change affects public API, run `pnpm api.update` after the focused tests pass.43- If this skill or `references/core-notes.md` is stale after your source inspection, update it before44 finishing or record why guidance edits were out of scope.
qwikdev