@skill-graph/cli 0.5.6

package/marketplace/skills/client-server-boundary/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: client-server-boundary
+description: "Use when reasoning about the line at which execution context changes between a server runtime and a client runtime: what values can cross via serialization, what cannot, the directives that mark transitions (`'use client'`, `'use server'`), the difference between server-rendered HTML and a serialized component tree, the trust model that treats client input as adversarial, and the consequences of leaking server-only modules into client bundles. Do NOT use for when and where the UI is produced (use rendering-models), the HTTP wire protocol itself (use http-semantics), how to organize the frontend codebase (use frontend-architecture), or how to design the JSON shape of an API endpoint (use api-design)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-15\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-15\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"client server boundary\\\\\\\",\\\\\\\"serialization boundary\\\\\\\",\\\\\\\"use client directive\\\\\\\",\\\\\\\"use server directive\\\\\\\",\\\\\\\"React Server Components\\\\\\\",\\\\\\\"server actions\\\\\\\",\\\\\\\"RPC\\\\\\\",\\\\\\\"serializable types\\\\\\\",\\\\\\\"structured clone\\\\\\\",\\\\\\\"secret leakage\\\\\\\",\\\\\\\"client bundle\\\\\\\",\\\\\\\"hydration boundary\\\\\\\"]\",\"triggers\":\"[\\\\\\\"can I pass this function as a prop\\\\\\\",\\\\\\\"why is my server-only module in the client bundle\\\\\\\",\\\\\\\"what does 'use client' actually do\\\\\\\",\\\\\\\"is it safe to put this secret in a server component\\\\\\\",\\\\\\\"why won't this Date / Map / class serialize\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a piece of data must cross the network or can stay server-only\\\\\\\",\\\\\\\"diagnose why a component marked as a server component is being shipped to the client\\\\\\\",\\\\\\\"review whether secrets in server code can leak through serialized props\\\\\\\",\\\\\\\"design which functions are exposed as server actions and which stay internal\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide whether a route should be SSG or SSR (use rendering-models)\\\\\\\",\\\\\\\"design HTTP authentication headers (use http-semantics)\\\\\\\",\\\\\\\"design the JSON shape of an API response body (use api-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"rendering-models\\\\\\\",\\\\\\\"http-semantics\\\\\\\",\\\\\\\"frontend-architecture\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"api-design\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"rendering-models\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"rendering-models owns the staging of work across build/request/stream/interaction. client-server-boundary owns the serialization frontier — what can cross between server code and client code. The two compose: any rendering model that emits a server-produced artifact for client consumption faces a boundary.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"http-semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"http-semantics owns the wire protocol (verbs, status codes, headers, caching). client-server-boundary is upstream — it decides what data exists at the boundary and how it is encoded into request and response bodies.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the external API surface (versioning, REST/GraphQL choice, endpoint shape). client-server-boundary owns the in-program boundary between a unified frontend codebase's server and client halves — a tighter, framework-mediated boundary than a public API.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety owns the discipline of compile-time type checking. client-server-boundary is one of the places where the type system stops — values crossing the boundary lose their type until parsed.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"type-safety\\\\\\\",\\\\\\\"api-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"The client-server boundary is to a unified codebase what an embassy boundary is to a city — both spaces exist in the same physical address, but inside the embassy the law of one country applies (server: full filesystem, secret access, database), outside the law of another applies (client: browser sandbox, no secrets), and everyone crossing must pass through documented customs (serialization) with their bags inspected (validation) and stamped (authentication).\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"The client-server boundary is the line in a unified codebase at which execution context changes — between a server runtime (full filesystem, secret access, database connections) and a client runtime (browser, no filesystem, no server secrets, untrusted by the server). Anything that crosses the boundary must be serialized: encoded as bytes on one side, decoded into a value on the other. The boundary is marked by directives, enforced by the framework, and made invisible to the developer who treats it correctly.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/client-server-boundary/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/client-server-boundary/SKILL.md
+---
+
+# Client-Server Boundary
+
+## Coverage
+
+The line in a unified codebase at which execution context changes between server and client. Covers the three governing properties (serialization, direction, trust), the wire formats currently in use (JSON, structured clone, RSC payload, FormData), the directives that mark the boundary (`'use client'`, `'use server'`, framework-specific equivalents), the trust asymmetry that makes client→server crossings categorically different from server→client, the leakage modes (server-only modules, secrets, hidden imports) that an unmarked boundary creates, and the misconceptions that arise from treating the boundary as either invisible or as a TypeScript-checked contract.
+
+## Philosophy
+
+The boundary always exists. Even an old PHP application with a templated HTML response has a server runtime and a client runtime separated by a wire protocol; the boundary is the network. What modern frameworks add is not the boundary itself, but the markers that make it visible — directives that say "this code is for over there" and serializers that say "these bytes will arrive on the other side as this shape."
+
+The discipline of the boundary is to take seriously the asymmetry between sides:
+
+- Server code can read secrets; client code cannot.
+- Server code receives requests; client code makes them.
+- Server code trusts itself; client code is trusted by the server only after validation.
+- Server code can import any module; client code can import only what the bundler shipped.
+
+A program that treats the two sides as interchangeable will leak secrets, ship broken code, and trust adversaries. A program that marks the boundary explicitly will pay a small upfront cost in ceremony and gain a large benefit in legibility and refactor safety.
+
+The goal of this skill is to make the boundary an object of explicit thought — not a thing to work around, but a thing to design with.
+
+## Directives — The Boundary Made Syntactic
+
+| Directive | Where it goes | What it means |
+|---|---|---|
+| `'use client'` | Top of a `.tsx` or `.ts` file | This file is the first client module in its import graph. Everything it imports becomes part of the client bundle. The framework will server-render it for first paint, then ship it to the client. |
+| `'use server'` | Top of a `.ts` file or first line of a function body | The functions in this file (or this specific function) become server actions — RPC handlers callable from the client. The function body executes on the server; the client invokes it via a network call. |
+| `import 'server-only'` | A line at the top of a server-intended module | A static import that causes the bundler to error if this module ends up in the client bundle. A guardrail, not a directive. |
+| `import 'client-only'` | A line at the top of a client-intended module | Symmetric: errors if the module ends up in the server bundle. Useful for code that touches `window`, `document`, or other browser-only globals. |
+
+The directives are not the boundary; they are the marks that make the boundary visible. A file without `'use client'` in an App Router project is implicitly a server component — the absence is meaningful.
+
+## Serialization — What Can Cross
+
+| Wire format | Allowed types | Disallowed types |
+|---|---|---|
+| Plain JSON | string, number, boolean, null, plain objects, arrays | undefined, functions, Dates (become strings), Maps, Sets, Symbols, BigInts, class instances, circular references |
+| Structured clone (postMessage, IndexedDB) | All JSON + Date, RegExp, Blob, File, FileList, ImageData, Map, Set, ArrayBuffer, typed arrays | Functions, DOM nodes, Error objects (partial), class instances with non-cloneable internals |
+| RSC payload (React Server Components) | All structured-clone + Promises, JSX trees, server-action function references (as opaque tokens) | Arbitrary closures, classes with private fields, host-environment-bound objects |
+| FormData (multipart/form-data) | string key/value, File/Blob | Nested structure (must encode as JSON inside a string field), non-string non-file values |
+
+The practical rule: **if you cannot describe the value in terms of bytes, it cannot cross.** A `Map<string, User>` can cross structured-clone but not JSON; serialize to an array of `[key, value]` pairs for JSON.
+
+## Trust — The Asymmetric Boundary
+
+The two directions across the boundary have categorically different trust profiles.
+
+**Server → client.** The server emits a payload. The payload is trusted by its producer (the server) and consumed as data by the client. The client cannot tamper with the payload in transit (TLS), but can read everything inside it and use the contents however the client code chooses.
+
+Implications:
+- Do not put server secrets in the payload. The client will see them.
+- Do not assume the client will *not* call a function in the payload. If the payload says "this user is an admin," the client UI may render an admin panel; if a security check depends on it, that check must be repeated on the server.
+- The payload is a window into the server's state model. Keep it minimal.
+
+**Client → server.** The client emits a request. The request crosses the trust boundary; every byte is adversarial. The server must:
+
+- Parse the request structurally (the bytes may not be the expected shape).
+- Validate the contents semantically (the values may not be in the expected range).
+- Authenticate the requester (cookies, tokens — themselves potentially forged).
+- Authorize the action (the authenticated requester may not have permission for this operation).
+- Rate-limit (the client may be a script).
+
+Server actions look like local function calls when invoked from a client component. They are not. They are RPC handlers with a network in front of them and a hostile caller on the other side of the network.
+
+## Common Leakage Modes
+
+| Leakage mode | What goes wrong | How to prevent |
+|---|---|---|
+| Secret in a shared module | `process.env.SECRET` is referenced in a module imported by both server and client; the secret name (and possibly value) ends up in the client bundle | Import the secret only in modules guarded by `import 'server-only'`; or read it inside a server action / route handler where the import graph cannot leak |
+| Server-only API in a client bundle | `fs.readFileSync` or `pg.Client` is imported into a `'use client'` component; build fails or runtime crashes | Mark client components with `'use client'`; mark server-only utilities with `import 'server-only'`; the bundler's static analysis catches the leak |
+| Untyped client→server validation gap | A server action accepts an argument typed as `{ userId: string }`; the client constructs a payload with `{ userId: 123 }`; the server crashes or, worse, queries with `123` and accidentally exposes another user's data | Validate every server-action argument with a runtime schema (Zod, valibot); never trust the TypeScript types of an RPC handler |
+| Trusted-by-default client claim | A server action checks `if (req.userRole === 'admin') ...` where `req.userRole` came from the client (via cookie, header, or body) | Re-derive trust from the server's authoritative source (the session record, the database, the IdP) — never from the client's self-report |
+| Non-serializable value in props | A `'use client'` component receives a server-built `Map<string, User>` as a prop; the RSC serializer can encode it, but a misconfigured project on plain JSON cannot — silent data loss or runtime crash | Test the serialization shape in code review; convert to plain objects at the boundary; or upgrade to a wire format that supports the type |
+| Closure leakage attempt | A server component constructs `() => doSomething()` and tries to pass it to a client component as a prop | Use a `'use server'` function (which serializes as an RPC reference) or pass the data the function uses and reconstruct the behavior on the client |
+
+## RSC Server Actions — A Worked Example
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { z } from 'zod';
+import { requireSession } from '@/lib/auth';
+import { db } from '@/lib/db';
+
+const UpdateNameInput = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+});
+
+export async function updateUserName(rawInput: unknown) {
+  // 1. Authenticate the caller (server-only source of truth)
+  const session = await requireSession();
+
+  // 2. Validate the input (the bytes from the client may be anything)
+  const input = UpdateNameInput.parse(rawInput);
+
+  // 3. Authorize the action (the authenticated user may not be allowed to do this)
+  if (session.userId !== input.userId && !session.isAdmin) {
+    throw new Error('not allowed');
+  }
+
+  // 4. Perform the action
+  await db.user.update({
+    where: { id: input.userId },
+    data: { name: input.name },
+  });
+}
+```
+
+```typescript
+// app/profile/edit.tsx
+'use client';
+
+import { updateUserName } from '@/app/actions';
+
+export function EditProfile({ userId }: { userId: string }) {
+  return (
+    <form action={async (formData) => {
+      await updateUserName({
+        userId,
+        name: formData.get('name'),
+      });
+    }}>
+      <input name="name" />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+The shape of this code embeds the boundary's three properties:
+
+- **Serialization** — the `formData` is a `FormData` (the wire format for a form submission), unwrapped to a plain object before the action is invoked.
+- **Direction** — the form is client→server; everything in `rawInput` is potentially adversarial.
+- **Trust** — the session is the server's authoritative claim about who is calling; `input.userId` is the client's claim about who to operate on; the authorization check compares the two.
+
+A version of this code that skipped the schema parse, used the session's `userId` as if it were the same as `input.userId`, or trusted a client-supplied `isAdmin` claim would have a vulnerability at the boundary.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every file that ships to the client has `'use client'` (or is reachable only through client imports) — the implicit-server default is intentional, not accidental.
+- [ ] Every server action has `'use server'` at the function or file level — the function's network reachability is explicit.
+- [ ] Server actions validate input with a runtime schema (Zod, valibot, io-ts) — types from TypeScript are not validation.
+- [ ] Server actions re-derive trust from a server-authoritative source (session, JWT verification, database lookup) — client-supplied trust claims are never accepted.
+- [ ] Modules holding secrets import `'server-only'` — the bundler will error if they leak.
+- [ ] Modules touching `window`, `document`, or other browser globals import `'client-only'` — symmetric guardrail.
+- [ ] Props passed from server to client components are serializable in the project's wire format — verified by build success and by code review for non-trivial types (Maps, class instances, Dates).
+- [ ] FormData payloads with nested structure are validated after parsing — no `as` casts of `JSON.parse` results.
+- [ ] No closures cross the boundary — only data, server-action references, and RSC primitives.
+- [ ] Authentication, authorization, and rate-limiting live inside server actions and route handlers, not in client components.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Deciding when and where the UI is produced (CSR/SSR/SSG/RSC) | `rendering-models` | rendering-models owns the staging decision; client-server-boundary owns the serialization frontier — they compose but are distinct |
+| Designing HTTP caching, status codes, content negotiation | `http-semantics` | http-semantics owns the wire protocol; client-server-boundary owns what data exists at the boundary |
+| Organizing the frontend folder layout and module structure | `frontend-architecture` | frontend-architecture is wider — it includes state management, component layering, feature boundaries; the client-server-boundary is one axis it touches |
+| Designing the JSON shape of an external API | `api-design` | api-design owns external surface contracts; client-server-boundary is the internal boundary inside a single application |
+| Choosing between Zod / valibot / io-ts as a runtime validator | individual library docs + `api-design` | library choice is below this skill |
+| Enforcing TypeScript discipline inside the program | `type-safety` | type-safety owns compile-time discipline; the boundary is one of the places where type safety stops |
+
+## Key Sources
+
+- React team. [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md). Proposed Dec 2020. The canonical specification of the RSC wire format, including the rules for what can be serialized across the boundary and the role of `'use client'` / `'use server'`.
+- Sebastian Markbåge (React core). ["The Future of Web Software Is Server Components"](https://www.youtube.com/watch?v=zMf_xeGPn6s). 2022 talk. The mental model of the boundary as a serialization protocol rather than a deployment topology.
+- Vercel. [Next.js documentation — Server and Client Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components). Reference for `'use client'` / `'use server'` semantics, the `server-only` and `client-only` packages, and the serialization rules in App Router.
+- WHATWG. [HTML Living Standard — Structured clone algorithm](https://html.spec.whatwg.org/multipage/structured-data.html#structured-clone). Specification of the broader-than-JSON serialization set used by postMessage, IndexedDB, and Worker boundaries.
+- Mark Erikson. ["Why React Server Components Are Important"](https://blog.isquaredsoftware.com/2023/04/whats-the-deal-with-react-server-components/). 2023. Practitioner-level explanation of the boundary's implications for bundle size, hydration, and the framework-author contract.
+- Remix team. [Loader and Action documentation](https://remix.run/docs/en/main/route/loader). Reference for the function-named boundary convention that predates and informs RSC's directive-based model.
+- OWASP. [Top 10:2021 — A01:2021 Broken Access Control](https://owasp.org/Top10/A01_2021-Broken_Access_Control/). The class of vulnerabilities that arise specifically from treating client-supplied trust claims as authoritative — the failure mode this skill exists to prevent.
+- Hejlsberg, A. et al. [TypeScript Handbook — Type assertions and the `unknown` type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions). The explicit acknowledgement that `as` casts do not validate at runtime — the gap that boundary-crossing validation must fill.

package/marketplace/skills/code-review/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: code-review
+description: "Use when reviewing a pull request, diff, or proposed code change for correctness, clarity, security, performance, and conformance to project conventions — whether the author is a human, an AI agent, or a peer. Covers the pre-review fact-gathering pass, the read-order strategy (tests first, then implementation, then call sites), the severity-grading rubric, the comment-phrasing discipline, and the no-rubber-stamp rule for AI-generated diffs. Do NOT use for AUTHORING the code (use `refactor` for behaviour-preserving changes or `skill-scaffold` for new skills), for chasing a known bug after merge (use `debugging`), or for security-only audits (use `owasp-security` for vulnerability-focused review)."
+license: MIT
+compatibility: Language-agnostic; assumes a diff or PR as input
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"quality\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-04\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-04\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"code review\\\\\\\",\\\\\\\"review this PR\\\\\\\",\\\\\\\"review this diff\\\\\\\",\\\\\\\"review this change\\\\\\\",\\\\\\\"review this AI generated code\\\\\\\",\\\\\\\"PR review\\\\\\\",\\\\\\\"diff review\\\\\\\",\\\\\\\"severity grade\\\\\\\",\\\\\\\"reviewer rubric\\\\\\\",\\\\\\\"approve or block\\\\\\\",\\\\\\\"request changes\\\\\\\",\\\\\\\"review checklist\\\\\\\",\\\\\\\"review a colleague PR\\\\\\\",\\\\\\\"review my own code\\\\\\\",\\\\\\\"code quality review\\\\\\\"]\",\"examples\":\"[\\\\\\\"review this PR for correctness and project conventions\\\\\\\",\\\\\\\"this diff was generated by an AI agent — what should I check?\\\\\\\",\\\\\\\"should I approve this change or request more work?\\\\\\\",\\\\\\\"what's the right severity for missing test coverage on a refactor?\\\\\\\",\\\\\\\"review my own code before I open the PR\\\\\\\",\\\\\\\"review this 600-line diff — where do I start?\\\\\\\",\\\\\\\"this PR adds a new endpoint — review for security and correctness\\\\\\\",\\\\\\\"phrase a request-changes comment without sounding harsh\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"fix this bug that production users are reporting\\\\\\\",\\\\\\\"refactor this 200-line function into smaller pieces\\\\\\\",\\\\\\\"scaffold a new skill that teaches code review\\\\\\\",\\\\\\\"write a guide explaining our review conventions\\\\\\\",\\\\\\\"audit this code for SQL injection and XSS specifically\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor produces the change being reviewed; code-review evaluates the change. Reviewer and author are distinct roles even when the same person fills them\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases an observed failure; code-review catches problems before merge\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"owasp-security\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"owasp-security is a security-specific deep audit; code-review is the holistic per-PR pass that includes security as one of several concerns\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy decides what to test; code-review evaluates whether the implemented tests adequately cover the change\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"owasp-security\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/code-review/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/code-review/SKILL.md
+---
+
+# Code Review
+
+## Coverage
+
+- Pre-review fact-gathering: understanding the PR's stated purpose, the linked issue, the size of the diff, and any context the author called out
+- Read-order strategy: tests first (do they describe the change correctly?), then the implementation, then the call sites that consume the changed surface
+- Severity-grading rubric: blocker / change-requested / suggestion / nit / praise — and when each is appropriate
+- Comment-phrasing discipline: how to ask questions instead of make accusations, how to cite line numbers and references, how to distinguish an objective rule from a stylistic preference
+- The no-rubber-stamp rule for AI-generated diffs: deliberate verification of the generated code's claims, especially around tests, error handling, and security
+- Self-review pass: how to review your own diff before opening the PR, catching the obvious issues so the human reviewer can focus on the non-obvious
+- Tools that complement the review: lint output, type-check output, test results, and how to interpret each in context
+- The merge decision: when "approve", "request changes", and "close without merge" are appropriate
+
+## Philosophy
+
+A code review is a *conversation*, not a verdict. The reviewer's job is not to prove they could have written the code differently; it is to ensure the change ships in a state the team can maintain. Reviews fail when they are either rubber-stamped (no verification, just a thumbs-up) or weaponised (every review becomes a referendum on the author's competence). The reviewer's leverage comes from reading code the author has been staring at for hours — the reviewer sees the obvious mistakes the author cannot.
+
+For AI-generated diffs the bar is higher, not lower. Karpathy's "vibe hangover" is real: AI-generated code typically *looks* correct, has reasonable variable names, and compiles cleanly — and contains 1.7-2.74× more security vulnerabilities than human-authored equivalents. A reviewer rubber-stamping an AI diff is not saving time; they are deferring debugging cost to whichever colleague debugs the production failure.
+
+## Workflow
+
+The review is six phases. Skipping any phase is a rubber stamp; doing them out of order produces low-signal comments that confuse the author.
+
+### Phase 1 — Pre-review fact-gathering (5 minutes)
+
+1. Read the **PR title and description**. Identify the stated purpose in one sentence.
+2. Read the **linked issue or task**. Confirm the diff matches the issue's acceptance criteria.
+3. Note the **diff size**: <50 lines is a quick review, 50-300 is a normal review, 300-1000 is a slow review, 1000+ is a "should this have been split?" review.
+4. Skim the **list of changed files**. Form a hypothesis: "this change should touch X, Y, Z." If the diff touches files outside that hypothesis, ask why before reading the code.
+
+### Phase 2 — Read tests first (10-30 minutes)
+
+1. Open the test files BEFORE the implementation files.
+2. For each new or modified test, read the *assertion* — what does the test claim is true?
+3. For each new or modified test, read the *setup* — what state does the test put the code in?
+4. The tests should describe the change in plain language. If the tests are unclear, the implementation will be too.
+5. **Missing tests** for new behaviour is a *change-requested* signal at minimum, often a *blocker* for production paths.
+
+### Phase 3 — Read implementation (30-90 minutes)
+
+Read in the order the diff is presented (chronological by file path). Apply the rubric below to each diff hunk.
+
+| Concern | Look for | Severity if missing |
+|---|---|---|
+| **Correctness** | Does this implement what the PR claims? Edge cases handled? Off-by-one? | **Blocker** |
+| **Type safety / null handling** | Unguarded null deref, untyped boundary, `any` escape | **Blocker** if production-path; otherwise change-requested |
+| **Security** | SQL injection, XSS, auth bypass, secret in code, missing CSRF | **Blocker** |
+| **Test coverage** | New code path with no test, new branch with no test | **Change-requested** at minimum |
+| **Performance** | N+1 query, unbounded loop, sync I/O in hot path | **Change-requested** if observable; **blocker** if catastrophic |
+| **Project conventions** | Naming, file location, import order, lint cleanliness | **Suggestion** unless project doc enforces |
+| **Documentation drift** | Stale comment, wrong API description, broken cross-reference | **Change-requested** if user-visible |
+| **Naming clarity** | Misleading name, abbreviation that hides meaning | **Suggestion** unless the name actively lies |
+| **Stylistic preference** | "I'd write this differently" with no objective rule | **Nit** at most; often delete |
+
+### Phase 4 — Read call sites (10-30 minutes)
+
+For every changed public surface (exported function, route, schema), grep for callers. Confirm the diff's contract matches what callers expect. The most expensive bugs are introduced at the contract layer because the implementation looked fine in isolation.
+
+### Phase 5 — Author the review (15-30 minutes)
+
+Write comments in the order: **blockers, change-requested, suggestions, nits, praise**. Each comment must:
+
+- Cite the line number explicitly.
+- State the *concern* before the *fix*: "this returns null on missing input — should it throw? callers do not currently null-check."
+- Distinguish an objective rule (cite the rule) from a preference ("style nit").
+- Avoid ad-hominem. The diff is the subject, not the author.
+
+For AI-generated diffs, add deliberate verification comments: "AI-generated — confirmed test exists for the happy path. Did the author verify the empty-input case? It's not in the diff."
+
+### Phase 6 — The merge decision
+
+| Verdict | When |
+|---|---|
+| **Approve** | All blockers absent, change-requested resolved, suggestions optional |
+| **Approve with comments** | Blockers absent, suggestions worth raising but not blocking |
+| **Request changes** | Any blocker present, OR any change-requested item the author should address |
+| **Close without merge** | The diff implements the wrong thing, OR the issue is no longer valid |
+
+A review without a verdict is incomplete. Don't leave PRs open with comments and no decision.
+
+## Self-Review (Before Opening the PR)
+
+Run the same six phases on your own diff before opening the PR. The author's self-review catches 60-80% of the issues a reviewer would otherwise raise, leaving the reviewer's attention free for the non-obvious. Self-review is not optional — it is the cheapest place to catch the obvious mistakes.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/code-review.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/code-review.json). The checklist below is the reviewer gate for proposed changes; the eval file is the grader surface.
+
+## Verification
+
+- [ ] PR description matches the diff scope (no surprise files or scope creep)
+- [ ] Tests exist for new behaviour and pass locally / in CI
+- [ ] All blockers and change-requested items have line-cited comments
+- [ ] AI-generated content is verified, not rubber-stamped
+- [ ] Naming, security, and convention concerns are graded by severity, not lumped together
+- [ ] The merge decision is explicit (approve / request-changes / close)
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `refactor` | Authoring the change being reviewed |
+| `debugging` | Investigating a failure that already shipped |
+| `owasp-security` | Conducting a security-specific deep audit (the holistic review covers security as one concern; OWASP is the deep dive) |
+| `testing-strategy` | Deciding what tests to write before authoring the diff |
+| `skill-scaffold` | Authoring a new skill from scratch (skill content review IS code review, but the authoring workflow is the scaffold's domain) |

package/marketplace/skills/color-system-design/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: color-system-design
+description: "Use when designing a color system — palette construction, semantic color tokens, WCAG contrast ratios, perceptual uniformity in OKLCH/LCH, and light/dark mode parity. Do NOT use for single brand-color picks, runtime theme-switching mechanics, or non-color design tokens."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"color palette design\\\\\\\",\\\\\\\"semantic color tokens\\\\\\\",\\\\\\\"wcag contrast ratio\\\\\\\",\\\\\\\"apca contrast\\\\\\\",\\\\\\\"oklch color space\\\\\\\",\\\\\\\"perceptual uniformity\\\\\\\",\\\\\\\"color scales\\\\\\\",\\\\\\\"light dark parity\\\\\\\",\\\\\\\"color accessibility\\\\\\\",\\\\\\\"p3 color gamut\\\\\\\",\\\\\\\"color-mix\\\\\\\",\\\\\\\"color palette light dark mode\\\\\\\",\\\\\\\"pick color scheme\\\\\\\"]\",\"triggers\":\"[\\\\\\\"color system\\\\\\\",\\\\\\\"color palette\\\\\\\",\\\\\\\"color tokens\\\\\\\",\\\\\\\"wcag contrast\\\\\\\",\\\\\\\"oklch\\\\\\\"]\",\"examples\":\"[\\\\\\\"Build a 10-step color scale from a brand seed color with perceptually even lightness steps\\\\\\\",\\\\\\\"Map semantic intents (success, warning, danger, info) to scale colors with WCAG AA contrast against both light and dark surfaces\\\\\\\",\\\\\\\"Audit an existing palette for AA contrast failures and propose minimal changes\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Pick the brand's primary color from scratch with no constraints\\\\\\\",\\\\\\\"Implement the prefers-color-scheme media query and toggle UI\\\\\\\",\\\\\\\"Choose spacing values for the layout grid\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"dark-mode-implementation\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"a11y\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"theme-system-design structures how color decisions become tokens and reach components; this skill produces those color decisions.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns the WCAG criteria themselves; this skill applies them when constructing palettes and selecting pairings.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/color-system-design/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/color-system-design/SKILL.md
+---
+
+# Color System Design
+
+## Coverage
+A color system has three layers: a palette of raw color values (organized as scales — typically 9 to 12 steps from very light to very dark within a single hue), a set of semantic tokens that name colors by purpose rather than appearance (background-surface, text-primary, border-subtle, danger-emphasis), and a mapping that resolves semantic tokens to palette values per theme. The palette is the vocabulary; the semantic tokens are the contract that components consume; the mapping is what changes between themes.
+
+Color spaces matter for scale construction. sRGB and HSL are non-perceptually-uniform — equal numeric steps in lightness produce unequal perceived lightness changes, with notable cliffs around yellow and teal. OKLCH and CIELAB are perceptually uniform color spaces where equal L (lightness) steps look equal regardless of hue, making them the appropriate space for generating scales. The CSS Color Module Level 4 specifies oklch() and lch() as first-class CSS color functions, and color-mix() in lch/oklch space produces predictable interpolation. The display-p3 gamut, supported by most modern displays, allows more saturated colors than sRGB in the green/red regions; declaring color-gamut: p3 or using p3 color functions delivers them while CSS color fallbacks handle sRGB-only displays.
+
+Contrast is governed by WCAG 2.1, which specifies a contrast ratio computed from relative luminance: 4.5:1 for normal text (AA), 3:1 for large text (AA, defined as 18pt+ or 14pt+ bold), and 7:1 for normal text (AAA). APCA (Accessible Perceptual Contrast Algorithm), the working draft for WCAG 3, uses a different model that better predicts perceived text legibility, with thresholds expressed as Lc values (60 Lc for body text, 75 Lc for small text). Tooling should compute both, but WCAG 2.1 remains the legally referenced standard in most jurisdictions as of 2026.
+
+Semantic tokens decouple the system from a single visual treatment. text-primary on a light theme might be near-black at L=0.15; on a dark theme it might be near-white at L=0.96. Both resolve to the same component token and meet the same contrast requirement against their respective backgrounds. The discipline is to define semantic tokens by intent and contrast pair (text-on-surface, text-on-emphasis), never by appearance (text-dark-gray).
+
+## Philosophy
+Color choices are constraints applied to perception, not free decisions. Perceptual uniformity, contrast minima, color-blindness considerations (8% of men have some form of color vision deficiency), and gamut limits are real and observable. A palette that ignores them produces accessibility violations and uneven scales that designers have to compensate for with one-off tweaks.
+
+Semantic tokens are worth the indirection because color meanings outlive specific values. "Danger" stays danger when the brand red shifts a few degrees; components keep working. Tying components directly to palette values turns every brand refresh into a code change.
+
+## Verification
+- Every text/background pair used in the product meets WCAG 2.1 AA at minimum; an automated check runs in CI against the token combinations.
+- Scales are generated in OKLCH or LCH and exported to sRGB or display-p3; equal step indices have equal lightness within ±2 L units.
+- Semantic tokens are named by intent (background-surface, danger-emphasis) not by appearance (gray-50, red-700) in component code.
+- Light and dark themes provide every semantic token; no token is light-only or dark-only.
+- Color is not the only signal for state — error states pair red with an icon and text, not red alone, to remain accessible to color-blind users.
+- The palette has been previewed under simulated protanopia, deuteranopia, and tritanopia, and important distinctions remain visible.
+- Brand color is anchored at a specific scale step (e.g., brand at step 600) so the surrounding scale is generated rather than hand-tuned.
+
+## Do NOT Use When
+- The task is picking a single brand color with no system implications. That is a brand decision, not a system decision.
+- You are implementing the runtime mechanics of theme switching, persistence, and asset variants. Use theme-system-design and dark-mode-implementation.
+- The work is non-color tokens — spacing, typography, motion. Use typography-system or visual-design-foundations.
+- The concern is purely accessibility-criterion lookup rather than palette construction. Use a11y.
+- You need to choose color values for a single illustration or marketing graphic with no token impact. Treat as art direction, not system design.

package/marketplace/skills/component-architecture/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: component-architecture
+description: "Use when structuring a component library or design system for reuse across products, themes, and teams: layering of primitives, composites, and product-specific assemblies; component API design (props, polymorphism, compound components, render props vs hooks vs slots); the open-closed principle for component evolution; the headless/styled split for theming; controlled vs uncontrolled state contracts; ref forwarding and imperative escape hatches; composition over configuration trade-offs; and the cross-product reuse problem. Do NOT use for within-product module composition (use design-module-composition), design system meta-architecture (use design-system-architecture), the visual language itself (use visual-design-foundations or tokens), tactical hooks (library docs), or state-management decisions that are not component-API-shaped (use state-management)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/component-systems\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"component library design\\\\\\\",\\\\\\\"atomic design layering\\\\\\\",\\\\\\\"component primitives\\\\\\\",\\\\\\\"component composites\\\\\\\",\\\\\\\"compound components\\\\\\\",\\\\\\\"polymorphic component\\\\\\\",\\\\\\\"asChild prop\\\\\\\",\\\\\\\"headless component\\\\\\\",\\\\\\\"styled component\\\\\\\",\\\\\\\"controlled component\\\\\\\",\\\\\\\"uncontrolled component\\\\\\\",\\\\\\\"ref forwarding\\\\\\\",\\\\\\\"render props\\\\\\\",\\\\\\\"component slots\\\\\\\",\\\\\\\"compose components\\\\\\\",\\\\\\\"component prop API\\\\\\\",\\\\\\\"component reuse across products\\\\\\\",\\\\\\\"decomposing a large component to maintain it\\\\\\\"]\",\"triggers\":\"[\\\\\\\"structure components for reuse\\\\\\\",\\\\\\\"how do I design this component API\\\\\\\",\\\\\\\"controlled or uncontrolled\\\\\\\",\\\\\\\"should I use props or composition\\\\\\\",\\\\\\\"compound component pattern\\\\\\\",\\\\\\\"headless vs styled\\\\\\\",\\\\\\\"primitive vs composite\\\\\\\"]\",\"examples\":\"[\\\\\\\"design the API surface for a Dialog component that must work in multiple products with different visual languages\\\\\\\",\\\\\\\"decide whether a Form component should be controlled, uncontrolled, or both\\\\\\\",\\\\\\\"structure a component library so primitives can be themed without rewriting the composites\\\\\\\",\\\\\\\"refactor a 30-prop component into a compound API that surfaces the right primitives\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide where the form's state lives across page navigations (use state-management)\\\\\\\",\\\\\\\"pick the design tokens for color and spacing (use visual-design-foundations)\\\\\\\",\\\\\\\"decide how a single product's modules are wired together internally (use design-module-composition)\\\\\\\",\\\\\\\"implement a specific React hook for form management (library docs / tactical decision)\\\\\\\",\\\\\\\"decide where state lives across the app — server, client UI, URL, or persistent (use state-management)\\\\\\\",\\\\\\\"design the application-level folder structure, routing, build, and deployment (use frontend-architecture)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"design-module-composition\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"state-management\\\\\\\",\\\\\\\"frontend-architecture\\\\\\\",\\\\\\\"typography-system\\\\\\\",\\\\\\\"color-system-design\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"design-module-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-module-composition owns how a SINGLE PRODUCT's modules compose internally — layout, slots, named regions, within-product composition patterns. This skill owns the layer above: how components are STRUCTURED to be reusable across products, with API surfaces that survive multiple visual languages and interaction contracts. They compose: this skill says how to build the components; design-module-composition says how a product wires them up.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-system-architecture owns the META structure of a design system: tokens, foundations, governance, documentation, distribution. This skill owns one stratum inside that: how components themselves are structured. A design system is a system of components plus tokens plus foundations plus distribution; this skill is the component stratum.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"visual-design-foundations owns the design language itself: color theory, typography, spacing, grid, motion. This skill owns the structural mechanism by which that language is delivered to product code — components that bind to tokens and surface the language in reusable form.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"design-module-composition\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Component architecture is to a UI library what API design is to a backend service — the public contract is the only thing consumers see; every consumer depends on shape, behavior, and naming for things that may seem internal to the author; once a version ships, every prop and slot becomes a thing future versions must continue to support, just as every endpoint and field of a public API does. The headless/styled split is to component libraries what the data-plane/control-plane split is to distributed systems: separating the part that changes slowly (behavior, contracts) from the part that changes fast (visual treatment, theming).\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Component architecture is the architectural discipline of structuring a library of UI components so that they can be reused across products, themes, and teams without each reuse requiring a rewrite. The discipline answers four interlocking questions: (1) at what LAYER does a given concern belong — primitive, composite, product-specific assembly; (2) what is the API SURFACE — which props, slots, refs, callbacks, render functions, and which are open for extension vs closed for modification; (3) what STATE CONTRACT does the component expose — controlled, uncontrolled, hybrid; (4) what THEMING and styling mechanism allows the component's behavior to remain stable while its visual language changes. The discipline is distinct from the visual design language itself (which colors, which type scale) and from within-product wiring (which screens compose which modules) — it is the architectural stratum that makes both possible by producing components whose API outlives any single product instance and any single visual treatment.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/component-architecture/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1107\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/component-architecture/SKILL.md
+---
+
+# Component Architecture
+
+## Coverage
+
+The architectural discipline of structuring a library of UI components so they can be reused across products, themes, and teams. Covers the layering of primitives, composites, and product-specific assemblies; the composition-over-configuration principle and its trade-offs; the headless/styled split as the mechanism for behavior reuse across visual languages; controlled / uncontrolled / hybrid state contracts; the open-closed principle adapted to component evolution; polymorphism via `as` and `asChild`; extension mechanisms (props, children, slots, render props, compound components, ref forwarding); and the API-as-contract framing that makes component libraries survive multi-product, multi-year reuse.
+
+## Philosophy
+
+The component's API is the contract between its author and every future consumer. Every prop, every slot, every event is a public surface that becomes a thing future versions must continue to support — or break consumers. Component architecture is the discipline of designing those contracts with the knowledge that you cannot predict every consumer and that the contract will be inhabited by integrations you didn't anticipate.
+
+The discipline is upstream of any specific library, framework, or visual language. Layering, composition, the headless/styled split, the controlled/uncontrolled distinction, and the open-closed principle are properties of how components are *structured* — independent of which framework implements them and which design tokens style them. A team that internalizes these properties produces libraries that survive a decade of framework changes, brand refreshes, and product evolution. A team that does not produces libraries that work for the first product and require a rewrite for the second.
+
+For agents working in component-heavy codebases, the discipline is the framework that lets the agent reason locally. Pick up a component, classify it by layer (primitive / composite / product-specific), inspect its API surface (props, slots, events), identify its state contract (controlled / uncontrolled / hybrid), and use it correctly without internalizing every idiosyncrasy. Without the framework, the agent pattern-matches against whatever the codebase already does — which means proliferating the codebase's existing architectural mistakes.
+
+## The Layering Principle
+
+| Layer | What it is | Change rate | Reuse scope | Examples |
+|---|---|---|---|---|
+| **Primitive** | Smallest reusable unit; behavior only or behavior + minimal styling | Rare | All products | Button, Input, Checkbox, Popover, Dialog Root |
+| **Composite** | Combines primitives into recurring patterns | Moderate | Most products | FormField (label + input + error), Card, DataTable |
+| **Product-specific assembly** | Combines composites into unique product surfaces | Frequent | One product | CheckoutForm, SettingsPanel, DashboardWidget |
+
+Dependencies flow downward (composites depend on primitives; assemblies depend on composites). Reversing the flow couples primitives to specific use cases and destroys reuse.
+
+## Composition Over Configuration
+
+| Pattern | When to use | What it costs | What it scales |
+|---|---|---|---|
+| **Configuration (props)** | Small closed enum of variations; combinations are independent | Each new prop is more API surface; combinations multiply | Acceptable up to ~5-7 independent props; gets dangerous beyond |
+| **Composition (children, slots, sub-components)** | Open-ended variation; structure matters | More code at each consumer; more concepts | Scales indefinitely; new variations are additive, not multiplicative |
+
+Refactor sign: a configured component with >10 props that are mostly independent is a candidate for the compound-component refactor.
+
+## The Headless / Styled Split
+
+| Layer | Owns | Examples |
+|---|---|---|
+| **Headless** | Keyboard navigation, focus management, ARIA, internal state, event emission | Radix Primitives, Headless UI, Ariakit, React Aria, Tanstack Table |
+| **Styled** | Visual treatment, layout, spacing, typography binding | shadcn/ui (Radix + Tailwind), Mantine, MUI theme, your design system |
+
+The split is the architectural mechanism that solves cross-product reuse when the same interaction patterns must look different in different products. Behavior evolves independently of styling; styling evolves independently of behavior.
+
+## State Contract Patterns
+
+| Contract | Who owns value | API shape | When to use |
+|---|---|---|---|
+| **Controlled** | Consumer | `value` + `onChange` | Value participates in larger state (form, store, URL) |
+| **Uncontrolled** | Component (internal) | `defaultValue` + `onChange` (event-shaped) | Value is the component's business alone |
+| **Hybrid** | Both supported | Both `value` (controlled path) and `defaultValue` (uncontrolled path) | Default for any new component; serves both consumer kinds |
+| **Imperative-only** | Refs and methods | `ref.current.play()`, etc. | Rare; for cases where declarative APIs are awkward (video, focus) |
+
+Default to hybrid. Consumers choose by passing `value` or `defaultValue`.
+
+## Extension Mechanisms
+
+| Mechanism | What it opens | When to use |
+|---|---|---|
+| **Props (config)** | Closed set of variations | Variations are small, closed, combinatorially independent |
+| **Children / slots** | Structure | Consumer composes inner content |
+| **Compound components** (`Dialog.Root`, `Dialog.Trigger`, `Dialog.Content`) | Structure + implicit shared state via context | Multi-part components with structural variation |
+| **Render props / render functions** | Rendering | Consumer overrides how something renders, with access to internal state |
+| **Forward refs / imperative handles** | Imperative access | Escape hatch for cases declarative APIs cannot reach (focus, scroll, play) |
+| **Polymorphism (`as` / `asChild`)** | Element type | Consumer chooses the semantic tag rendered |
+
+## The Polymorphism Patterns
+
+| Pattern | Syntax | Pros | Cons |
+|---|---|---|---|
+| **`as` prop** | `<Button as="a" href="...">` | React-idiomatic; familiar | Hard to type correctly; doesn't compose well across libraries |
+| **`asChild`** (Radix) | `<Button asChild><a href="...">...</a></Button>` | Cleaner accessibility; consumer sees the semantic element | Unfamiliar at first encounter |
+| **Slot-based** (Vue, Svelte) | Framework slot mechanism | Native framework support | Limited to that framework |
+
+For cross-library compatibility in React, `asChild` (and the underlying Radix Slot pattern) has become the modern default.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Each component has been classified by layer (primitive / composite / product-specific); the dependency direction is downward only.
+- [ ] Configuration-explosion candidates (components with many independent boolean/enum props) have been considered for composition refactors.
+- [ ] Headless behavior is separated from styled presentation when the component is intended for cross-product or cross-theme reuse.
+- [ ] State contracts are deliberate (controlled / uncontrolled / hybrid / imperative); the default is hybrid for inputs.
+- [ ] Polymorphic components use a deliberate pattern (`as` or `asChild`) — not an accidental any-tag escape hatch.
+- [ ] Compound components share state via context and document the requirement that sub-components live within the parent.
+- [ ] Accessibility (keyboard, focus, ARIA, screen-reader announcement) is built into the primitive layer, not retrofitted.
+- [ ] The API surface is documented (every prop, every slot, every event, every imperative method) and stable; breaking changes follow a deprecation cycle.
+- [ ] Tokens (color, spacing, type) are the binding mechanism for visual properties, not hardcoded values; the styled layer binds to tokens, not literals.
+- [ ] The component library has been tested with multiple actual consumers (multiple products, multiple themes) to verify reusability claims.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Wiring a specific product's screens from components | `design-module-composition` | design-module-composition owns within-product assembly; this skill owns the components being assembled |
+| Designing the design system's overall structure (tokens, foundations, governance, distribution) | `design-system-architecture` | design-system-architecture owns meta-structure; this skill owns the component stratum |
+| Picking the design language (color, type, spacing decisions) | `visual-design-foundations` | visual-design-foundations owns the language; this skill owns the structural mechanism delivering it |
+| Deciding where component state lives across the app | `state-management` | state-management owns location and ownership; this skill owns the component's state-contract API surface |
+| Picking React hook patterns for internal component state | Library docs (React, Vue, etc.) | Tactical implementation; below this skill |
+| Designing the app's folder structure | `folder-structure` or `frontend-architecture` | This skill cares about components, not where they live on disk |
+| Component-level accessibility audit | `a11y` | a11y owns the discipline of checking accessibility; this skill bakes the property into the architecture |
+| Form-specific component architecture (validation, submit) | `form-ux-architecture` | form-ux-architecture owns the form-specific patterns; this skill is the broader framing |
+
+## Key Sources
+
+- Frost, B. (2016). *Atomic Design*. Brad Frost Web. The canonical layering framework: atoms / molecules / organisms / templates / pages. Establishes the discipline of layering as a property of well-structured component libraries.
+- Meyer, B. (1988). *Object-Oriented Software Construction*. Prentice Hall. The original articulation of the open-closed principle ("software entities should be open for extension, but closed for modification") — adapted in this skill to component evolution.
+- Radix UI. [Radix Primitives documentation](https://www.radix-ui.com/primitives/docs/overview/introduction). The modern reference implementation of the headless component pattern, the compound-component pattern, and the `asChild` polymorphism pattern. Establishes the contract that has become widely adopted across the React ecosystem.
+- Adobe. [React Aria documentation](https://react-spectrum.adobe.com/react-aria/). The reference implementation of accessibility-first headless components. Demonstrates the architectural commitment to keyboard, focus, and screen-reader support as primitive-layer concerns.
+- Erikson, M. (2020). ["Compound Components"](https://kentcdodds.com/blog/compound-components-with-react-hooks) [Kent C. Dodds]. Canonical modern articulation of the compound-component pattern with hooks-based React.
+- shadcn. [shadcn/ui documentation](https://ui.shadcn.com/). The 'registry' distribution model (copy into the consumer's repo) and the canonical example of the headless-primitive + styled-wrapper layered architecture.
+- Vue Team. [Vue.js Slots documentation](https://vuejs.org/guide/components/slots.html). The reference framework-native slot mechanism that predates and inspired React's compound-component patterns; demonstrates that the architectural principles apply across frameworks.
+- Liskov, B. (1987). "Data Abstraction and Hierarchy." *Proceedings of OOPSLA '87 Addendum*. The Liskov Substitution Principle — adapted in this skill as the constraint that polymorphic substitutions must preserve invariants.
+- Garlan, D., & Shaw, M. (1993). "An Introduction to Software Architecture." *Advances in Software Engineering and Knowledge Engineering*, Vol. 1. The foundational treatment of layered architectures as a software-architecture pattern; provides the dependency-direction reasoning this skill adapts to components.
+- Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley. The Composite, Decorator, and Strategy patterns underlie much of the composition-vs-configuration framing; the foundational reference for reuse-via-composition.