@skill-graph/cli 0.5.6

package/marketplace/skills/cron-scheduling/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: cron-scheduling
+description: "This skill provides cron job architecture patterns for web applications: Inngest schedule integration, Vercel Cron configuration, retry logic, monitoring and alerting for failed crons, and idempotency requirements. Load when designing scheduled tasks, configuring cron triggers, debugging missed or duplicate executions, or implementing monitoring for recurring jobs."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/scheduling\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-29\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-29\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"cron-scheduling\\\\\\\",\\\\\\\"cron\\\\\\\",\\\\\\\"scheduling\\\\\\\"]\",\"triggers\":\"[\\\\\\\"cron-scheduling-skill\\\\\\\",\\\\\\\"cron-job-skill\\\\\\\",\\\\\\\"scheduled-task-skill\\\\\\\",\\\\\\\"vercel-cron-skill\\\\\\\",\\\\\\\"recurring-job-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"background-jobs\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"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/cron-scheduling/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/cron-scheduling/SKILL.md
+---
+# Cron Scheduling Skill
+
+## Domain Context
+
+**What is this skill?** This skill provides cron job architecture patterns for web applications: Inngest schedule integration, Vercel Cron configuration, retry logic, monitoring and alerting for failed crons, and idempotency requirements. Load when designing scheduled tasks, configuring cron triggers, debugging missed or duplicate executions, or implementing monitoring for recurring jobs.
+> A cron that runs twice is worse than a cron that doesn't run. Idempotency is not optional.
+
+## Coverage
+
+This skill covers cron expression syntax and scheduling precision, Vercel Cron configuration (`vercel.json` cron routes), Inngest scheduled function patterns (cron triggers vs event-driven), idempotency guarantees for scheduled jobs, retry and failure handling for cron-triggered work, monitoring and alerting for missed or failed cron executions, timezone handling in cron schedules, and the decision framework for choosing between Vercel Cron, Inngest schedules, and external cron services.
+
+## Philosophy
+
+Cron jobs are the most deceptively simple infrastructure in web applications. The expression `0 9 * * *` looks trivial, but the implementation must handle: what happens when the job runs twice (deploy overlap), what happens when the job fails silently (no monitoring), what happens when the job takes longer than the interval (overlap), and what happens at DST transitions (timezone drift). Every anti-pattern in this skill was observed in production. The skill exists because agents routinely create cron schedules without idempotency, without monitoring, and without considering the failure modes that only surface under real-world conditions.
+
+## Architecture
+
+### Cron Platform Decision Matrix
+
+| Platform | Max Duration | Cold Start | Retry Built-in | Monitoring | Best For |
+|----------|-------------|------------|-----------------|------------|----------|
+| **Vercel Cron** | 60s (Hobby) / 300s (Pro) | Yes | No | Basic (logs) | Lightweight triggers that dispatch to background jobs |
+| **Inngest Cron** | Configurable (step functions) | No (warm) | Yes (built-in) | Dashboard + webhooks | Complex scheduled workflows with retry and state |
+| **External (e.g., cron-job.org)** | N/A (HTTP trigger) | Depends on target | No | External | When the app has no built-in cron capability |
+
+**Key architectural rule:** Vercel Cron should trigger work, not perform work. The cron route should dispatch an Inngest event or enqueue a background job, then return 200 immediately. Never put long-running logic directly in a Vercel Cron handler.
+
+### Vercel Cron Configuration
+
+```json
+// vercel.json
+{
+  "crons": [
+    {
+      "path": "/api/cron/daily-digest",
+      "schedule": "0 9 * * *"
+    },
+    {
+      "path": "/api/cron/sync-orders",
+      "schedule": "*/15 * * * *"
+    }
+  ]
+}
+```
+
+**Security:** Vercel Cron requests include a `CRON_SECRET` header. Always verify this header in the route handler to prevent unauthorized execution:
+
+```typescript
+// api/cron/daily-digest/route.ts
+import { verifyCronSecret } from "@/lib/auth/verify-cron-secret";
+
+export async function GET(request: Request) {
+  const authError = verifyCronSecret(request);
+  if (authError) return authError;
+  // Dispatch work, do not perform work here
+  await inngest.send({ name: 'cron/daily-digest.triggered' });
+  return new Response('OK', { status: 200 });
+}
+```
+
+### Inngest Scheduled Functions
+
+```typescript
+// Inngest cron function — preferred for complex scheduled work
+export const dailyDigest = inngest.createFunction(
+  {
+    id: 'daily-digest',
+    retries: 3,
+    concurrency: { limit: 1 },  // Prevent overlap
+  },
+  { cron: '0 9 * * *' },       // Inngest-native cron trigger
+  async ({ step }) => {
+    const orgs = await step.run('fetch-orgs', async () => {
+      return db.query('SELECT id FROM organizations WHERE digest_enabled = true');
+    });
+    for (const org of orgs) {
+      await step.run(`send-digest-${org.id}`, async () => {
+        return sendDigestEmail(org.id);
+      });
+    }
+  }
+);
+```
+
+## Implementation Patterns
+
+### 1. Idempotency for Cron Jobs
+
+Every cron job must be idempotent: running it twice with the same inputs produces the same result. This is not defensive programming; it is a hard requirement because:
+
+- Vercel may invoke a cron route during overlapping deployments
+- Inngest retries failed steps automatically
+- Manual re-runs during debugging are common
+
+**Pattern:** Use an idempotency key based on the scheduled execution window:
+
+```typescript
+const idempotencyKey = `digest-${orgId}-${format(new Date(), 'yyyy-MM-dd')}`;
+const existing = await db.query(
+  'SELECT 1 FROM cron_executions WHERE idempotency_key = $1',
+  [idempotencyKey]
+);
+if (existing.rows.length > 0) {
+  return { skipped: true, reason: 'already executed' };
+}
+// Execute, then record
+await db.query(
+  'INSERT INTO cron_executions (idempotency_key, executed_at) VALUES ($1, NOW())',
+  [idempotencyKey]
+);
+```
+
+### 2. Cron Expression Reference
+
+| Expression | Meaning | Common Use |
+|-----------|---------|------------|
+| `* * * * *` | Every minute | Health checks (use sparingly) |
+| `*/5 * * * *` | Every 5 minutes | Order sync polling |
+| `*/15 * * * *` | Every 15 minutes | Data refresh, cache warm |
+| `0 * * * *` | Every hour, on the hour | Hourly reports |
+| `0 9 * * *` | Daily at 09:00 UTC | Daily digest |
+| `0 9 * * 1` | Monday at 09:00 UTC | Weekly summary |
+| `0 0 1 * *` | First day of month, midnight | Monthly rollup |
+
+**Timezone rule:** All cron expressions in Vercel and Inngest execute in UTC. If the user expects "9am Eastern", compute the UTC offset and account for DST transitions. Document the intended local time as a comment next to every cron expression.
+
+### 3. Monitoring and Alerting
+
+A cron job that fails silently is worse than no cron job. Implement monitoring at three levels:
+
+| Level | What to Monitor | Alert When |
+|-------|----------------|------------|
+| **Execution** | Did the job start? | No execution within expected window + buffer |
+| **Completion** | Did the job finish? | Execution started but no completion within timeout |
+| **Result** | Did the job produce correct output? | Completion with error status or unexpected result count |
+
+**Heartbeat pattern:** After each successful cron execution, ping an external heartbeat monitor (e.g., Cronitor, Better Uptime, or a custom endpoint). If the heartbeat is missed, the monitor alerts the team.
+
+```typescript
+// After successful cron execution
+await fetch(`${process.env.HEARTBEAT_URL}/cron-daily-digest`, {
+  method: 'POST',
+  body: JSON.stringify({ status: 'ok', processedCount: orgs.length }),
+});
+```
+
+### 4. Overlap Prevention
+
+When a cron job takes longer than its interval (e.g., a 15-minute sync that runs every 10 minutes), overlapping executions corrupt data or cause duplicate processing.
+
+**Solutions:**
+- **Inngest concurrency limit:** Set `concurrency: { limit: 1 }` on the function
+- **Database lock:** Acquire an advisory lock at the start; skip if already held
+- **Execution record:** Check if a previous run is still in-progress before starting
+
+### 5. Graceful Degradation
+
+When a cron job fails, it must:
+1. Log the failure with structured context (job name, execution window, error)
+2. Retry with exponential backoff (Inngest does this automatically)
+3. After max retries, alert the team and record the failure
+4. Never leave the system in a partial state — use transactions for atomicity
+
+## Anti-Patterns
+
+1. **Long-running logic in Vercel Cron handlers.** Vercel Cron routes have a 60s (Hobby) or 300s (Pro) timeout. Put the work in an Inngest function or background job; the cron route should only trigger.
+
+2. **No idempotency.** A cron that sends duplicate digest emails or double-processes orders because it ran twice during a deploy. Every cron must handle re-execution gracefully.
+
+3. **Silent failures.** A cron that catches all errors and returns 200. Failed crons must surface errors through logging and alerting, not swallow them.
+
+4. **Missing timezone documentation.** A cron expression `0 9 * * *` without a comment explaining the intended local time. When DST shifts, 9am UTC becomes 4am or 5am Eastern, surprising the user.
+
+5. **No overlap protection.** A data sync cron that runs every 5 minutes but occasionally takes 8 minutes, causing two instances to process the same data concurrently.
+
+6. **Cron for real-time needs.** Using a 1-minute cron to poll for new orders instead of using webhooks. Cron is for periodic batch work, not real-time data ingestion.
+
+## Key Files
+
+When working in a project with cron scheduling:
+
+- `vercel.json` — Vercel Cron route definitions
+- `api/cron/` or `app/api/cron/` — Cron route handlers
+- Inngest function definitions — for cron-triggered step functions
+- `cron_executions` table (if it exists) — idempotency tracking
+- Monitoring service configuration — heartbeat endpoints
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every cron handler verifies the `CRON_SECRET` authorization header
+- [ ] Every cron job is idempotent (safe to run twice)
+- [ ] Vercel Cron routes dispatch work rather than performing long-running operations
+- [ ] Overlap prevention is configured for jobs that could exceed their interval
+- [ ] Monitoring alerts exist for missed or failed executions
+- [ ] Timezone is documented as a comment next to every cron expression
+- [ ] Retry logic exists for transient failures
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Event-driven job orchestration (not time-based) | `inngest-orchestration` | Inngest covers event-driven patterns; this skill covers time-based triggers |
+| General background job queue patterns | `background-jobs` | Job queue architecture is broader than cron-specific scheduling |
+| Data synchronization strategies | `data-sync` | Data sync covers webhook ingestion and polling; cron is one trigger mechanism |
+| Alert rule evaluation and dispatch | `alert-dispatch` | Alert dispatch covers when and how to send alerts, not how to schedule the check |
+
+---
+
+*Version 1.0.0 -- 2026-03-29. Initial creation.*

