@olegkoval/agent-skills 1.26.0 → 1.27.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "author": {
     "name": "Oleg Koval"
   },

package/README.md

@@ -11,6 +11,8 @@
 
 Agent-agnostic skill collection for Codex, Claude, Cursor, Grok, and other skill-aware tools.
 
+**Browse the catalog: [skills.olegkoval.com](https://skills.olegkoval.com)**
+
 These skills are opinionated by design. They encode working defaults, preferred tools, and repeatable workflows instead of trying to be neutral snippets. Treat them as starting points with taste: useful out of the box, easy to inspect, and specific enough for an agent to execute consistently.
 
 ## Structure
@@ -19,6 +21,7 @@ These skills are opinionated by design. They encode working defaults, preferred
 - `catalog/` — machine-readable inventory
 - `collections/` — grouped package bundles
 - `scripts/` — sync and validation helpers
+- `site/` — generator for the browsable catalog at [skills.olegkoval.com](https://skills.olegkoval.com) (`npm run build:site`)
 
 ## Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -30,13 +30,15 @@
     ".kiro",
     "scripts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "site"
   ],
   "scripts": {
     "build": "sh ./scripts/build-adapters.sh",
     "test": "sh ./scripts/validate-catalog.sh",
     "semantic-release": "semantic-release",
-    "release:dry-run": "semantic-release --dry-run --no-ci --verify-conditions=@semantic-release/changelog --verify-conditions=@semantic-release/git --verify-conditions=@semantic-release/github"
+    "release:dry-run": "semantic-release --dry-run --no-ci --verify-conditions=@semantic-release/changelog --verify-conditions=@semantic-release/git --verify-conditions=@semantic-release/github",
+    "build:site": "node site/build.mjs"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package/site/assets/paperbag.css

@@ -0,0 +1,707 @@
+/*
+ * paperbag.css — lo-fi / grunge "brown paper bag" styling.
+ * Homage to p2output.com (late-1990s), documented in "Fresh Styles for Web
+ * Designers: Eye Candy from the Underground" for its busy background graphics
+ * and cursor-reactive text highlighting.
+ *
+ * Everything here is self-contained: no webfonts, no images, no network.
+ * The textures are procedural (SVG feTurbulence + gradients).
+ */
+
+/* ---------------------------------------------------------------- tokens */
+:root {
+  --bag: #c3ac84;
+  --bag-lit: #d6c19c;
+  --bag-dim: #a78f68;
+  --bag-deep: #8d7752;
+  --ink: #191410;
+  --ink-soft: #3d3225;
+  --ink-faint: #6b5b43;
+  --stamp: #a8321f;
+  --marker: #f6e14b;
+  --overprint: #1f6f7a;
+
+  --edge: 2px solid var(--ink);
+  --rule: 1px solid rgba(25, 20, 16, 0.28);
+
+  /* Period-correct: Impact was *the* late-90s display face and ships on both
+     macOS and Windows. Condensed grotesques stand in everywhere else. */
+  --display: "Impact", "Haettenschweiler", "Franklin Gothic Bold",
+    "Arial Narrow Bold", "Arial Narrow", "Liberation Sans Narrow",
+    "DejaVu Sans Condensed", sans-serif;
+  --mono: ui-monospace, "SF Mono", "SFMono-Regular", Menlo, Consolas,
+    "DejaVu Sans Mono", monospace;
+
+  --shadow-hard: 5px 5px 0 var(--ink);
+  --shadow-soft: 3px 3px 0 rgba(25, 20, 16, 0.55);
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+/* ------------------------------------------------------------ the paper */
+html {
+  scroll-behavior: smooth;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  color: var(--ink);
+  background-color: var(--bag);
+  font-family: var(--mono);
+  font-size: 15px;
+  line-height: 1.55;
+  overflow-x: hidden;
+}
+
+/*
+ * Three stacked procedural layers make the "busy background": kraft fibre
+ * grain, a print halftone, and the soft blotches of a bag that has been
+ * folded and re-opened. They sit behind content and never intercept input.
+ */
+.grain,
+.halftone,
+.blotch {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 0;
+}
+
+.grain {
+  opacity: 0.42;
+  mix-blend-mode: multiply;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='220' height='220'><filter id='f'><feTurbulence type='fractalNoise' baseFrequency='0.82' numOctaves='4' stitchTiles='stitch'/><feColorMatrix type='saturate' values='0'/></filter><rect width='220' height='220' filter='url(%23f)' opacity='0.55'/></svg>");
+}
+
+.halftone {
+  opacity: 0.2;
+  mix-blend-mode: multiply;
+  background-image: radial-gradient(
+    circle at 1px 1px,
+    rgba(25, 20, 16, 0.9) 0.7px,
+    transparent 1.1px
+  );
+  background-size: 5px 5px;
+}
+
+.blotch {
+  opacity: 0.5;
+  mix-blend-mode: multiply;
+  background-image:
+    radial-gradient(60% 42% at 12% 8%, rgba(120, 96, 60, 0.5), transparent 70%),
+    radial-gradient(48% 38% at 88% 22%, rgba(90, 72, 44, 0.42), transparent 70%),
+    radial-gradient(70% 46% at 30% 92%, rgba(122, 100, 66, 0.4), transparent 72%),
+    repeating-linear-gradient(
+      104deg,
+      transparent 0 78px,
+      rgba(25, 20, 16, 0.05) 78px 79px
+    );
+}
+
+/*
+ * The cursor drags a smudge of ink across the bag. Positioned from JS via
+ * --mx / --my; hidden entirely when the pointer is coarse or motion is
+ * reduced.
+ */
+.smudge {
+  position: fixed;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 400ms ease;
+  mix-blend-mode: multiply;
+  background: radial-gradient(
+    220px 220px at var(--mx, -999px) var(--my, -999px),
+    rgba(25, 20, 16, 0.28),
+    rgba(25, 20, 16, 0.1) 45%,
+    transparent 72%
+  );
+}
+
+body.pointer-fine .smudge {
+  opacity: 1;
+}
+
+/* --------------------------------------------------------------- layout */
+.shell {
+  position: relative;
+  z-index: 2;
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 0 20px 96px;
+}
+
+a {
+  color: var(--ink);
+  text-decoration-thickness: 2px;
+  text-underline-offset: 3px;
+}
+
+a:hover {
+  background: var(--marker);
+  color: var(--ink);
+}
+
+a:focus-visible,
+button:focus-visible,
+input:focus-visible {
+  outline: 3px solid var(--overprint);
+  outline-offset: 2px;
+}
+
+/* -------------------------------------------------------------- masthead */
+.masthead {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 14px;
+  align-items: baseline;
+  justify-content: space-between;
+  padding: 18px 0 14px;
+  border-bottom: var(--edge);
+}
+
+.wordmark {
+  font-family: var(--display);
+  font-size: clamp(22px, 3.4vw, 30px);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  text-decoration: none;
+}
+
+.wordmark:hover {
+  background: none;
+}
+
+.masthead nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  font-size: 12px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+/* ----------------------------------------------------------------- hero */
+.hero {
+  position: relative;
+  padding: 54px 0 40px;
+  border-bottom: var(--edge);
+}
+
+.kicker {
+  font-size: 11px;
+  letter-spacing: 0.34em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  margin: 0 0 18px;
+}
+
+.hero h1 {
+  font-family: var(--display);
+  font-size: clamp(44px, 11vw, 128px);
+  line-height: 0.86;
+  max-width: 12ch;
+  letter-spacing: -0.005em;
+  text-transform: uppercase;
+  margin: 0;
+  /* Cheap offset-litho misregistration. */
+  text-shadow:
+    2px 0 0 rgba(168, 50, 31, 0.4),
+    -2px 1px 0 rgba(31, 111, 122, 0.3);
+}
+
+.hero p.lede {
+  max-width: 62ch;
+  margin: 26px 0 0;
+  font-size: 16px;
+}
+
+.stamp {
+  position: absolute;
+  top: 46px;
+  right: 4px;
+  display: grid;
+  place-items: center;
+  width: 158px;
+  height: 158px;
+  padding: 14px;
+  border: 4px double var(--stamp);
+  border-radius: 50%;
+  background: rgba(195, 172, 132, 0.75);
+  color: var(--stamp);
+  font-family: var(--display);
+  font-size: 21px;
+  line-height: 1.02;
+  letter-spacing: 0.06em;
+  text-align: center;
+  text-transform: uppercase;
+  opacity: 0.82;
+  transform: rotate(-13deg);
+  mix-blend-mode: multiply;
+}
+
+@media (max-width: 720px) {
+  .stamp {
+    position: static;
+    margin: 28px 0 0;
+    transform: rotate(-6deg);
+  }
+}
+
+/* --------------------------------------------------------------- strips */
+.ticker {
+  overflow: hidden;
+  border-bottom: var(--edge);
+  padding: 9px 0;
+  font-size: 11px;
+  letter-spacing: 0.3em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  white-space: nowrap;
+}
+
+.ticker span {
+  display: inline-block;
+  padding-left: 100%;
+  animation: drift 34s linear infinite;
+}
+
+@keyframes drift {
+  to {
+    transform: translateX(-100%);
+  }
+}
+
+.statbar {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  border-bottom: var(--edge);
+}
+
+.statbar div {
+  padding: 16px 14px;
+  border-right: var(--rule);
+}
+
+.statbar div:last-child {
+  border-right: 0;
+}
+
+.statbar b {
+  display: block;
+  font-family: var(--display);
+  font-size: 40px;
+  line-height: 1;
+}
+
+.statbar small {
+  font-size: 10px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+}
+
+/* --------------------------------------------------------------- filter */
+.controls {
+  position: sticky;
+  top: 0;
+  z-index: 5;
+  padding: 16px 0;
+  border-bottom: var(--edge);
+  background: var(--bag);
+  box-shadow: 0 10px 18px -14px rgba(25, 20, 16, 0.8);
+}
+
+.controls label {
+  display: block;
+  font-size: 10px;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  margin-bottom: 6px;
+}
+
+#q {
+  width: 100%;
+  padding: 11px 13px;
+  border: var(--edge);
+  border-radius: 0;
+  background: var(--bag-lit);
+  color: var(--ink);
+  font: inherit;
+}
+
+#q::placeholder {
+  color: var(--ink-faint);
+}
+
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 7px;
+  margin-top: 12px;
+}
+
+.chip {
+  padding: 5px 11px;
+  border: 2px solid var(--ink);
+  background: transparent;
+  color: var(--ink);
+  font: inherit;
+  font-size: 11px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+.chip:hover {
+  background: var(--bag-lit);
+}
+
+.chip[aria-pressed="true"] {
+  background: var(--ink);
+  color: var(--bag-lit);
+}
+
+.count {
+  margin-top: 12px;
+  font-size: 11px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+}
+
+/* ---------------------------------------------------------------- cards */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(310px, 1fr));
+  gap: 20px;
+  padding: 28px 0 0;
+  list-style: none;
+  margin: 0;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 18px;
+  border: var(--edge);
+  background: var(--bag-lit);
+  box-shadow: var(--shadow-soft);
+  transition:
+    transform 120ms ease,
+    box-shadow 120ms ease;
+}
+
+.card:hover,
+.card:focus-within {
+  transform: translate(-2px, -2px);
+  box-shadow: var(--shadow-hard);
+}
+
+.card[hidden] {
+  display: none;
+}
+
+.card .cat {
+  font-size: 10px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--stamp);
+}
+
+.card h2 {
+  margin: 0;
+  font-family: var(--display);
+  font-size: 27px;
+  line-height: 1.02;
+  letter-spacing: 0.01em;
+  text-transform: uppercase;
+}
+
+.card h2 a {
+  text-decoration: none;
+}
+
+.card h2 a:hover {
+  background: none;
+}
+
+/* Full-card click target without nesting interactive elements. */
+.card h2 a::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+
+.card {
+  position: relative;
+}
+
+.card p {
+  margin: 0;
+  font-size: 13.5px;
+  color: var(--ink-soft);
+}
+
+.card .lookup {
+  font-size: 12px;
+  color: var(--overprint);
+  word-break: break-all;
+}
+
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+  margin: auto 0 0;
+  padding: 10px 0 0;
+  border-top: var(--rule);
+  list-style: none;
+}
+
+.tags li {
+  padding: 2px 7px;
+  border: 1px solid rgba(25, 20, 16, 0.45);
+  font-size: 10px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+}
+
+.empty {
+  padding: 48px 0;
+  font-family: var(--display);
+  font-size: 30px;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+}
+
+.empty[hidden] {
+  display: none;
+}
+
+/* -------------------------------------------------------------- sections */
+section.band {
+  padding: 56px 0 0;
+}
+
+section.band > h2 {
+  font-family: var(--display);
+  font-size: clamp(30px, 6vw, 60px);
+  line-height: 0.94;
+  text-transform: uppercase;
+  margin: 0 0 6px;
+}
+
+section.band > .sub {
+  margin: 0 0 26px;
+  font-size: 13px;
+  color: var(--ink-soft);
+}
+
+/* ------------------------------------------------------------ code slabs */
+.slab {
+  border: var(--edge);
+  background: var(--ink);
+  color: var(--bag-lit);
+  margin: 0 0 18px;
+}
+
+.slab header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 12px;
+  border-bottom: 1px solid rgba(214, 193, 156, 0.3);
+  font-size: 10px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+}
+
+.slab pre {
+  margin: 0;
+  padding: 14px 12px;
+  overflow-x: auto;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.7;
+}
+
+.copy {
+  padding: 3px 9px;
+  border: 1px solid var(--bag-lit);
+  background: transparent;
+  color: var(--bag-lit);
+  font: inherit;
+  font-size: 10px;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+.copy:hover {
+  background: var(--bag-lit);
+  color: var(--ink);
+}
+
+.cols {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  gap: 20px;
+}
+
+/* --------------------------------------------------------------- detail */
+.crumb {
+  padding: 22px 0 0;
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+}
+
+.detail-head {
+  padding: 10px 0 34px;
+  border-bottom: var(--edge);
+}
+
+.detail-head h1 {
+  font-family: var(--display);
+  font-size: clamp(38px, 8.5vw, 96px);
+  line-height: 0.88;
+  text-transform: uppercase;
+  margin: 8px 0 0;
+  text-shadow:
+    2px 0 0 rgba(168, 50, 31, 0.36),
+    -2px 1px 0 rgba(31, 111, 122, 0.26);
+}
+
+.detail-head p {
+  max-width: 68ch;
+  margin: 20px 0 0;
+  font-size: 16px;
+}
+
+.meta {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(210px, 1fr));
+  gap: 0;
+  border-bottom: var(--edge);
+}
+
+.meta div {
+  padding: 16px 14px 16px 0;
+}
+
+.meta dt {
+  font-size: 10px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  margin-bottom: 6px;
+}
+
+.meta dd {
+  margin: 0;
+  font-size: 13px;
+  word-break: normal;
+  overflow-wrap: anywhere;
+}
+
+.pager {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 16px;
+  margin-top: 56px;
+  padding-top: 20px;
+  border-top: var(--edge);
+  font-size: 12px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+/* --------------------------------------------------------------- footer */
+footer.colophon {
+  margin-top: 72px;
+  padding-top: 20px;
+  border-top: var(--edge);
+  font-size: 11px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  justify-content: space-between;
+}
+
+/* ----------------------------------------------------- cursor highlight */
+/*
+ * The p2output signature: glyphs light up as the pointer sweeps over them.
+ * JS sets --h (0..1) per character; everything visual happens here so the
+ * effect degrades to nothing when JS is off.
+ */
+.reactive .w {
+  display: inline-block;
+  white-space: nowrap;
+}
+
+.reactive .g {
+  display: inline-block;
+  color: color-mix(in srgb, var(--stamp) calc(var(--h, 0) * 100%), currentColor);
+  transform: translateY(calc(var(--h, 0) * -5px)) rotate(calc(var(--h, 0) * -3deg));
+  background: linear-gradient(
+    var(--marker),
+    var(--marker)
+  ) no-repeat;
+  background-size: 100% calc(var(--h, 0) * 100%);
+  background-position: 0 100%;
+  will-change: transform;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+
+  .ticker span {
+    animation: none;
+    padding-left: 0;
+  }
+
+  .reactive .g {
+    transform: none;
+  }
+
+  .smudge {
+    display: none;
+  }
+
+  .card {
+    transition: none;
+  }
+}
+
+@media print {
+  .grain,
+  .halftone,
+  .blotch,
+  .smudge,
+  .controls {
+    display: none;
+  }
+
+  body {
+    background: #fff;
+  }
+}

package/site/assets/paperbag.js

@@ -0,0 +1,218 @@
+/*
+ * paperbag.js — progressive enhancement only. With JS off the page is a
+ * complete, readable, fully linked catalog; everything below just adds the
+ * p2output-era cursor theatrics and client-side filtering.
+ */
+(() => {
+  "use strict";
+
+  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+  const finePointer = window.matchMedia("(hover: hover) and (pointer: fine)");
+
+  /* ------------------------------------------------ cursor-lit lettering */
+
+  // Radius of the pointer's influence, in CSS pixels.
+  const RADIUS = 130;
+
+  const glyphs = [];
+
+  const splitIntoGlyphs = (el) => {
+    const text = el.textContent;
+    // Keep the accessible name intact; the per-character spans are decorative.
+    el.setAttribute("aria-label", text.trim());
+    const frag = document.createDocumentFragment();
+    // Characters are inline-block, which would otherwise let the browser break
+    // a line mid-word. Wrapping each word keeps normal wrapping behaviour.
+    for (const word of text.split(/(\s+)/)) {
+      if (word === "") continue;
+      if (/^\s+$/.test(word)) {
+        frag.appendChild(document.createTextNode(word));
+        continue;
+      }
+      const wrap = document.createElement("span");
+      wrap.className = "w";
+      wrap.setAttribute("aria-hidden", "true");
+      for (const ch of word) {
+        const span = document.createElement("span");
+        span.className = "g";
+        span.textContent = ch;
+        wrap.appendChild(span);
+      }
+      frag.appendChild(wrap);
+    }
+    el.textContent = "";
+    el.appendChild(frag);
+    el.classList.add("reactive");
+  };
+
+  const measure = () => {
+    for (const glyph of glyphs) {
+      const r = glyph.el.getBoundingClientRect();
+      // Page coordinates so scrolling never invalidates the cache.
+      glyph.x = r.left + r.width / 2 + window.scrollX;
+      glyph.y = r.top + r.height / 2 + window.scrollY;
+      glyph.visible = r.width > 0;
+    }
+  };
+
+  const initGlyphs = () => {
+    if (!finePointer.matches) return;
+    document.querySelectorAll("[data-reactive]").forEach((el) => {
+      splitIntoGlyphs(el);
+      el.querySelectorAll(".g").forEach((span) => {
+        glyphs.push({ el: span, x: 0, y: 0, lit: 0, visible: true });
+      });
+    });
+    if (glyphs.length) measure();
+  };
+
+  let pointerX = -9999;
+  let pointerY = -9999;
+  let queued = false;
+
+  const paint = () => {
+    queued = false;
+    const top = window.scrollY - RADIUS;
+    const bottom = window.scrollY + window.innerHeight + RADIUS;
+
+    for (const glyph of glyphs) {
+      let next = 0;
+      if (glyph.visible && glyph.y > top && glyph.y < bottom) {
+        const dx = glyph.x - pointerX;
+        const dy = glyph.y - pointerY;
+        const d = Math.hypot(dx, dy);
+        if (d < RADIUS) {
+          // Ease-out so the falloff reads as a soft brush, not a hard disc.
+          const t = 1 - d / RADIUS;
+          next = Math.round(t * t * 100) / 100;
+        }
+      }
+      if (next !== glyph.lit) {
+        glyph.lit = next;
+        if (next === 0) glyph.el.style.removeProperty("--h");
+        else glyph.el.style.setProperty("--h", String(next));
+      }
+    }
+  };
+
+  const onPointerMove = (event) => {
+    pointerX = event.clientX + window.scrollX;
+    pointerY = event.clientY + window.scrollY;
+    document.body.style.setProperty("--mx", `${event.clientX}px`);
+    document.body.style.setProperty("--my", `${event.clientY}px`);
+    if (!queued && glyphs.length) {
+      queued = true;
+      requestAnimationFrame(paint);
+    }
+  };
+
+  if (finePointer.matches && !reduceMotion.matches) {
+    document.body.classList.add("pointer-fine");
+    initGlyphs();
+    window.addEventListener("pointermove", onPointerMove, { passive: true });
+    window.addEventListener("resize", measure);
+  }
+
+  /* -------------------------------------------------------- catalog filter */
+
+  const q = document.getElementById("q");
+  const grid = document.getElementById("grid");
+
+  if (q && grid) {
+    const cards = Array.from(grid.querySelectorAll(".card"));
+    const chips = Array.from(document.querySelectorAll(".chip"));
+    const countEl = document.getElementById("count");
+    const emptyEl = document.getElementById("empty");
+    const active = { category: null, adapter: null };
+
+    const apply = () => {
+      const needle = q.value.trim().toLowerCase();
+      let shown = 0;
+
+      for (const card of cards) {
+        const matchesText = !needle || card.dataset.search.includes(needle);
+        const matchesCat =
+          !active.category || card.dataset.category === active.category;
+        const matchesAdapter =
+          !active.adapter ||
+          card.dataset.adapters.split(" ").includes(active.adapter);
+        const visible = matchesText && matchesCat && matchesAdapter;
+        card.hidden = !visible;
+        if (visible) shown += 1;
+      }
+
+      countEl.textContent =
+        shown === cards.length
+          ? `${cards.length} skills`
+          : `${shown} of ${cards.length} skills`;
+      emptyEl.hidden = shown !== 0;
+
+      // Cards moved, so the glyph rect cache is stale.
+      if (glyphs.length) requestAnimationFrame(measure);
+    };
+
+    q.addEventListener("input", apply);
+
+    for (const chip of chips) {
+      chip.addEventListener("click", () => {
+        const kind = chip.dataset.kind;
+        const value = chip.dataset.value;
+        const isOn = active[kind] === value;
+        active[kind] = isOn ? null : value;
+        for (const other of chips) {
+          if (other.dataset.kind !== kind) continue;
+          other.setAttribute(
+            "aria-pressed",
+            String(!isOn && other.dataset.value === value),
+          );
+        }
+        apply();
+      });
+    }
+
+    // Deep links like /?q=release or /?category=marketing.
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("q")) q.value = params.get("q");
+    for (const kind of ["category", "adapter"]) {
+      const value = params.get(kind);
+      if (!value) continue;
+      const chip = chips.find(
+        (c) => c.dataset.kind === kind && c.dataset.value === value,
+      );
+      if (chip) {
+        active[kind] = value;
+        chip.setAttribute("aria-pressed", "true");
+      }
+    }
+    apply();
+  }
+
+  /* ------------------------------------------------------- copy buttons */
+
+  document.querySelectorAll(".copy").forEach((button) => {
+    const idle = button.textContent;
+    let resetTimer = 0;
+
+    button.addEventListener("click", async () => {
+      const pre = button.closest(".slab").querySelector("pre");
+      try {
+        await navigator.clipboard.writeText(pre.textContent.trim());
+        button.textContent = "copied";
+        // A second click before the first timer fires would otherwise capture
+        // "copied" as the label to restore, wedging the button in that state.
+        clearTimeout(resetTimer);
+        resetTimer = setTimeout(() => {
+          button.textContent = idle;
+        }, 1400);
+      } catch {
+        // Clipboard blocked (insecure context, denied permission): select the
+        // text so the reader can copy it by hand.
+        const range = document.createRange();
+        range.selectNodeContents(pre);
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+      }
+    });
+  });
+})();

