@skill-graph/cli 0.5.6

package/marketplace/skills/server-components-design/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: server-components-design
+description: "Use when designing or reviewing React Server Components: what an RSC can do (async, data fetching, server-only imports) versus what it cannot (state, effects, event handlers, browser APIs), where to draw the server/client boundary in the tree, and how RSC composes with Suspense to stream content without a separate API layer. Covers Next.js App Router as the canonical implementation, but the discipline is framework-agnostic. Do NOT use for the 'use client' directive mechanics (use client-server-boundary), hook discipline on Client Components (use hooks-patterns), rendering strategy choice (use rendering-models), or the server-action mutation surface (use server-actions-design when authored)."
+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-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"React Server Components\\\\\\\",\\\\\\\"RSC\\\\\\\",\\\\\\\"Next.js App Router\\\\\\\",\\\\\\\"async components\\\\\\\",\\\\\\\"server-side data fetching\\\\\\\",\\\\\\\"streaming RSC\\\\\\\",\\\\\\\"server/client component tree\\\\\\\",\\\\\\\"RSC payload\\\\\\\",\\\\\\\"Suspense boundaries with RSC\\\\\\\",\\\\\\\"data flow without API layer\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a Server Component or a Client Component\\\\\\\",\\\\\\\"can I fetch data here\\\\\\\",\\\\\\\"why can't I use useState in this file\\\\\\\",\\\\\\\"how does data move from server to client\\\\\\\",\\\\\\\"do I need an API route\\\\\\\",\\\\\\\"why is the bundle so large\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a dashboard widget should be a Server Component (fetches and renders) or a Client Component (interactive)\\\\\\\",\\\\\\\"explain why a Server Component cannot pass a function as a prop to a Client Component\\\\\\\",\\\\\\\"design a page where the layout fetches user data once and child widgets fetch their own data, with Suspense streaming each in\\\\\\\",\\\\\\\"audit a component tree for unnecessary 'use client' boundaries that pull static rendering into the bundle\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"add a click handler to an existing component (use hooks-patterns and client-server-boundary)\\\\\\\",\\\\\\\"choose between SSR and SSG for a marketing page (use rendering-models)\\\\\\\",\\\\\\\"build the form-submission mutation flow (use server-actions-design when authored)\\\\\\\",\\\\\\\"design the public API for a third-party integration (use api-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"rendering-models\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"streaming-architecture\\\\\\\",\\\\\\\"suspense-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization-and-directive mechanics of the boundary itself ('use client', what can cross, RSC payload format); server-components-design owns the discipline of which work belongs on the server side of that boundary.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"rendering-models\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"rendering-models owns the strategic decision among SSR, SSG, ISR, and CSR; server-components-design operates within the App Router / RSC paradigm and is one rendering mode among several.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"hooks-patterns covers state and effect discipline on Client Components; Server Components cannot use those primitives at all, so the two skills cover disjoint surfaces.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"rendering-models\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A Server Component is to a React tree what a printed page is to a book — the typesetter (server) sets the lead, presses the ink, and ships the printed page (RSC payload); the reader's table lamp (Client Component) is wired and switchable at the reader's end. You do not ship the typesetter to the reader's living room, and you do not ship the lamp's wiring to the printer — the boundary is where 'this never changes once it leaves my workshop' ends and 'this responds to who touches it' begins.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A React Server Component is a component that runs only on the server, never ships to the browser as JavaScript, can be async, and can directly access server-side resources (databases, file system, secrets) — its output is serialized to a wire format (the RSC payload) and reconstituted into the client tree without a separate API layer. Server Components compose with Client Components in a single tree, but the directionality is one-way: a Server Component can render a Client Component, but a Client Component cannot import a Server Component as a child.\\\\\\\",\\\\\\\"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/server-components-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/server-components-design/SKILL.md
+---
+
+# Server Components Design
+
+## Coverage
+
+The discipline of designing React Server Components (RSC): what an RSC is *for*, what it can do that Client Components cannot, what it cannot do, how the server/client boundary shapes the component graph and the data-flow graph, how RSC composes with Suspense to stream content from the server in chunks, why Server Components remove the need for a separate API layer for read-path data, and the recurring design questions a reviewer asks of any RSC tree. Next.js App Router is the canonical implementation referenced throughout; the discipline applies to any RSC implementation (Remix RSC, Waku, hand-rolled RSC servers) since the underlying primitive is the React RFC, not a single framework.
+
+## Philosophy
+
+The original React component model collapsed two roles into one function: produce HTML for the initial render, and produce a virtual DOM update in response to client-side state. Server-Side Rendering pre-React-18 tried to make that single function run twice — once on the server to produce HTML, once on the client to produce the interactive tree — and pay for it with hydration: a full re-execution on the client to bind event handlers and reconstruct state.
+
+Hydration has two costs the industry tolerated for a decade: every component must ship to the client (bundle size grows with the page), and every component re-runs on the client (CPU cost grows with the page). React Server Components separate the two roles into different *kinds* of component. A Server Component runs once, on the server, and produces a serialized output that the client uses directly — no shipping, no re-execution. A Client Component is what we used to call "a component": ships to the browser, runs on render and on every interaction.
+
+The discipline of RSC design is to push as much of the tree as possible to the server side of the boundary, and to draw the line as close to the actual interactive leaves as possible. A button needs `useState`; the dashboard surrounding the button does not. A chart that responds to filter clicks is interactive; the page header above it is not. The win is real: bundle size shrinks toward "only the interactive parts," and the server has direct access to databases, file systems, and secrets without an intermediating API layer.
+
+But the boundary is unforgiving. A Server Component cannot use hooks. It cannot read state. It cannot attach event handlers. Anything that crosses to a Client Component must be serializable — strings, numbers, plain objects, arrays, Promises (in React 19), JSX, and React elements; not functions, not class instances, not symbols, not Maps. The discipline is to express the work in shapes that respect that constraint, and to use Suspense boundaries to let the server-rendered tree stream piece by piece rather than blocking on the slowest piece.
+
+## What a Server Component Can Do (And What a Client Component Cannot)
+
+| Capability | Server Component | Client Component |
+|---|---|---|
+| `async` / `await` at the component level | Yes | No (React 18); promises must be unwrapped via `use()` (React 19) |
+| Direct database queries, file reads, secret access | Yes | No — would leak to the browser |
+| Read environment variables (including `PROCESS_SECRET`-style) | Yes | No — only `NEXT_PUBLIC_*` vars are safe |
+| Import server-only libraries (Postgres driver, file system) | Yes | No — bundling would fail (or worse, succeed and leak) |
+| Subscribe to browser events (`onClick`, `onChange`) | No | Yes |
+| Manage state (`useState`, `useReducer`) | No | Yes |
+| Side effects (`useEffect`) | No | Yes |
+| Read browser APIs (`window`, `localStorage`) | No | Yes |
+| Render Client Components as children | Yes — boundary crosses here | Yes |
+| Be rendered *as a child* of a Client Component | Only via the `children` prop pattern | n/a |
+
+The boundary is not just about what's available; it's about what makes sense. A Server Component that renders the same output regardless of any client state is doing the right thing. A Server Component that wants to know "what tab did the user click on" is asking the wrong primitive — that's Client Component territory.
+
+## The Composition Pattern: Client at the Leaves, Server Everywhere Else
+
+A naive boundary draws the line at the page level: "this page needs interactivity, so the whole page is a Client Component." This loses most of the RSC benefit.
+
+A disciplined boundary draws the line at the *interactive leaves*: the button that toggles a dropdown is a Client Component; the dropdown's structure, the surrounding layout, the data feeding it — all Server Components.
+
+The enabling pattern is **passing Server Components as `children` to Client Components**:
+
+```tsx
+// app/dashboard/page.tsx — Server Component
+import { ServerData } from './ServerData'
+import { ClientFilterBar } from './ClientFilterBar'
+
+export default async function Dashboard() {
+  const data = await db.getDashboardData()
+  return (
+    <ClientFilterBar>
+      <ServerData data={data} />
+    </ClientFilterBar>
+  )
+}
+
+// ClientFilterBar.tsx — Client Component with state
+'use client'
+import { useState } from 'react'
+
+export function ClientFilterBar({ children }: { children: React.ReactNode }) {
+  const [filter, setFilter] = useState('all')
+  return (
+    <div>
+      <select onChange={e => setFilter(e.target.value)}>...</select>
+      {children}  {/* Server Component renders here */}
+    </div>
+  )
+}
+```
+
+The `children` prop is *content*, not *components-to-import*. The Client Component receives the already-rendered React element from the server tree. This is the only way to put a Server Component "inside" a Client Component visually without violating the import rule.
+
+## The Import Rule and Why It Matters
+
+A Client Component cannot `import` a Server Component. Not "should not" — *cannot*, because the bundler running on the client would have to bundle the Server Component, and Server Components are not allowed to ship.
+
+But a Server Component *can* `import` a Client Component. The Client Component file is marked `'use client'` at its top, the bundler treats it as a client-bundle entry point, and the Server Component renders a reference to it (in the RSC payload) that the client runtime resolves to the bundled component.
+
+The directionality matters for tree design:
+
+- Top-down: Server → Server → Server → Client → (only more Client below this point).
+- Pierce-through via children: Server → Client → (children prop receives) → Server → Server.
+
+A tree that follows the first pattern naturally pushes work to the server. A tree that violates it (a Client Component near the root that needs to render a Server Component as a non-children child) cannot be expressed; you'll be forced to restructure.
+
+## Data Flow Without an API Layer
+
+The classic React data-fetching pattern:
+
+1. Browser requests page → SSR returns HTML
+2. Browser hydrates page
+3. Client Component mounts, runs `useEffect`, calls `/api/data`
+4. API route handler runs, queries database, returns JSON
+5. Component re-renders with data
+
+RSC collapses steps 1–5 to:
+
+1. Browser requests page → Server Component runs, queries database directly, returns RSC payload (with data already baked in)
+
+The `/api/data` route does not need to exist. The Server Component reaches into the database, passes the result to a child component as a prop, and the prop arrives at the client *as the rendered output* — serialized in the RSC payload, never round-tripped through a JSON API.
+
+When does an API route still make sense? When something *outside* this app needs to read the data: a mobile app, a third-party integration, a server-to-server call. The API layer is no longer the only way to get data into the page; it's only what you need when there are multiple consumers.
+
+## Suspense and Streaming RSC
+
+A Server Component that awaits a slow query blocks the entire HTML response. Suspense unblocks the pattern: wrap the slow component in `<Suspense fallback={...}>` and the server flushes the surrounding tree immediately, then streams in the slow component's output when it resolves.
+
+```tsx
+// app/dashboard/page.tsx — Server Component
+export default async function Dashboard() {
+  return (
+    <>
+      <Header />
+      <Suspense fallback={<SkeletonChart />}>
+        <SlowChartData />  {/* awaits a 2-second query */}
+      </Suspense>
+      <Suspense fallback={<SkeletonTable />}>
+        <SlowTableData />  {/* awaits a 1.5-second query */}
+      </Suspense>
+    </>
+  )
+}
+```
+
+Both `SlowChartData` and `SlowTableData` start their queries in parallel (the Server Component renders both subtrees, and each `await` is a Promise that the renderer holds open). The chart and table fallback HTML ships immediately; the actual content streams in as each query resolves. Time-to-first-byte is bounded by the fastest non-Suspended path; time-to-interactive of each section is bounded by that section's own query.
+
+Two design rules:
+
+1. **Co-locate the Suspense boundary with the slow data, not above it.** A boundary too high makes more of the page wait; a boundary too low produces visible layout shift as content pops in.
+2. **Trigger parallel data fetches at the same level.** If two queries don't depend on each other, render their components as siblings (not parent/child) so their awaits happen in parallel.
+
+See `suspense-patterns` (when authored) for the wider Suspense discipline including error boundaries, nested fallbacks, and the relationship to React's transition APIs.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong | Fix |
+|---|---|---|
+| Whole page marked `'use client'` to use one button | Loses all RSC benefit; ships entire page as client bundle | Move `'use client'` to the leaf component that actually needs it |
+| `useEffect` to fetch data on mount | Hydration delay + double-fetch + lost streaming | Fetch in a Server Component ancestor and pass data as prop |
+| Importing a Client Component that wraps `children` and trying to put a Server Component import inside | Bundler treats the Server Component as client code | Pass the Server Component as `children` from a Server Component parent |
+| `await fetch('/api/data')` in a Server Component | Spending a round-trip for data you could query directly | Query the database directly; the API route is now redundant |
+| Passing a function (`onClick`) from Server Component to Client Component | Not serializable across the boundary | Define the handler in the Client Component, pass primitive props instead |
+| Reading `window` or `document` in a Server Component | Will crash at render time | Move browser-API code to a Client Component or to a `useEffect` |
+| One giant Suspense boundary at the page root | All slow content blocks together — no streaming benefit | Place boundaries near the slow data, one per independent slow section |
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] `'use client'` appears at the leaf where interactivity actually starts, not higher in the tree.
+- [ ] No Server Component imports a Client Component's internals; the Client Component imports from `'use client'`-marked files only at its top level.
+- [ ] No serialization-breaking values cross the boundary (no functions, no class instances, no Maps/Sets unless explicitly supported).
+- [ ] Slow data fetches are wrapped in Suspense boundaries co-located with the data.
+- [ ] No `useEffect` fetches for data that could be fetched server-side.
+- [ ] Server Components do not call hooks, do not attach event handlers, and do not read browser APIs.
+- [ ] Client Components do not import server-only libraries (DB drivers, file system modules, secret-reading helpers).
+- [ ] The component tree expresses the actual interactivity boundary; rebuild it if a Client Component is forced to wrap Server Components it should be a sibling of.
+
+## Grounding Sources
+
+- React RFC — [Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md). The original proposal and the formal model.
+- React docs — [Server Components](https://react.dev/reference/rsc/server-components). Official reference for the runtime contract.
+- React docs — [`'use client'`](https://react.dev/reference/rsc/use-client) and [`'use server'`](https://react.dev/reference/rsc/use-server). The directive semantics.
+- Next.js docs — [Server and Client Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) and [Composition Patterns](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns). The canonical working implementation.
+- Vercel — [How React Server Components Work](https://vercel.com/blog/understanding-react-server-components). Walk-through of the RSC payload and rendering pipeline.
+- Markbåge, S. et al. — [Introducing Zero-Bundle-Size React Server Components](https://legacy.reactjs.org/blog/2020/12/21/data-fetching-with-react-server-components.html). The first public introduction; useful for the design rationale.
+- Akinmade Adeleke, A. — [The Forensics of React Server Components](https://www.smashingmagazine.com/2024/05/forensics-react-server-components/). Deep dive on the RSC payload format and tree reconstruction.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| The mechanics of the `'use client'` / `'use server'` directive boundary itself (serialization rules, what crosses, RSC payload format) | `client-server-boundary` | client-server-boundary owns the boundary as a serialization mechanism; this skill owns the *design discipline* of where to draw the boundary in your component graph. |
+| Hook discipline on the Client Component side (Rules of Hooks, useEffect, useMemo) | `hooks-patterns` | hooks-patterns covers what Client Components do correctly. Server Components cannot use hooks at all. |
+| Choosing between SSR, SSG, ISR, and CSR rendering strategies | `rendering-models` | rendering-models owns the strategic rendering choice. RSC is one rendering mode among several. |
+| Designing the Server Actions / form-mutation surface | `server-actions-design` (when authored) | Server Actions are the *write* path; Server Components are the *read* path. They share infrastructure but have distinct design concerns. |
+| Streaming patterns broader than RSC (HTTP/2 push, SSE, WebSockets, AI streaming) | `streaming-architecture` | streaming-architecture covers streaming as a general protocol concern. RSC streaming is one application of that toolkit. |

package/marketplace/skills/sharding-strategy/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: sharding-strategy
+description: "Use when reasoning about horizontal partitioning of data across nodes for storage capacity and write throughput beyond a single node: the three foundational partitioning schemes (range, hash, directory/lookup), the shard-key choice that determines whether the system scales or hotspots, the resharding problem and how consistent hashing addresses it, cross-shard queries and the joins-and-transactions trade-off, the relationship to replication (sharding partitions data; replication copies each shard), and the failure modes (hot shard, skewed distribution, cross-shard transactions, range-end overload). Do NOT use for replicating the same data across nodes (use replication-patterns), the CAP/PACELC frame (use cap-theorem-tradeoffs), single-node performance tuning (use query-optimization), or indexing within a shard (use indexing-strategy)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/data\",\"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\":\"[\\\\\\\"sharding\\\\\\\",\\\\\\\"partitioning\\\\\\\",\\\\\\\"horizontal partitioning\\\\\\\",\\\\\\\"shard key\\\\\\\",\\\\\\\"hash partitioning\\\\\\\",\\\\\\\"range partitioning\\\\\\\",\\\\\\\"consistent hashing\\\\\\\",\\\\\\\"hot shard\\\\\\\",\\\\\\\"resharding\\\\\\\",\\\\\\\"cross-shard query\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how should we shard\\\\\\\",\\\\\\\"what's the right shard key\\\\\\\",\\\\\\\"hot shard\\\\\\\",\\\\\\\"cross-shard transaction\\\\\\\",\\\\\\\"consistent hashing\\\\\\\"]\",\"examples\":\"[\\\\\\\"choose a shard key for a multi-tenant system where 90% of queries are tenant-scoped\\\\\\\",\\\\\\\"diagnose a hot shard caused by skewed shard-key distribution\\\\\\\",\\\\\\\"design the resharding strategy when adding nodes to a hash-sharded cluster\\\\\\\",\\\\\\\"decide whether to accept cross-shard JOIN complexity or denormalize\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design replication topology for the same data (use replication-patterns)\\\\\\\",\\\\\\\"tune a single slow query (use query-optimization)\\\\\\\",\\\\\\\"design indexes within one shard (use indexing-strategy)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"indexing-strategy\\\\\\\",\\\\\\\"data-modeling\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"replication-patterns owns copying the same data across nodes; this skill owns splitting different data across nodes. The two compose: a sharded system can replicate each shard. They answer different questions.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"cap-theorem-tradeoffs owns the theoretical consistency-availability frame; this skill owns the operational partitioning that often interacts with it (cross-shard transactions have stronger consistency requirements than single-shard ones).\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"indexing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"indexing-strategy owns within-node retrieval; this skill owns how data is divided across nodes. Indexes within a shard are designed normally; cross-shard secondary indexes are a separate, harder problem.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns schema and access-pattern design; this skill owns the partitioning of that schema across nodes. The shard key is a schema design decision with operational consequences.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"data-modeling\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Sharding is to a database what tenant-based building partitioning is to a multinational corporation — replicating each office to multiple cities is fault tolerance (replication); putting *Sales* in Building A and *Engineering* in Building B *because they do not talk to each other* is sharding. The shard key is the rule that decides who goes in which building, and the most catastrophic operational outcome is choosing a rule that puts everyone in Building A on Monday morning and Building B on Tuesday morning — the hot shard, where the structure was right but the routing rule was wrong.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Sharding (horizontal partitioning) is the discipline of dividing a database's data across multiple nodes such that each node holds a subset (a shard) of the data. The unit of judgment is the *shard key*: the column or columns the system uses to route each row to a specific shard. Three foundational schemes exist — **range partitioning** (rows with shard-key values in a contiguous range go to the same shard), **hash partitioning** (the shard-key value is hashed; the hash determines the shard), and **directory / lookup partitioning** (an explicit map records which shard owns each key or key-range). Each scheme has its own access-pattern fit, resharding complexity, and hot-shard risk profile. The strategic discipline of sharding is choosing the shard key and scheme such that (a) the per-shard load is balanced, (b) common queries can be answered by a single shard (no cross-shard scatter-gather), and (c) the system can be resharded (add nodes, rebalance data) without unacceptable downtime.\\\\\\\",\\\\\\\"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/sharding-strategy/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/sharding-strategy/SKILL.md
+---
+
+# Sharding Strategy
+
+## Coverage
+
+The discipline of dividing a database's data across multiple nodes through horizontal partitioning. Covers the three foundational partitioning schemes (range, hash, directory), consistent hashing as the refinement that solves the resharding problem, the shard-key choice as the most consequential design decision, the cross-shard query and transaction trade-offs, the catalog of failure modes (hot shard, skewed distribution, range-boundary overload), the relationship to replication (sharding divides; replication copies; they compose), and the rule that sharding is one of the last optimizations to reach for after replication, caching, and denormalization.
+
+## Philosophy
+
+Sharding is the scaling tool of last resort. Replication scales reads; caching reduces load; denormalization eliminates joins; vertical scaling adds capacity. When write throughput, storage capacity, or geographic data placement exceeds what those tools provide, sharding becomes the answer.
+
+The shard key is the most consequential design decision. It determines which queries are fast (single-shard) and which are slow (scatter-gather), which operations are atomic (single-shard) and which require distributed commit (cross-shard), which growth patterns hotspot and which balance. A team that chooses the shard key well gains nearly linear scaling; a team that chooses it poorly pays operational complexity without capacity gain.
+
+The schema must be designed with sharding in mind from the start, or significant refactoring is required when sharding is later introduced. Queries must filter on the shard key; related data must be co-located on the same shard; cross-shard operations must be rare or accepted as slow. Sharding is a schema architecture, not just an operational technique.
+
+## The Three Partitioning Schemes
+
+| Scheme | How it routes | Strong for | Weak for |
+|---|---|---|---|
+| Range | Contiguous key ranges per shard | Range queries (`BETWEEN x AND y`) | Hotspots at range boundaries; resharding by split |
+| Hash | Hash(key) % N | Even balance; no range hotspots | Range queries become scatter-gather; resharding rehashes |
+| Consistent hashing | Hash ring; key → nearest clockwise shard | Adding shards moves only 1/N of data | Range queries still scatter-gather |
+| Directory | Explicit map per key | Flexibility; arbitrary routing | The directory itself becomes a bottleneck |
+
+Hash with consistent hashing is the default for most large-scale systems; range partitioning is used for time-series and naturally-ordered data; directory is rare but useful for arbitrary placement.
+
+## The Shard-Key Selection Rules
+
+A good shard key:
+
+1. **Appears in nearly every query's WHERE clause** — for shard-locality.
+2. **Distributes data evenly** — high cardinality; no value dominates traffic.
+3. **Is immutable for a row** — moving a row between shards is expensive.
+4. **Has predictable growth** — won't shift hotspots over time.
+5. **Matches the natural grain of operations** — common transactions are single-shard.
+
+Common keys:
+- **Multi-tenant SaaS**: `tenant_id`. Most queries are tenant-scoped; tenants are independent.
+- **Per-user data**: `user_id`. Most queries are user-scoped.
+- **Time-series**: `time_bucket(timestamp)`. Recent shards hot; older shards cold (often acceptable for time-series).
+- **Geographic**: `region`. Latency benefit; regulatory benefit.
+
+Bad keys:
+- `created_at` (range hotspot at latest range).
+- `status` (low cardinality; one value dominates).
+- A column not in most query WHERE clauses (scatter-gather every query).
+
+## Cross-Shard Query Trade-offs
+
+| Operation | Single-shard | Cross-shard |
+|---|---|---|
+| Lookup by shard key | Fast | n/a (must include shard key) |
+| Lookup not using shard key | Single-shard if data co-located | Scatter to every shard |
+| JOIN | Fast within shard | Slow or unavailable |
+| Aggregation | Fast | Scatter-gather; partial-aggregate-then-combine |
+| Transaction | ACID via single-shard primary | Two-phase commit or distributed consensus; slow and failure-prone |
+
+Schema design under sharding co-locates related data (store user's orders on user's shard) to make JOINs and transactions single-shard.
+
+## When Sharding Is The Right Tool
+
+| Workload property | Tool |
+|---|---|
+| Read load too high | Replication (read replicas) |
+| Cache hit rate possible | Caching layer |
+| Joins / aggregations slow | Denormalization, materialized views |
+| Single-node CPU/memory exceeded | Vertical scaling |
+| Storage approaching node limit | Sharding (or larger disks first) |
+| Write throughput exceeds primary | Sharding |
+| Geographic latency required | Sharding by region (with replication within region) |
+| Multi-tenant isolation required | Sharding by tenant |
+
+Sharding is the answer when write throughput or storage exceeds single-node capacity. Before that, simpler tools suffice.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Sharding is being considered after replication, caching, denormalization, and vertical scaling — not as a first response.
+- [ ] The shard key is chosen against the criteria: appears in queries, distributes evenly, immutable, predictable, matches operation grain.
+- [ ] Most production queries are single-shard. Scatter-gather queries are recognized as expensive and made rare.
+- [ ] Related data is co-located on the same shard for JOIN and transaction locality.
+- [ ] Cross-shard transactions are rare. Application design avoids them where possible.
+- [ ] Resharding plan exists before launch: how shards are added, how data moves, what downtime is expected.
+- [ ] Hot-shard detection is in place. Per-shard load metrics surface hotspots before they become incidents.
+- [ ] Consistent hashing is used over modulo hash where resharding is anticipated. Naive hash modulo locks the shard count.
+- [ ] The cross-shard query cost is documented and accepted. Reports and analytics that scatter-gather are run on read replicas or designed for the cost.
+- [ ] Sharding interacts with replication intentionally — each shard's replication strategy is designed, not defaulted.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Copying the same data to multiple nodes | `replication-patterns` | replication copies; sharding partitions |
+| The CAP / PACELC theoretical frame | `cap-theorem-tradeoffs` | CAP names the trade-off |
+| Tuning a slow query | `query-optimization` | query-optimization is single-query |
+| Designing indexes within a shard | `indexing-strategy` | indexing is within-node |
+| Designing schema | `data-modeling` | data-modeling is the schema design; this is the partitioning of the schema |
+| Single-node transactional behavior | `acid-fundamentals` | ACID is the single-system frame |
+
+## Key Sources
+
+- Karger, D., Lehman, E., Leighton, T., Panigrahy, R., Levine, M., & Lewin, D. (1997). ["Consistent Hashing and Random Trees: Distributed Caching Protocols for Relieving Hot Spots on the World Wide Web"](https://dl.acm.org/doi/10.1145/258533.258660). *STOC 1997*. The foundational paper on consistent hashing.
+- DeCandia, G., Hastorun, D., Jampani, M., et al. (2007). ["Dynamo: Amazon's Highly Available Key-Value Store"](https://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf). *SOSP 2007*. Industrial application of consistent hashing in sharded systems; basis of Cassandra and DynamoDB.
+- Chang, F., Dean, J., Ghemawat, S., et al. (2006). ["Bigtable: A Distributed Storage System for Structured Data"](https://research.google/pubs/pub27898/). *OSDI 2006*. Google's range-partitioning-based sharded store; basis of HBase and many others.
+- Corbett, J. C., Dean, J., Epstein, M., et al. (2012). ["Spanner: Google's Globally-Distributed Database"](https://research.google/pubs/pub39966/). *OSDI 2012*. Modern globally-distributed database with automatic sharding and consensus-based cross-shard transactions.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 6 (Partitioning) — modern comprehensive treatment of all three schemes.
+- MongoDB Manual. ["Sharding"](https://www.mongodb.com/docs/manual/sharding/). Reference for MongoDB's sharded cluster architecture.
+- Citus Data. ["Citus Documentation — Distributed Tables"](https://docs.citusdata.com/en/stable/sharding/data_modeling.html). Reference for Postgres + Citus distributed sharding.
+- Vitess. ["Vitess Documentation — Sharding"](https://vitess.io/docs/user-guides/configuration-basic/sharding/). Reference for Vitess's MySQL-based sharded architecture (YouTube, Slack, others).
+- Lakshman, A., & Malik, P. (2010). ["Cassandra: a decentralized structured storage system"](https://www.cs.cornell.edu/projects/ladis2009/papers/lakshman-ladis2009.pdf). The Cassandra paper; consistent-hashing-based leaderless sharded store.
+- Sadalage, P. J., & Fowler, M. (2012). *NoSQL Distilled*. Addison-Wesley. Practitioner reference covering sharding patterns across NoSQL system types.

package/marketplace/skills/shopify/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: shopify
+description: "Use when working with Shopify — Admin API, Storefront API, OAuth scopes, HMAC SHA-256 webhook verification, GraphQL query-cost handling, Online Store 2.0 themes (sections, blocks, Liquid), metafields and metaobjects, and App Proxy. Do NOT use for generic e-commerce design, non-Shopify storefronts, or internal event-contract design."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/integrations\",\"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\":\"[\\\\\\\"shopify admin api\\\\\\\",\\\\\\\"shopify storefront api\\\\\\\",\\\\\\\"shopify webhooks\\\\\\\",\\\\\\\"shopify oauth scopes\\\\\\\",\\\\\\\"shopify hmac verification\\\\\\\",\\\\\\\"online store 2.0 sections\\\\\\\",\\\\\\\"liquid templates\\\\\\\",\\\\\\\"shopify graphql query cost\\\\\\\",\\\\\\\"shopify metafields\\\\\\\",\\\\\\\"shopify rate limits\\\\\\\",\\\\\\\"shopify app proxy\\\\\\\"]\",\"triggers\":\"[\\\\\\\"shopify\\\\\\\",\\\\\\\"shopify webhook\\\\\\\",\\\\\\\"shopify api\\\\\\\",\\\\\\\"shopify theme\\\\\\\",\\\\\\\"shopify app\\\\\\\"]\",\"examples\":\"[\\\\\\\"Verify an incoming Shopify webhook by computing HMAC SHA-256 over the raw body and comparing against the X-Shopify-Hmac-Sha256 header\\\\\\\",\\\\\\\"Query the Shopify Admin GraphQL API for product variants with their metafields and handle query cost throttling\\\\\\\",\\\\\\\"Build an Online Store 2.0 section schema with block types and dynamic settings\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Design the event payload schema for our internal order-processing pipeline\\\\\\\",\\\\\\\"Implement Stripe Connect onboarding for a marketplace\\\\\\\",\\\\\\\"Refactor a generic shopping cart component that isn't Shopify-specific\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"printify\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"webhook-integration covers vendor-agnostic delivery, retries, and signing; this skill handles Shopify's specific topic names, X-Shopify-* header contract, and the 5-second response deadline before retry.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"Hand off to event-contract-design when modeling internal events downstream of Shopify webhooks — the contract surface there is your own system, not Shopify's.\\\\\\\"}]}\",\"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/shopify/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/shopify/SKILL.md
+---
+
+# Shopify
+
+## Coverage
+Shopify exposes four primary integration surfaces: the Admin API (REST and GraphQL, used by apps acting on the merchant's behalf), the Storefront API (GraphQL, customer-facing, unauthenticated by default with a public access token), themes (Liquid templating plus Online Store 2.0 JSON templates with sections and blocks), and webhooks (signed event delivery over HTTPS). Each surface has distinct authentication, rate-limit, and versioning rules. This skill covers all four and the seams between them.
+
+Authentication for public apps follows OAuth 2.0 authorization code flow: the merchant approves a comma-separated scope list (read_products, write_orders, etc.), the app receives a permanent offline access token, and that token is sent as the X-Shopify-Access-Token header. Webhooks are verified by computing HMAC SHA-256 over the raw request body using the app's API secret key (for app-managed webhooks) or the shop's webhook signature key (for shop-managed webhooks) and base64-comparing against the X-Shopify-Hmac-Sha256 header. The webhook handler must respond with 2xx within five seconds or Shopify retries with exponential backoff for up to 48 hours before disabling the subscription.
+
+Rate limits differ per surface. REST Admin API uses a leaky-bucket model — 40 requests with a 2/sec leak rate on standard plans, 80/4 on Shopify Plus. GraphQL Admin API uses a query-cost model: each request is scored before execution (1000-point bucket, 50/sec leak), and the response includes extensions.cost with actualQueryCost and throttleStatus so the client can pace itself. The Storefront API has separate, more generous limits. Online Store 2.0 themes organize content into sections (reusable, merchant-configurable blocks defined in JSON schema) and templates (JSON files referencing sections), replacing the older static Liquid-include model.
+
+Metafields and metaobjects extend native resources with typed custom data. Metafields attach to a parent resource (product, variant, customer, order, etc.) with a namespace.key path and a defined type (single_line_text_field, number_integer, json, file_reference, metaobject_reference, etc.). Metaobjects are standalone typed records and are queryable via GraphQL like first-class resources. App Proxy routes a path on the merchant's storefront domain to the app's backend with a signed query string, enabling authenticated storefront experiences without CORS.
+
+## Philosophy
+Shopify's APIs are explicit about cost and explicit about contract. The query-cost model, the HMAC requirement, the five-second webhook deadline, and the API versioning calendar (one stable version per quarter, four supported simultaneously) all push toward integrations that observe their own load and respond to drift rather than assume forever-availability. Treat each surface's contract as load-bearing: don't catch HMAC failures and proceed, don't skip query-cost inspection, don't pin to a soon-to-be-unsupported API version.
+
+The theme surface and the API surface should remain separable. Online Store 2.0 lets merchants customize themes without code; an app that imposes UI through Liquid edits will conflict with merchant theme updates and theme-store apps. Prefer App Blocks and App Embeds (theme app extensions) over Liquid injection wherever the integration needs to render storefront UI.
+
+## Verification
+- The webhook handler computes HMAC SHA-256 over the raw, undecoded request body — not the parsed JSON — and uses a constant-time comparison against the header value.
+- OAuth scopes requested match scopes actually used. Audit by listing every API endpoint called and confirming the minimum scope per the Shopify REST Admin API reference.
+- GraphQL Admin clients read extensions.cost.throttleStatus on every response and back off when currentlyAvailable drops below the next expected query cost.
+- The integration declares a target API version (e.g., 2026-01) and a planned upgrade path; calls without an explicit version pin fall back to the oldest supported version and break unpredictably.
+- Webhook subscriptions are recreated on app reinstall — uninstall deletes them. The install flow re-registers all required topics.
+- For theme app extensions, blocks are testable in the merchant's theme editor and respect the merchant's existing section group layout.
+
+## Do NOT Use When
+- The integration target is a generic e-commerce platform (WooCommerce, BigCommerce, Magento, custom). Use the platform-specific skill or api-design for a vendor-neutral approach.
+- You are designing internal event contracts that happen to be triggered by Shopify webhooks — the contract surface is yours. Use event-contract-design.
+- The task is generic webhook signing and retry semantics across multiple providers. Use webhook-integration.
+- The work is product strategy, merchandising, or marketing for a Shopify store rather than technical work on the platform.
+- You are building a storefront UI component that does not touch Shopify APIs or themes directly. Use frontend-architecture or design-module-composition.