package/marketplace/skills/dark-mode-implementation/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: dark-mode-implementation
+description: "Use when implementing dark mode — prefers-color-scheme detection, theme persistence, flash-of-unstyled-theme prevention, color token mirroring, image and asset variants, and meta theme-color updates. Do NOT use for designing the dark palette itself, designing the token architecture, or generic theme-switching across more than two themes."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/visual\",\"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\":\"[\\\\\\\"dark mode\\\\\\\",\\\\\\\"prefers-color-scheme\\\\\\\",\\\\\\\"theme persistence\\\\\\\",\\\\\\\"flash of unstyled theme\\\\\\\",\\\\\\\"flash of incorrect theme\\\\\\\",\\\\\\\"color-scheme css property\\\\\\\",\\\\\\\"meta theme-color\\\\\\\",\\\\\\\"dark mode images\\\\\\\",\\\\\\\"picture source media\\\\\\\",\\\\\\\"system theme detection\\\\\\\",\\\\\\\"light dark css function\\\\\\\"]\",\"triggers\":\"[\\\\\\\"dark mode\\\\\\\",\\\\\\\"prefers-color-scheme\\\\\\\",\\\\\\\"light dark toggle\\\\\\\",\\\\\\\"system theme\\\\\\\",\\\\\\\"FOUC dark mode\\\\\\\"]\",\"examples\":\"[\\\\\\\"Add a dark mode toggle with system / light / dark options and persist the user's choice\\\\\\\",\\\\\\\"Eliminate the white flash that appears for a moment when a dark-mode user loads the page\\\\\\\",\\\\\\\"Provide dark variants of the marketing illustrations and the favicon\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Pick the dark mode color palette values\\\\\\\",\\\\\\\"Design the three-tier token architecture\\\\\\\",\\\\\\\"Build a multi-brand theme system with five themes\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"color-system-design\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"frontend-architecture\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"theme-system-design defines the token layering that makes dark mode a token-mapping change; this skill handles the integration mechanics on top of that foundation.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"color-system-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"The dark palette and its contrast pairings are color-system-design's responsibility; this skill consumes them.\\\\\\\"}]}\",\"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/dark-mode-implementation/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/dark-mode-implementation/SKILL.md
+---
+
+# Dark Mode Implementation
+
+## Coverage
+A dark mode implementation handles five concerns: detecting the user's preference (system, explicit choice, persisted choice), applying the right theme before first paint, propagating theme changes at runtime, swapping color-sensitive assets, and updating browser-chrome hints. Each has well-defined web platform primitives.
+
+Detection uses the prefers-color-scheme media query (window.matchMedia('(prefers-color-scheme: dark)')), which reflects the operating system or browser-level preference. Most products offer three user choices — System, Light, Dark — where System defers to the media query and the other two override it. The chosen mode is persisted (localStorage or a cookie) and read on every load. The CSS color-scheme property tells the user agent which schemes a page supports, enabling correct rendering of native form controls, scrollbars, and the default page background; declare color-scheme: light dark on :root for sites that support both.
+
+Flash-of-incorrect-theme (sometimes called FOUC for theme) occurs when the browser paints the light default before the persisted dark preference is applied. The fix is a small, blocking inline script in <head> that reads the persisted preference and sets a class or data attribute on <html> synchronously before stylesheets resolve. Frameworks with server-side rendering must serialize the resolved theme into the HTML response, often by reading a cookie on the server.
+
+The CSS Color Module Level 5 light-dark() function (light-dark(white, black)) lets a property declare both schemes inline and the user agent picks based on color-scheme. This is supported in current browsers and reduces the boilerplate of paired custom properties for simple cases; for token-driven systems, paired :root and [data-theme="dark"] custom property assignments remain the typical approach.
+
+Asset handling covers three categories. Raster images that have brand-color elements need dark variants delivered via <picture> with <source media="(prefers-color-scheme: dark)"> (the markup-driven approach) or via CSS background-image swapping. SVG illustrations can use currentColor or CSS custom properties for fill/stroke and update automatically. Favicons can declare a dark variant via <link rel="icon" media="(prefers-color-scheme: dark)" href="...">. Embedded videos and iframes (YouTube, Maps) often have their own theme parameter that needs to be passed via URL.
+
+Browser chrome hints include the meta theme-color tag (<meta name="theme-color" content="..." media="(prefers-color-scheme: dark)">), which sets the address bar color on mobile browsers, the Safari toolbar tint, and the PWA splash screen. Pair it with a light variant via media= so the chrome matches the active theme. Apple-specific apple-mobile-web-app-status-bar-style is now overridden by theme-color on supported versions.
+
+## Philosophy
+Dark mode is not a re-skin; it is a parallel design surface. Image contrast, shadow strategy (shadows on dark backgrounds work differently — often replaced with subtle borders or elevated background tints), focus ring visibility, and chart palettes all need attention. Treating dark mode as a CSS-only change produces a dark mode that technically works and feels half-finished.
+
+The user's explicit choice overrides the system. A user who has toggled to Dark on your site once expects Dark on the next visit regardless of what their OS is doing. Persistence is not optional, and a System option is a separate, third state from "no preference saved."
+
+## Verification
+- No flash of incorrect theme occurs on cold load for a dark-mode user; verified by throttling network and watching the first paint.
+- The CSS color-scheme property is declared on :root with the schemes the page supports, so native form controls render correctly in dark mode.
+- Brand-color images (illustrations, hero photos with light backgrounds) have dark variants delivered via <picture> source matching or equivalent.
+- The meta theme-color tag has paired light and dark variants and matches the active theme.
+- The favicon has a dark variant where the design needs it (e.g., dark logos on transparent backgrounds become invisible against dark browser tabs).
+- The user's explicit choice (light/dark/system) is persisted and restored across reloads; toggling away from System and back is observable.
+- All interactive states (focus rings, hover, selected) are visible in dark mode and meet contrast requirements; verified visually and via automated contrast testing.
+
+## Do NOT Use When
+- The task is choosing the dark palette values themselves. Use color-system-design.
+- The work is defining the token architecture that makes theming possible. Use theme-system-design.
+- The product requires more than two themes (multi-brand white-label, three or more visual modes). Use theme-system-design for the architecture; this skill covers the dark-specific platform integrations only.
+- You are auditing for WCAG contrast violations specifically. Use a11y for the criteria; the palette decisions come from color-system-design.
+- The bug is a single component looking wrong in dark mode after the system is otherwise complete. That is component-level debugging, not implementation architecture.