package/site/build.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/*
+ * Static site generator for the agent-skills catalog.
+ *
+ * Reads the machine-readable catalog (the same file `npm test` validates) and
+ * emits a dependency-free static site into `_site/` for GitHub Pages.
+ * There is no templating library on purpose: the catalog is small, the output
+ * must stay auditable, and CI should not need a lockfile refresh to publish.
+ */
+
+import { mkdir, readFile, readdir, copyFile, writeFile, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+const out = join(root, "_site");
+
+const SITE_URL = "https://skills.olegkoval.com";
+const REPO = "https://github.com/oleg-koval/agent-skills";
+const CNAME = "skills.olegkoval.com";
+
+/* ------------------------------------------------------------- utilities */
+
+const esc = (value) =>
+  String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+const titleCase = (slug) =>
+  slug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+/** Pulls the YAML-ish frontmatter block off a SKILL.md without a YAML dep. */
+const readFrontmatter = async (path) => {
+  if (!existsSync(path)) return {};
+  const raw = await readFile(path, "utf8");
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    fields[kv[1]] = kv[2].replace(/^["']|["']$/g, "").trim();
+  }
+  return fields;
+};
+
+/** Counts the extra reference material shipped alongside a skill. */
+const countSupportFiles = async (dir) => {
+  let files = 0;
+  const walk = async (current) => {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "adapters") continue; // wrappers, not content
+      if (entry.isDirectory()) await walk(join(current, entry.name));
+      else if (entry.name !== "SKILL.md") files += 1;
+    }
+  };
+  if (existsSync(dir)) await walk(dir);
+  return files;
+};
+
+/* ----------------------------------------------------------------- chrome */
+
+const layout = ({ title, description, canonical, body, ogTitle }) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<meta name="description" content="${esc(description)}">
+<link rel="canonical" href="${esc(canonical)}">
+<meta property="og:type" content="website">
+<meta property="og:site_name" content="agent skills">
+<meta property="og:title" content="${esc(ogTitle || title)}">
+<meta property="og:description" content="${esc(description)}">
+<meta property="og:url" content="${esc(canonical)}">
+<meta name="twitter:card" content="summary">
+<meta name="theme-color" content="#c3ac84">
+<link rel="icon" href="/assets/favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/assets/paperbag.css">
+</head>
+<body>
+<div class="grain" aria-hidden="true"></div>
+<div class="halftone" aria-hidden="true"></div>
+<div class="blotch" aria-hidden="true"></div>
+<div class="smudge" aria-hidden="true"></div>
+<div class="shell">
+<header class="masthead">
+  <a class="wordmark" href="/">agent&nbsp;skills</a>
+  <nav aria-label="Primary">
+    <a href="/#catalog">Catalog</a>
+    <a href="/#install">Install</a>
+    <a href="/#about">About</a>
+    <a href="${REPO}">GitHub</a>
+  </nav>
+</header>
+${body}
+<footer class="colophon">
+  <span>MIT licensed &middot; <a href="${REPO}">oleg-koval/agent-skills</a></span>
+  <span>Lo-fi homage to p2output.com, c. 1998</span>
+</footer>
+</div>
+<script src="/assets/paperbag.js" defer></script>
+</body>
+</html>
+`;
+
+const slab = (label, code) => `<div class="slab">
+  <header><span>${esc(label)}</span><button class="copy" type="button">Copy</button></header>
+  <pre>${esc(code)}</pre>
+</div>`;
+
+/* ------------------------------------------------------------ index page */
+
+const installSection = (sample) => `<section class="band" id="install">
+  <h2 data-reactive>Get them</h2>
+  <p class="sub">Pick your agent. The canonical package is the same either way; only the wrapper changes.</p>
+  <div class="cols">
+    <div>
+      <h3>Claude Code</h3>
+      ${slab("marketplace", "/plugin marketplace add oleg-koval/agent-skills\n/plugin install olko-agent-skills@olko-agent-skills")}
+    </div>
+    <div>
+      <h3>Codex</h3>
+      ${slab("symlink install", "git clone https://github.com/oleg-koval/agent-skills.git\ncd agent-skills\n./scripts/install-codex-symlinks.sh")}
+    </div>
+    <div>
+      <h3>Grok</h3>
+      ${slab("marketplace", "grok plugin marketplace add oleg-koval/agent-skills")}
+    </div>
+    <div>
+      <h3>Then just ask</h3>
+      ${slab("any session", `Use the ${sample} skill.`)}
+    </div>
+  </div>
+  <p class="sub">Cursor, Copilot, Windsurf and Kiro consume the generated wrappers under each package's <code>adapters/</code> directory &mdash; see the <a href="${REPO}#quick-start">repository README</a>.</p>
+</section>`;
+
+const card = (pkg) => {
+  const search = [pkg.name, pkg.description, pkg.category, ...(pkg.tags || [])]
+    .join(" ")
+    .toLowerCase();
+  return `<li class="card"
+    data-category="${esc(pkg.category)}"
+    data-adapters="${esc((pkg.adapters || []).join(" "))}"
+    data-search="${esc(search)}">
+    <span class="cat">${esc(pkg.category.replace(/-/g, " "))}</span>
+    <h2><a href="/skills/${esc(pkg.name)}/" data-reactive>${esc(titleCase(pkg.name))}</a></h2>
+    <p>${esc(pkg.description)}</p>
+    <span class="lookup">${esc(pkg.lookupName)}</span>
+    <ul class="tags">${(pkg.tags || [])
+      .slice(0, 6)
+      .map((t) => `<li>${esc(t)}</li>`)
+      .join("")}</ul>
+  </li>`;
+};
+
+const indexPage = ({ packages, categories, adapters, collections }) => {
+  const body = `<section class="hero">
+  <p class="kicker">Agent-agnostic skill catalog</p>
+  <h1 data-reactive>Skills in a paper bag</h1>
+  <div class="stamp" aria-hidden="true">Opinionated<br>by design</div>
+  <p class="lede">${packages.length} canonical skills for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, Pi and Hermes. They encode working defaults and repeatable workflows instead of neutral snippets &mdash; starting points with taste, easy to inspect, specific enough for an agent to execute the same way twice.</p>
+</section>
+
+<div class="ticker" aria-hidden="true"><span>${packages
+    .map((p) => p.lookupName)
+    .join(" &nbsp;&bull;&nbsp; ")}</span></div>
+
+<div class="statbar">
+  <div><b>${packages.length}</b><small>Skills</small></div>
+  <div><b>${adapters.length}</b><small>Agent adapters</small></div>
+  <div><b>${categories.length}</b><small>Categories</small></div>
+  <div><b>${collections.length}</b><small>Collections</small></div>
+</div>
+
+<section class="band" id="catalog">
+  <div class="controls">
+    <label for="q">Search the catalog</label>
+    <input id="q" type="search" autocomplete="off" placeholder="release, pull requests, obsidian, watch face&hellip;">
+    <div class="chips" role="group" aria-label="Filter by category">
+      ${categories
+        .map(
+          (c) =>
+            `<button class="chip" type="button" aria-pressed="false" data-kind="category" data-value="${esc(c.name)}">${esc(c.name.replace(/-/g, " "))} <span aria-hidden="true">${c.count}</span></button>`,
+        )
+        .join("\n      ")}
+    </div>
+    <div class="chips" role="group" aria-label="Filter by agent">
+      ${adapters
+        .map(
+          (a) =>
+            `<button class="chip" type="button" aria-pressed="false" data-kind="adapter" data-value="${esc(a.name)}">${esc(a.name)} <span aria-hidden="true">${a.count}</span></button>`,
+        )
+        .join("\n      ")}
+    </div>
+    <p class="count" id="count" role="status">${packages.length} skills</p>
+  </div>
+  <ul class="grid" id="grid">
+    ${packages.map(card).join("\n    ")}
+  </ul>
+  <p class="empty" id="empty" hidden>Nothing in the bag matches that.</p>
+</section>
+
+${installSection(packages[0].lookupName)}
+
+<section class="band" id="about">
+  <h2 data-reactive>About</h2>
+  <p class="sub">One canonical package per workflow. Agent-specific wrappers live in <code>adapters/</code> rather than duplicating the skill. Catalogs stay neutral and machine-readable, so this page is generated from <code>catalog/skills.json</code> and can never drift from what actually ships.</p>
+  <p class="sub">The styling is a deliberate homage to <strong>p2output.com</strong>, a late-1990s experimental web design and motion graphics project written up in <em>Fresh Styles for Web Designers: Eye Candy from the Underground</em> for its lo-fi paper-bag surface, busy background graphics, and text that lit up as your cursor swept across it. The original domain has been dark for years. Move your pointer over the headlines.</p>
+</section>`;
+
+  return layout({
+    title: "agent skills — an agent-agnostic skill catalog",
+    ogTitle: "agent skills",
+    description: `${packages.length} opinionated, agent-agnostic skills for Codex, Claude, Cursor, Grok, Copilot, Windsurf and Kiro.`,
+    canonical: `${SITE_URL}/`,
+    body,
+  });
+};
+
+/* ----------------------------------------------------------- detail page */
+
+const detailPage = (pkg, prev, next) => {
+  const label = titleCase(pkg.name);
+  const body = `<p class="crumb"><a href="/">Catalog</a> / ${esc(pkg.category.replace(/-/g, " "))}</p>
+<div class="detail-head">
+  <span class="cat">${esc(pkg.lookupName)}</span>
+  <h1 data-reactive>${esc(label)}</h1>
+  <p>${esc(pkg.longDescription || pkg.description)}</p>
+</div>
+
+<dl class="meta">
+  <div><dt>Lookup name</dt><dd>${esc(pkg.lookupName)}</dd></div>
+  <div><dt>Category</dt><dd>${esc(pkg.category.replace(/-/g, " "))}</dd></div>
+  <div><dt>Agents</dt><dd>${esc((pkg.adapters || []).join(", "))}</dd></div>
+  <div><dt>Bundled references</dt><dd>${pkg.supportFiles} file${pkg.supportFiles === 1 ? "" : "s"}</dd></div>
+</dl>
+
+<section class="band">
+  <h2 data-reactive>Use it</h2>
+  <p class="sub">Once the catalog is installed, name the skill in a session.</p>
+  ${slab("any agent", `Use the ${pkg.lookupName} skill.`)}
+  ${slab("claude code", `/plugin marketplace add oleg-koval/agent-skills\n/plugin install olko-agent-skills@olko-agent-skills`)}
+  <p class="sub"><a href="${REPO}/blob/main/${esc(pkg.path)}/SKILL.md">Read the full SKILL.md on GitHub</a> &middot; <a href="${REPO}/tree/main/${esc(pkg.path)}">Browse the package</a></p>
+</section>
+
+${
+  (pkg.tags || []).length
+    ? `<section class="band">
+  <h2 data-reactive>Tags</h2>
+  <ul class="tags">${pkg.tags.map((t) => `<li><a href="/?q=${encodeURIComponent(t)}">${esc(t)}</a></li>`).join("")}</ul>
+</section>`
+    : ""
+}
+
+<nav class="pager" aria-label="Catalog">
+  <a href="/skills/${esc(prev.name)}/">&larr; ${esc(titleCase(prev.name))}</a>
+  <a href="/skills/${esc(next.name)}/">${esc(titleCase(next.name))} &rarr;</a>
+</nav>`;
+
+  return layout({
+    title: `${label} — agent skills`,
+    description: pkg.description,
+    canonical: `${SITE_URL}/skills/${pkg.name}/`,
+    body,
+  });
+};
+
+/* ------------------------------------------------------------------ main */
+
+const favicon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+<rect width="32" height="32" fill="#c3ac84"/>
+<path d="M7 9h18v16H7z" fill="none" stroke="#191410" stroke-width="2.5"/>
+<path d="M7 9l4-4h10l4 4" fill="none" stroke="#191410" stroke-width="2.5"/>
+<circle cx="16" cy="18" r="3.4" fill="#a8321f"/>
+</svg>
+`;
+
+const main = async () => {
+  const catalog = JSON.parse(
+    await readFile(join(root, "catalog", "skills.json"), "utf8"),
+  );
+
+  const collectionFiles = await readdir(join(root, "collections"));
+  const collections = collectionFiles.filter((f) => f.endsWith(".json"));
+
+  const packages = [...catalog.packages].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+
+  for (const pkg of packages) {
+    const dir = join(root, pkg.path);
+    const front = await readFrontmatter(join(dir, "SKILL.md"));
+    // The catalog description is the source of truth; frontmatter only fills
+    // the longer detail-page blurb when it is genuinely richer.
+    if (front.description && front.description.length > pkg.description.length) {
+      pkg.longDescription = front.description;
+    }
+    pkg.supportFiles = await countSupportFiles(dir);
+  }
+
+  const tally = (key) => {
+    const counts = new Map();
+    for (const pkg of packages) {
+      const values = Array.isArray(pkg[key]) ? pkg[key] : [pkg[key]];
+      for (const value of values) counts.set(value, (counts.get(value) || 0) + 1);
+    }
+    return [...counts]
+      .map(([name, count]) => ({ name, count }))
+      .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+  };
+
+  const categories = tally("category");
+  const adapters = tally("adapters");
+
+  await rm(out, { recursive: true, force: true });
+  await mkdir(join(out, "assets"), { recursive: true });
+
+  await copyFile(
+    join(here, "assets", "paperbag.css"),
+    join(out, "assets", "paperbag.css"),
+  );
+  await copyFile(
+    join(here, "assets", "paperbag.js"),
+    join(out, "assets", "paperbag.js"),
+  );
+  await writeFile(join(out, "assets", "favicon.svg"), favicon);
+
+  await writeFile(
+    join(out, "index.html"),
+    indexPage({ packages, categories, adapters, collections }),
+  );
+
+  for (const [i, pkg] of packages.entries()) {
+    const prev = packages[(i - 1 + packages.length) % packages.length];
+    const next = packages[(i + 1) % packages.length];
+    const dir = join(out, "skills", pkg.name);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "index.html"), detailPage(pkg, prev, next));
+  }
+
+  await writeFile(
+    join(out, "404.html"),
+    layout({
+      title: "Not in the bag — agent skills",
+      description: "That page does not exist.",
+      canonical: `${SITE_URL}/404.html`,
+      body: `<section class="hero">
+  <p class="kicker">404</p>
+  <h1 data-reactive>Not in the bag</h1>
+  <p class="lede">Whatever you reached for is not here. <a href="/">Go back to the catalog</a>.</p>
+</section>`,
+    }),
+  );
+
+  const urls = [`${SITE_URL}/`, ...packages.map((p) => `${SITE_URL}/skills/${p.name}/`)];
+  await writeFile(
+    join(out, "sitemap.xml"),
+    `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls
+      .map((u) => `  <url><loc>${u}</loc></url>`)
+      .join("\n")}\n</urlset>\n`,
+  );
+  await writeFile(
+    join(out, "robots.txt"),
+    `User-agent: *\nAllow: /\nSitemap: ${SITE_URL}/sitemap.xml\n`,
+  );
+  await writeFile(join(out, "CNAME"), `${CNAME}\n`);
+  await writeFile(join(out, ".nojekyll"), "");
+
+  console.log(
+    `site: ${packages.length} skills, ${categories.length} categories, ${adapters.length} adapters -> _site/`,
+  );
+};
+
+await main();