package/marketplace/skills/data-modeling/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: data-modeling
+description: "Use when designing logical or physical data structures: entities as stored data, keys, constraints, normalization, denormalization, provenance, lifecycle, indexing implications, and schema tradeoffs. Do NOT use for pre-implementation business concept discovery (use `conceptual-modeling`), migrations against an existing database (use `database-migration`), or formal ontology semantics (use `ontology-modeling`)."
+license: MIT
+compatibility: "Portable data-modeling discipline across relational, document, graph, event-sourced, and warehouse-style systems."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"data/modeling\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"data modeling\\\\\\\",\\\\\\\"logical data model\\\\\\\",\\\\\\\"physical data model\\\\\\\",\\\\\\\"entity relationship\\\\\\\",\\\\\\\"normalization\\\\\\\",\\\\\\\"denormalization\\\\\\\",\\\\\\\"primary key\\\\\\\",\\\\\\\"foreign key\\\\\\\",\\\\\\\"schema design\\\\\\\",\\\\\\\"data provenance\\\\\\\",\\\\\\\"indexing implications\\\\\\\"]\",\"examples\":\"[\\\\\\\"turn this conceptual model into a logical schema with keys and constraints\\\\\\\",\\\\\\\"should this be normalized, denormalized, or materialized as a view?\\\\\\\",\\\\\\\"model provenance for revenue, cost, and refund fields\\\\\\\",\\\\\\\"choose identifiers and uniqueness constraints before writing the migration\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"identify business entities and relationships without implementation details\\\\\\\",\\\\\\\"write and apply the actual migration for an existing database\\\\\\\",\\\\\\\"define OWL/RDF class axioms and reasoning rules\\\\\\\",\\\\\\\"design REST endpoints for these resources\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling is implementation-neutral; data-modeling adds logical and physical data constraints\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"database-migration\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"database-migration changes an existing database; data-modeling decides the schema shape before migration\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"ontology-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"ontology-modeling formalizes meaning; data-modeling structures persisted data\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design exposes resources and operations; data-modeling stores and constrains underlying data\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"database-migration\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"state-machine-modeling\\\\\\\"],\\\\\\\"depends_on\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"database-migration\\\\\\\",\\\\\\\"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/data-modeling/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/data-modeling/SKILL.md
+---
+
+# Data Modeling
+
+## Coverage
+
+Design logical and physical data structures from a validated conceptual model. Covers entities as stored records, identifiers, primary keys, foreign keys, uniqueness, cardinality enforcement, normalization, denormalization, derived data, materialized views, provenance, retention, indexing implications, and schema-change risk.
+
+## Philosophy
+
+Data models are long-lived promises. Application code changes quickly; stored data and integrations remember mistakes. A good data model preserves business meaning, supports expected queries, and prevents invalid states without overfitting to today's UI.
+
+Do not jump from concept to migration. First decide what must be stored, what can be derived, what must be constrained, and what must remain queryable.
+
+## Method
+
+1. Start from a conceptual model or extract one quickly.
+2. Define identity and uniqueness for each stored entity.
+3. Map relationships to keys, junctions, embeddings, or references.
+4. Decide normalization vs denormalization based on write/read patterns and consistency requirements.
+5. Mark derived fields and their source of truth.
+6. Add provenance for data sourced from external systems or calculations.
+7. Check query patterns and indexing implications.
+8. Hand off to `database-migration` for implementation changes.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/data-modeling.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/data-modeling.json). The checklist below is the authoring gate for persistence-model decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Every stored entity has identity and uniqueness criteria
+- [ ] Relationship cardinality is enforceable or intentionally documented
+- [ ] Derived data names its source and refresh rule
+- [ ] Denormalization has a stated read/write tradeoff
+- [ ] External-source fields carry provenance
+- [ ] Retention and privacy obligations are represented where relevant
+- [ ] Expected queries can be served without accidental full scans at scale
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `conceptual-modeling` | You are still discovering business concepts without persistence details. |
+| `database-migration` | You need to write, apply, or verify a concrete migration. |
+| `ontology-modeling` | You need formal semantic axioms or reasoning constraints. |
+| `api-design` | You need endpoint, request, response, error, and versioning design. |

package/marketplace/skills/data-modeling-fundamentals/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: data-modeling-fundamentals
+description: "Use when reasoning about the foundational theory beneath data modeling: Codd's relational model (1970) and the algebra it sits on, the normal forms (1NF, 2NF, 3NF, BCNF, 4NF, 5NF) as a precise sequence of constraint-elimination steps, functional dependencies and the closure algorithm, Chen's entity-relationship model (1976) as a higher-abstraction layer above relations, the principled case for and against denormalization, the relational-vs-document tradeoff at the conceptual level, the immutable-data-model alternative (event sourcing, append-only tables), and the historical and theoretical literature that grounds modern database design. Do NOT use for practical persistence design and method (use data-modeling), for safely applying changes to an existing schema (use schema-evolution), for choosing what indexes to maintain (use indexing-strategy), or for the conceptual-modeling layer above the data model (use conceptual-modeling)."
+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\":\"[\\\\\\\"relational model\\\\\\\",\\\\\\\"Codd\\\\\\\",\\\\\\\"normalization\\\\\\\",\\\\\\\"normal forms\\\\\\\",\\\\\\\"functional dependency\\\\\\\",\\\\\\\"1NF\\\\\\\",\\\\\\\"2NF\\\\\\\",\\\\\\\"3NF\\\\\\\",\\\\\\\"BCNF\\\\\\\",\\\\\\\"4NF\\\\\\\",\\\\\\\"5NF\\\\\\\",\\\\\\\"entity-relationship model\\\\\\\",\\\\\\\"Chen\\\\\\\",\\\\\\\"relational algebra\\\\\\\",\\\\\\\"denormalization\\\\\\\",\\\\\\\"immutable data model\\\\\\\",\\\\\\\"event sourcing\\\\\\\"]\",\"triggers\":\"[\\\\\\\"what normal form is this\\\\\\\",\\\\\\\"should this be normalized or denormalized\\\\\\\",\\\\\\\"explain functional dependencies\\\\\\\",\\\\\\\"relational vs document model\\\\\\\",\\\\\\\"Codd's rules\\\\\\\"]\",\"examples\":\"[\\\\\\\"explain why a table is in 2NF but not 3NF and what change would bring it to 3NF\\\\\\\",\\\\\\\"decide whether a workload's read pattern justifies denormalization against the theoretical baseline\\\\\\\",\\\\\\\"compare the relational, document, and event-sourced models at the conceptual level for a given domain\\\\\\\",\\\\\\\"trace a functional-dependency closure to find a candidate key\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design the practical schema for a new persistence layer (use data-modeling)\\\\\\\",\\\\\\\"apply an expand-contract migration to change an existing schema (use schema-evolution)\\\\\\\",\\\\\\\"choose which indexes to maintain (use indexing-strategy)\\\\\\\",\\\\\\\"discover business entities without implementation details (use conceptual-modeling)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"data-modeling\\\\\\\",\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"entity-relationship-modeling\\\\\\\",\\\\\\\"schema-evolution\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns the practical method of designing persistence — turn a conceptual model into a working schema with keys, constraints, indexing implications. This skill owns the theoretical foundations beneath that method — what normal forms guarantee, what Codd's relational model formally provides, the algebra that makes joins composable, and the principled justification for or against denormalization. They are companion skills: theory and practice.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling owns implementation-neutral business-concept discovery (entities, relationships, attributes as business reality). This skill owns the formal data-model layer below conceptual modeling: the relational model, the algebra, the dependency theory. The two compose: conceptual modeling identifies entities; data-modeling-fundamentals formalizes how those entities map to relations.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"entity-relationship-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"entity-relationship-modeling owns the ER notation and method (entities, relationships, cardinality, ER diagrams) as developed by Chen and extended by Bachman, Barker, and others. This skill owns the broader theoretical frame including the relational model that ER diagrams typically translate into. The boundary: ER is the diagramming and discovery layer; the relational model is the formal target.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"schema-evolution\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"schema-evolution owns the migration mechanics — how to change a deployed schema without downtime. This skill owns the static theory of what a good schema is. The decision 'this schema should be in 3NF' is grounded by this skill; the application of that decision to a live database is `schema-evolution`'s domain.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"data-modeling\\\\\\\",\\\\\\\"entity-relationship-modeling\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Data-modeling fundamentals is to schema design what Euclidean geometry is to architecture — the architect does not draw a right-angled wall by intuition each time; they draw it because the geometry guarantees stability and squares lock together. A schema in 3NF is the wall built to plumb, where every dependency is structural and no anomaly is hiding in the carpentry. Denormalization is the deliberate decision to cut a non-load-bearing wall for an open floor plan — defensible when the workload justifies it, indefensible when the cost is invisible.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Data-modeling fundamentals is the body of formal theory beneath practical database design: Codd's relational model (1970), which represents data as relations (sets of tuples) and provides a closed algebra (selection, projection, join, union, intersection, difference, division) for querying them; the normal forms (1NF through 5NF and BCNF), each defined by the elimination of a specific class of dependency anomaly; the theory of functional dependencies and the closure algorithm used to derive normal-form membership and candidate keys; Chen's entity-relationship model (1976), which sits above the relational model as a higher-abstraction modeling layer that translates downward into relations; the principled justifications for normalization (avoid update, insert, delete anomalies) and for denormalization (workload-driven performance trade-offs against the normal-form baseline); and the alternative data models — document, graph, key-value, columnar, event-sourced — each of which can be characterized by what relational primitives it preserves, relaxes, or trades for a different access pattern. The skill is the *theory* a practitioner draws on when deciding what shape data should take and why; the practical application of that theory is `data-modeling`.\\\\\\\",\\\\\\\"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/data-modeling-fundamentals/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/data-modeling-fundamentals/SKILL.md
+---
+
+# Data Modeling Fundamentals
+
+## Coverage
+
+The body of formal theory beneath practical database design. Covers Codd's relational model (1970), the closed relational algebra (selection, projection, join, union, difference, division), functional dependencies and the closure algorithm, the normal forms (1NF through 5NF, BCNF, with notes on 6NF and DKNF), Chen's entity-relationship model (1976) and its extensions, the principled framing of normalization vs denormalization as anomaly-elimination vs measured read-performance trade, the alternative data models (document, graph, key-value, columnar, time-series, event-sourced) characterized by which relational primitives they preserve or trade, and the foundational literature from Codd, Chen, Fagin, Date, Garcia-Molina, and Kleppmann that grounds modern database design.
+
+## Philosophy
+
+Data outlives application code. Application code is rewritten in years; stored data and integrations persist for decades. A bad data model is the most expensive kind of technical debt — every consumer (application, report, integration, analytical job) depends on it, and changing it requires coordinated migration across all of them. The discipline of getting the model right early pays back over the data's full lifetime.
+
+Without the theory, design becomes folklore. Teams normalize because someone said normalization is good; they denormalize because someone said joins are slow. Neither claim is wrong, but without the theory underneath, the decisions are tribal rather than reasoned. The theoretical layer — what normal forms guarantee, what anomalies each form eliminates, what relational algebra closure buys — makes the conversation precise.
+
+Normalization is a principled cleanup procedure, not an aesthetic standard. Each normal form eliminates a specific class of anomaly; the question is not "what normal form is this in" but "are the anomalies this form admits operationally relevant to our workload." The discipline is matching the form to the workload.
+
+## The Normal Forms — A Sequence of Anomaly Eliminations
+
+| Form | Eliminates | Defined by |
+|---|---|---|
+| 1NF | Repeating groups, non-atomic attributes | Atomic values only |
+| 2NF | Partial-key dependencies | 1NF + every non-key attribute fully depends on the whole key |
+| 3NF | Transitive non-prime dependencies | 2NF + no non-key attribute depends on another non-key attribute |
+| BCNF | Anomalies in overlapping candidate keys | Every non-trivial FD has a superkey on its left |
+| 4NF | Multi-valued-dependency anomalies | BCNF + no non-trivial multi-valued dependencies |
+| 5NF | Join-dependency anomalies | 4NF + every join dependency is implied by candidate keys |
+
+**The discipline:** start with FDs, derive closure, find candidate keys, test normal-form membership, decompose to the level where the anomalies that matter for the workload are eliminated.
+
+## The Relational Algebra — Why It Composes
+
+| Operator | Notation | What it does |
+|---|---|---|
+| Selection | σ_predicate(R) | Filter rows |
+| Projection | π_columns(R) | Filter columns |
+| Join | R ⋈ S | Combine relations on matching attributes |
+| Union | R ∪ S | Set union of compatible relations |
+| Difference | R − S | Set difference |
+| Intersection | R ∩ S | Set intersection (derivable) |
+| Division | R ÷ S | Tuples in R matching all values in S |
+| Rename | ρ_a→b(R) | Rename attributes |
+
+Every operator's input and output are relations. This *closure* is what makes the algebra compose — JOIN of JOIN of JOIN is still a relation, queryable by further algebra. SQL inherits this property; the document, graph, and key-value alternatives give it up in exchange for different access patterns.
+
+## Normalization vs Denormalization — The Principled Tradeoff
+
+| Path | Benefit | Cost |
+|---|---|---|
+| Normalize to BCNF | No update, insert, delete anomalies | More tables, more joins, slower reads |
+| Denormalize selectively | Faster reads for measured access patterns | Update anomalies application must manage |
+| Materialized view | Pre-computed aggregations | Refresh complexity; staleness window |
+| Embedded reference (document-style) | Read locality | Update fan-out across embedded copies |
+| Pre-computed aggregate | O(1) reads of sums/counts | Write-time computation; consistency burden |
+
+**Principled framing:** normalize to eliminate operationally-relevant anomalies; denormalize specific paths for measured read-performance need; accept the consistency burden explicitly.
+
+## Alternative Models — What They Trade
+
+| Model | Preserves | Trades away | Wins for |
+|---|---|---|---|
+| Document (MongoDB) | Per-document atomicity | Cross-document joins, transactional consistency | Aggregate-as-document reads |
+| Graph (Neo4j) | Relationship traversal | Tabular query, aggregation | Many-hop relationship queries |
+| Key-value (Redis) | Point access | Structured query | Caching, simple lookups |
+| Wide-column (Cassandra) | Distributed scale | Joins, ACID transactions | Distributed writes, time-series |
+| Columnar (BigQuery, ClickHouse) | Analytical aggregation | Point access, transactional updates | OLAP workloads |
+| Time-series (TimescaleDB, InfluxDB) | Timestamp-indexed writes | Generic relational query | Metrics, IoT, observability |
+| Event-sourced | Full history | Current-state read complexity, storage | Audit, financial ledger |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The functional dependencies of the schema have been listed explicitly. Normalization claims are grounded in FDs, not in intuition.
+- [ ] The normal form chosen for each table matches the workload's anomaly tolerance. Higher form is not asserted as "better" without justification.
+- [ ] Denormalization decisions have a measured read-performance justification and a documented plan for maintaining the redundant data consistently. Denormalization-by-reflex is not present.
+- [ ] The choice of data model (relational vs document vs graph vs columnar vs event-sourced) has been justified against the workload's dominant access pattern, not chosen by tribal preference.
+- [ ] Integrity constraints (primary keys, foreign keys, NOT NULL, CHECK constraints, UNIQUE indexes) are present where the theory requires them. Entity integrity and referential integrity are enforced at the database layer, not delegated to the application.
+- [ ] The ER model (entities, relationships, cardinality) was drawn before tables were designed. The schema reflects entity structure, not query-shape.
+- [ ] For each non-relational model in use, the team can name what relational primitive is being traded and what the application is doing in exchange. The choice is principled, not unexamined.
+- [ ] Anti-patterns are recognized: EAV (entity-attribute-value) tables for arbitrary metadata, JSON columns used to avoid schema design, missing foreign keys, denormalization without consistency strategy.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Designing the practical schema for a new persistence layer | `data-modeling` | data-modeling owns the method; this owns the theory |
+| Applying a migration to an existing schema | `schema-evolution` | schema-evolution owns the migration mechanics |
+| Choosing which indexes to maintain | `indexing-strategy` | indexing-strategy owns the index design surface |
+| Discovering business entities without implementation details | `conceptual-modeling` | conceptual-modeling sits above this layer at the business-domain level |
+| Drawing an ER diagram for a specific design | `entity-relationship-modeling` | entity-relationship-modeling owns the ER notation and discovery method |
+| Tuning a slow query against the current schema | `query-optimization` | query-optimization owns runtime performance |
+
+## Key Sources
+
+- Codd, E. F. (1970). ["A Relational Model of Data for Large Shared Data Banks"](https://dl.acm.org/doi/10.1145/362384.362685). *Communications of the ACM*, 13(6). The founding paper of the relational model. Defines relations, the algebra, and the integrity constraints. Foundational reading.
+- Codd, E. F. (1972). "Further Normalization of the Data Base Relational Model." In *Data Base Systems*, Prentice-Hall. Introduces 2NF and 3NF formally.
+- Codd, E. F., & Boyce, R. F. (1974). Introduces what became Boyce-Codd Normal Form (BCNF), addressing edge cases 3NF doesn't cover.
+- Chen, P. P. (1976). ["The Entity-Relationship Model — Toward a Unified View of Data"](https://dl.acm.org/doi/10.1145/320434.320440). *ACM TODS*, 1(1). The founding paper of the ER model.
+- Fagin, R. (1977). ["Multivalued Dependencies and a New Normal Form for Relational Databases"](https://dl.acm.org/doi/10.1145/320557.320571). *ACM TODS*, 2(3). 4NF.
+- Fagin, R. (1979). ["Normal Forms and Relational Database Operators"](https://dl.acm.org/doi/10.1145/582095.582120). *SIGMOD 1979*. 5NF (project-join normal form).
+- Fagin, R. (1981). ["A Normal Form for Relational Databases That Is Based on Domains and Keys"](https://dl.acm.org/doi/10.1145/319587.319592). *ACM TODS*, 6(3). Domain-Key Normal Form.
+- Date, C. J. *An Introduction to Database Systems*, 8th ed. (2003). Pearson. The canonical textbook treatment of the relational model and normalization; widely used in graduate database courses.
+- Garcia-Molina, H., Ullman, J. D., & Widom, J. (2008). *Database Systems: The Complete Book*, 2nd ed. Pearson. Comprehensive textbook covering relational theory, normalization, query processing, and modern systems.
+- Codd, E. F. (1985). ["Is Your DBMS Really Relational?"](https://www.computerworld.com/article/2522473/codd-on-dbms-rules.html). *Computerworld*. The article introducing Codd's 12 rules (later 13).
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 2 (Data Models and Query Languages) is the modern practitioner synthesis of the relational, document, and graph models and their trade-offs.
+- Ambler, S. W., & Sadalage, P. J. (2006). *Refactoring Databases: Evolutionary Database Design*. Addison-Wesley. Bridges normalization theory with the practical concerns of evolving a deployed schema; companion to `schema-evolution`.
+- Hellerstein, J. M., Stonebraker, M., & Hamilton, J. (2007). ["Architecture of a Database System"](https://dsf.berkeley.edu/papers/fntdb07-architecture.pdf). *Foundations and Trends in Databases*, 1(2). Treats the relational model from the systems-architecture perspective.