@nerdev/skillset 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nalin Dalal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# skillset
+
+69 agent skills in 10 categories (ui, backend, devops, architecture, engineering, quality, business, nerdev, ai-agent, workflow) with a CLI to install them into any harness (Claude Code, OpenCode, Cursor, Codex, Gemini) and a CI/CD pipeline that syncs a handful from upstream repos.
+
+> **Owned, not copied.** Synced skills are a base, not the final word. Any skill
+> you care about gets a `curations/<skill>/` layer that survives every upstream
+> re-sync: your taste, your whys, never clobbered. See [Ownership model](#ownership-model).
+
+## What's inside
+
+### Categories
+
+```
+skills/
+├── ui/               28 skills  Components, animations, design systems
+├── backend/           5 skills  API, auth, database, realtime, security
+├── devops/            4 skills  CI/CD, deployment, testing, performance
+├── architecture/      4 skills  Planning, onboarding, research
+├── engineering/       4 skills  TDD, code review, verification, standards
+├── quality/           2 skills  Writing quality, anti-slop
+├── business/          8 skills  Freelancing, startup, career, marketing
+├── nerdev/            3 skills  Nerdev skill family
+├── ai-agent/          2 skills  Agent docs, context management
+└── workflow/          7 skills  Ship, context, health, learn
+```
+
+### Synced from upstream (5 skills, auto-updated nightly)
+
+| Upstream                                                                                  | Skills                                                                                    |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (59k★)                        | `ui/impeccable`: 23 design commands, 59 deterministic detector rules, live browser iteration |
+| [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) (77k★)                    | `quality/output-skill`                                                                    |
+| [emilkowalski/skills](https://github.com/emilkowalski/skills) (30k★)                      | `ui/ask-sonner`, `ui/pick-ui-library`, `ui/prototype`                                     |
+| [cursor/plugins pstack](https://github.com/cursor/plugins/tree/main/pstack/skills/unslop) | `quality/unslop`: cuts AI tells from any writing                                          |
+
+These four repos are pinned in `vendor.json`. `.github/workflows/sync.yml` checks them nightly and opens a PR when they move. You never hand-copy a file from them.
+
+### Everything else (64 skills, owned outright)
+
+Not synced from anywhere. Written for this repo, live only here, edited directly in `skills/<category>/<name>/`.
+
+**ui/**: `house-style` (the law: how UI, code, and docs should look and feel), `ui-engineering` (loads the rest of the UI family for a full build), `ui-core` (whole UI job: direction → system → build → verify), `typography-picker` (font pairing, type scale, text motion), `motion` (whole motion job: name → decide → build → review), `imagegen` (design-reference image generation), `frontend-craftsmanship` (product design thinking, visual systems, interaction design, reverse engineering, learning roadmap), `product-site` (product site architecture: which pages exist, what each page accomplishes, page relationships, legal/trust/support/operational pages), `product-messaging` (landing page content hierarchy, hero/value prop/section copy, what each section should actually communicate).
+
+**Pattern → library pairs**: ask "how do I build X" and you get the pattern skill; it names the library and hands off to the library-specific guide:
+
+| Pattern skill      | Hands off to                                        |
+| ------------------ | --------------------------------------------------- |
+| `ui/ask-modal`     | `ui/ask-base-ui`                                    |
+| `ui/ask-toast`     | `ui/ask-sonner`                                     |
+| `ui/ask-animation` | `ui/ask-motion` (or `ui/ask-gsap` for showcase-tier) |
+| `ui/ask-form`      | `ui/ask-rhf`                                        |
+| `ui/ask-table`     | `ui/ask-tanstack-table`                             |
+| `ui/ask-command-menu` | `ui/ask-cmdk`                                    |
+| `ui/ask-virtual-list` | `ui/ask-virtuoso`                                 |
+| `ui/ask-drawer`    | `ui/ask-vaul`                                       |
+
+**backend/**: `api-design`, `auth`, `database`, `realtime`, `security`.
+
+**devops/**: `deployments`, `git-ci`, `performance`, `testing`.
+
+**architecture/**: `blueprint` (multi-PR construction plans), `code-tour` (guided codebase walkthroughs), `search-first` (research-before-coding), `progress-guard` (catches motion-not-progress on side work).
+
+**engineering/**: `tdd-workflow` (RED/GREEN/REFACTOR cycle), `code-review` (confidence-weighted, noise-free review), `verification-loop` (6-phase pre-PR gate), `coding-standards` (cross-project conventions).
+
+**quality/**: `unslop` (cuts AI tells), `output-skill` (elite writing quality).
+
+**nerdev/**: `nerdev-monorepo` (Turborepo + Bun structure, CI/CD, deploy), `nerdev-docs` (ADRs, design docs, runbooks), `nerdev-abstraction` (interface-first, registry-based plug-and-play).
+
+**ai-agent/**: `agent-docs-writer` (README/AGENTS.md), `ultra-context-engine` (token-efficiency layer).
+
+**business/**: `freelancing`, `startup-founder`, `resume-revamp-jake-ats`, `pricing` (SaaS pricing strategy, value metrics, tiers), `customer-research` (interviews, surveys, persona generation, JTBD), `copywriting` (landing page copy, headlines, CTAs), `launch` (ORB framework, five-phase approach, Product Hunt), `marketing-psychology` (mental models, persuasion, buyer behavior), `brag` (turn any project into a launch video with Hyperframes).
+
+**workflow/**: `office-hours` (YC-style product interrogation), `ship` (detect base, test, review, commit, push, PR), `careful` (destructive command guardrails), `context-save` (save working state to disk), `context-restore` (restore from saved context), `health` (code quality dashboard with composite scoring), `learn` (project learnings manager).
+
+## Install
+
+**Via GitHub (no npm account/token needed, always works):**
+
+```bash
+npx github:NalinDalal/skillset install    # install all skills, all harnesses (global)
+bunx github:NalinDalal/skillset install   # bun equivalent
+```
+
+**From npm (if/when published as `@nalindalal/skillset`):**
+
+```bash
+npx @nalindalal/skillset install
+bunx @nalindalal/skillset install
+```
+
+**From the repo directly:**
+
+```bash
+git clone https://github.com/NalinDalal/skillset.git
+cd skillset
+npm link                        # or bun link, then `skillset` is on your PATH
+```
+
+## Quick start (local project)
+
+```bash
+# 1. Install skills into your project
+cd my-project
+skillset install --scope project --target opencode   # or claude, cursor, etc.
+
+# 2. Open your agent in that directory
+opencode    # or claude, cursor, etc.
+
+# 3. Say what you want, the matching skill loads automatically
+> add a toast notification to this page
+# → ask-toast fires → hands off to ask-sonner → you get working code
+
+# Or name a skill explicitly if it doesn't auto-load
+> use the motion skill to review these animations
+```
+
+That's it. Skills are just markdown files your agent reads, no build step, no runtime. Install them, then talk to your agent naturally.
+
+## Usage
+
+```bash
+skillset list                              # see all 66 skills + descriptions
+skillset install                           # everything → ~/.claude, ~/.config/opencode, ~/.cursor, ~/.agents, ~/.gemini
+skillset install --skill ui/motion         # just one skill (category/name)
+skillset install --target claude,opencode  # only specific harnesses
+skillset install --scope project           # into ./project/.claude/skills etc. instead of global
+skillset install --dry-run                 # preview without touching anything
+skillset install --undo                    # remove everything this CLI installed
+skillset sync                              # pull latest from the 4 upstream repos (local)
+```
+
+Restart or reload your agent after installing:
+- **OpenCode**: just start a new session (`opencode`)
+- **Claude Code**: `/clear` or start a new session
+- **Cursor**: reload window (`Cmd+Shift+P` → "Reload Window")
+- **Codex**: start a new session
+
+## What to say for what you want
+
+Skills fire from their description, not from a command you type. Say what you want in plain words; the closest-matching skill loads. If it doesn't auto-load, name it: _"use the motion skill to review these animations."_
+
+**UI / frontend:**
+
+| You say                                                  | Skill fires                                                        |
+| -------------------------------------------------------- | ------------------------------------------------------------------ |
+| "build the FE / build the frontend / design the UI"      | `ui/ui-engineering` (loads the rest of the UI family)              |
+| "make this screen not look templated"                    | `ui/ui-core`                                                       |
+| "what's it called when a popover bounces open"           | `ui/motion`                                                        |
+| "pick a design direction / theme"                        | `ui/ui-core`, `ui/house-style`                                     |
+| "pick a font / typeface / type scale / text motion"      | `ui/typography-picker`                                             |
+| "generate a web/mobile design reference"                 | `ui/imagegen`                                                      |
+| "add a modal / dialog / sheet / popover / menu / select" | `ui/ask-modal` → `ui/ask-base-ui`                                  |
+| "add a toast / notification / loading state"             | `ui/ask-toast` → `ui/ask-sonner`                                   |
+| "add animations / transitions / motion"                  | `ui/ask-animation` → `ui/ask-motion` (or `ui/ask-gsap` for showcase) |
+| "build a form with validation"                           | `ui/ask-form` → `ui/ask-rhf`                                       |
+| "build a data table / sorting / filtering"               | `ui/ask-table` → `ui/ask-tanstack-table`                           |
+| "add a command palette / ⌘K"                             | `ui/ask-command-menu` → `ui/ask-cmdk`                              |
+| "build a virtual list / infinite scroll / feed / chat"   | `ui/ask-virtual-list` → `ui/ask-virtuoso`                          |
+| "add a mobile drawer / bottom sheet"                     | `ui/ask-drawer` → `ui/ask-vaul`                                    |
+| "what pages does my product site need"                   | `ui/product-site` (page architecture, funnel, legal/support/auth pages) |
+| "write my landing page / hero copy / value prop"         | `ui/product-messaging` (what to say, section hierarchy, actual copy) |
+
+**Backend / dev workflow:**
+
+| You say                                                               | Skill fires              |
+| --------------------------------------------------------------------- | ------------------------ |
+| "design/review this REST or tRPC or GraphQL API"                      | `backend/api-design`     |
+| "add auth / OAuth / JWT / MFA / passwordless"                         | `backend/auth`           |
+| "design the Prisma schema / optimize this query"                      | `backend/database`       |
+| "set up CI / commit conventions / release automation"                 | `devops/git-ci`          |
+| "reduce bundle size / fix Core Web Vitals / find a memory leak"       | `devops/performance`     |
+| "build live cursors / chat / multiplayer / presence"                  | `backend/realtime`       |
+| "harden security / add CSP / rate limiting / review security posture" | `backend/security`       |
+| "write tests / set up Vitest or Playwright / fix flaky tests"         | `devops/testing`         |
+
+**Architecture / planning:**
+
+| You say                                                               | Skill fires                      |
+| --------------------------------------------------------------------- | -------------------------------- |
+| "plan a complex feature / break work into PRs"                        | `architecture/blueprint`         |
+| "create a codebase walkthrough for onboarding"                        | `architecture/code-tour`         |
+| "research existing solutions before building"                         | `architecture/search-first`      |
+
+**Engineering / quality:**
+
+| You say                                                               | Skill fires                      |
+| --------------------------------------------------------------------- | -------------------------------- |
+| "write tests first / use TDD"                                         | `engineering/tdd-workflow`       |
+| "review this code / check for issues"                                 | `engineering/code-review`        |
+| "verify before PR / run all checks"                                   | `engineering/verification-loop`  |
+| "enforce coding standards / clean code"                               | `engineering/coding-standards`   |
+
+**Repo & process:**
+
+| You say                                           | Skill fires                     |
+| ------------------------------------------------- | ------------------------------- |
+| "help me deploy this repo to a VPS/EC2"           | `devops/deployments`            |
+| "write an AGENTS.md / audit this README"          | `ai-agent/agent-docs-writer`    |
+| "clean up this sloppy AI-sounding text"           | `quality/unslop`                |
+| "scaffold a new Turborepo + Bun monorepo"         | `nerdev/nerdev-monorepo`        |
+| "add a plug-and-play tool system with a registry" | `nerdev/nerdev-abstraction`     |
+| "create an ADR / design doc / incident template"  | `nerdev/nerdev-docs`            |
+
+**Business:**
+
+| You say                            | Skill fires                     |
+| ---------------------------------- | ------------------------------- |
+| "I want to start freelancing"      | `business/freelancing`          |
+| "should I build this startup idea" | `business/startup-founder`      |
+| "revamp my resume for this JD"     | `business/resume-revamp-jake-ats` |
+| "help me price this SaaS"          | `business/pricing`              |
+| "what are customers actually saying" | `business/customer-research`  |
+| "write copy for this landing page" | `business/copywriting`          |
+| "plan a Product Hunt launch"       | `business/launch`               |
+| "why do people buy this stuff"     | `business/marketing-psychology` |
+| "make a launch video for this"     | `business/brag`                 |
+
+**Workflow:**
+
+| You say                            | Skill fires                     |
+| ---------------------------------- | ------------------------------- |
+| "brainstorm this idea"             | `workflow/office-hours`         |
+| "ship it / create a PR"            | `workflow/ship`                 |
+| "be careful with that command"     | `workflow/careful`              |
+| "save my progress"                 | `workflow/context-save`         |
+| "where was I / resume"             | `workflow/context-restore`      |
+| "code health check"                | `workflow/health`               |
+| "what have we learned"             | `workflow/learn`                |
+
+`architecture/progress-guard` and `ai-agent/ultra-context-engine` don't wait to be called by name. They run in the background whenever their trigger conditions show up in the conversation (side-work-instead-of-shipping, and token-budget pressure, respectively).
+
+**See what's installed:** `skillset list`. **Remove one:** `skillset install --undo --skill ui/motion`.
+
+### Using your local skills (nerdev/*)
+
+The three `nerdev/*` skills live in `skills/nerdev/` but **aren't managed by the sync script**. They're owned directly in this repo, same as everything in "Everything else" above.
+
+**Option A: Use from this repo (recommended)**
+
+```bash
+# From skillset root
+opencode  # opencode.json points to ./skills
+# skill nerdev/nerdev-monorepo  → works
+```
+
+**Option B: Symlink globally (works everywhere)**
+
+```bash
+ln -sf /path/to/skillset/opencode.json ~/.config/opencode/opencode.json
+# Now in ANY directory:
+opencode
+# skill nerdev/nerdev-monorepo  → works
+```
+
+**Option C: Copy to a project**
+
+```bash
+cp -r /path/to/skillset/skills/nerdev/nerdev-monorepo /my-project/.opencode/skills/
+# In /my-project:
+opencode
+# skill nerdev/nerdev-monorepo  → works
+```
+
+**Compose them:**
+
+```bash
+skill nerdev/nerdev-monorepo      # Repo skeleton + conventions
+skill nerdev/nerdev-abstraction   # Plug-and-play architecture
+skill nerdev/nerdev-docs          # Living docs + ADRs + runbooks
+```
+
+## CI/CD: how updates flow
+
+The `.github/workflows/sync.yml` workflow runs **nightly at 03:00 UTC** (and on demand via _Actions → Sync upstream skills → Run workflow_):
+
+1. `scripts/sync.mjs` shallow-clones each upstream repo from `vendor.json`, compares the pinned commit against `origin/HEAD`
+2. If upstream moved, the skill folders are re-vendored into `skills/` and `vendor.json` is bumped
+3. Every owned skill's `curations/<skill>/overlay/` is re-applied on top: upstream churn never overwrites your voice
+4. A PR titled `chore: sync skills from upstreams` is auto-opened against `main`
+5. Merge it, then publish:
+
+```bash
+npm version patch && npm publish
+```
+
+`.github/workflows/sync.yml` also runs `npm run lint:ste` on every push. Every owned `.md` file has to stay under 5.0 STE violations per 100 words (synced upstream files are exempt).
+
+New versions flow: upstream repo → nightly sync → PR → merge → publish → `npx @nalindalal/skillset install` on any machine.
+
+## Ownership model
+
+Upstream SKILL.md files encode someone else's judgment about someone else's
+codebase. The moment a skill matters to you, it should encode yours.
+
+```text
+curations/
+  <skill>/
+    overlay/          # your owned versions, copied over skills/<category>/<skill>/ after EVERY sync
+    WHY.md            # why you own it this way; read by sync, never shipped
+```
+
+- **Pick what to own.** Upstream never ships a file you've overlaid. Your
+  version always wins. Everything else in that skill still tracks upstream.
+- **Never edit `skills/<category>/<skill>/` directly** for the 5 synced skills. The next
+  sync deletes the folder. If you want it in your voice, put it in
+  `curations/<skill>/overlay` first. (This does not apply to the 61 owned
+  skills, those you edit directly, since nothing re-vendors them.)
+- **Write the why.** `WHY.md` is the difference between curation and
+  copy-paste. Future-you and future agents read it.
+
+Try it:
+
+```bash
+cp -R curations/TEMPLATE curations/impeccable   # then fill in overlay/ + WHY.md
+npm run sync                                    # overlay survives, check git diff
+```
+
+## Manual sync
+
+```bash
+node scripts/sync.mjs            # check + apply updates
+node scripts/sync.mjs --dry-run  # report only
+node scripts/sync.mjs --repo taste-skill  # one upstream only
+```
+
+## Structure
+
+```
+skills/
+├── ui/                    # UI components, animations, design systems
+├── backend/               # API, auth, database, realtime, security
+├── devops/                # CI/CD, deployment, testing, performance
+├── architecture/          # Planning, onboarding, research
+├── engineering/           # TDD, code review, verification, standards
+├── quality/               # Writing quality, anti-slop
+├── business/              # Freelancing, startup, career, marketing
+├── nerdev/                # Nerdev skill family
+├── ai-agent/              # Agent docs, context management
+└── workflow/              # Ship, context save/restore, health, learn
+
+curations/<name>/          # your ownership layer: overlay/ + WHY.md (never touched by sync)
+vendor.json                # upstream repos + pinned commits + skill maps
+scripts/sync.mjs           # re-vendor logic (used by CI and manually)
+scripts/ste-gate.mjs       # STE prose-quality gate, runs on every push
+bin/skillset.mjs           # the CLI (npm bin target)
+.github/workflows/sync.yml # nightly auto-sync + PR
+```
+
+## License
+
+MIT: see [LICENSE](LICENSE).

package/bin/skillset.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * skillset: install, list, and sync agent skills from this repo.
+ *
+ *   skillset list                          list available skills
+ *   skillset install [--skill <name>]...   install into agent harnesses
+ *       --target claude,opencode,cursor,codex,gemini   (default: all detected)
+ *       --scope global|project             (default: global)
+ *       --dry-run
+ *   skillset sync [--dry-run]              re-vendor from upstream repos
+ */
+
+import { execSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SKILLS_DIR = join(ROOT, "skills");
+
+const HARNESSES = {
+  claude: { global: join(homedir(), ".claude", "skills"), project: ".claude/skills" },
+  opencode: { global: join(homedir(), ".config", "opencode", "skills"), project: ".opencode/skills" },
+  cursor: { global: join(homedir(), ".cursor", "skills"), project: ".cursor/skills" },
+  codex: { global: join(homedir(), ".agents", "skills"), project: ".agents/skills" },
+  gemini: { global: join(homedir(), ".gemini", "skills"), project: ".gemini/skills" },
+};
+
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+const rest = args.slice(1);
+
+function flag(name) {
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === `--${name}`) {
+      const next = rest[i + 1];
+      if (next && !next.startsWith("--")) return next;
+    } else if (rest[i].startsWith(`--${name}=`)) {
+      return rest[i].split("=").slice(1).join("=");
+    }
+  }
+  return undefined;
+}
+function hasFlag(name) {
+  return rest.includes(name);
+}
+function flagValues(name) {
+  const vals = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === `--${name}`) {
+      const next = rest[i + 1];
+      if (next && !next.startsWith("--")) {
+        vals.push(next);
+        i++;
+      }
+    } else if (rest[i].startsWith(`--${name}=`)) {
+      vals.push(rest[i].split("=").slice(1).join("="));
+    }
+  }
+  return vals;
+}
+
+function walkSkills(dir, prefix) {
+  const results = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    const full = join(dir, e.name);
+    if (existsSync(join(full, "SKILL.md"))) {
+      results.push(rel);
+    }
+    results.push(...walkSkills(full, rel));
+  }
+  return results;
+}
+
+function listSkills() {
+  return walkSkills(SKILLS_DIR, "").sort();
+}
+
+function readDescription(relPath) {
+  try {
+    const md = readFileSync(join(SKILLS_DIR, relPath, "SKILL.md"), "utf8");
+    const m = md.match(/^description:\s*(.*)$/m);
+    if (!m) return "";
+    return m[1].replace(/^["']|["']$/g, "").slice(0, 120) + (m[1].length > 120 ? "…" : "");
+  } catch {
+    return "";
+  }
+}
+
+function cmdList() {
+  const skills = listSkills();
+  console.log(`skillset: ${skills.length} skills\n`);
+  for (const name of skills) {
+    const desc = readDescription(name);
+    console.log(`  ${name.padEnd(32)} ${desc}`);
+  }
+}
+
+function cmdInstall() {
+  const scope = flag("scope") ?? "global";
+  const targetFlag = flag("target");
+  const onlySkills = flagValues("skill");
+  const dry = hasFlag("--dry-run");
+  const undo = hasFlag("--undo");
+
+  const targets = targetFlag
+    ? targetFlag.split(",").map((t) => t.trim()).filter(Boolean)
+    : Object.keys(HARNESSES);
+
+  const all = listSkills();
+  const allLeaf = all.map((p) => p.split("/").pop());
+  const skills = onlySkills.length
+    ? onlySkills.filter((s) => all.includes(s) || allLeaf.includes(s)).map((s) => {
+        const idx = all.indexOf(s);
+        return idx >= 0 ? all[idx] : all[allLeaf.indexOf(s)];
+      })
+    : all;
+  const missing = onlySkills.filter((s) => !all.includes(s) && !allLeaf.includes(s));
+  if (missing.length) console.warn(`  ! unknown skill(s): ${missing.join(", ")}. Skipped\n`);
+
+  let installed = 0;
+  for (const target of targets) {
+    const cfg = HARNESSES[target];
+    if (!cfg) {
+      console.warn(`  ! unknown target "${target}" (valid: ${Object.keys(HARNESSES).join(", ")})`);
+      continue;
+    }
+    const destBase = scope === "project" ? join(process.cwd(), cfg.project) : cfg.global;
+    for (const skill of skills) {
+      const leafName = skill.split("/").pop();
+      const safeSkill = leafName.replace(/\.\./g, "").replace(/[/\\]/g, "");
+      if (safeSkill !== leafName) {
+        console.warn(`  ! sanitized skill name: ${leafName} → ${safeSkill}`);
+      }
+      const dest = join(destBase, safeSkill);
+      if (dry) {
+        console.log(`  ~ ${target}: would install ${skill} → ${dest}`);
+        continue;
+      }
+      if (undo) {
+        if (existsSync(dest)) {
+          rmSync(dest, { recursive: true, force: true });
+          installed++;
+          console.log(`  ✗ ${target}: removed ${safeSkill}`);
+        }
+        continue;
+      }
+      mkdirSync(destBase, { recursive: true });
+      cpSync(join(SKILLS_DIR, skill), dest, { recursive: true });
+      installed++;
+      console.log(`  ✓ ${target}: installed ${skill} → ${dest}`);
+    }
+  }
+
+  if (dry) {
+    console.log(`\n[dry-run] would ${undo ? "remove" : "install"} ${skills.length} skill(s) ${undo ? "from" : "into"} ${targets.join(", ")} (${scope})`);
+  } else {
+    const verb = undo ? "removed" : "installed";
+    console.log(`\nDone. ${installed} skill(s) ${verb} (${scope}). Restart/reload your agent to pick them up.`);
+  }
+}
+
+function cmdSync() {
+  const dry = hasFlag("--dry-run");
+  execSync(`${process.execPath} ${join(ROOT, "scripts", "sync.mjs")} ${dry ? "--dry-run" : ""}`, {
+    stdio: "inherit",
+  });
+}
+
+function cmdHelp() {
+  console.log(`skillset: install, list, and sync agent skills.
+
+Usage:
+  skillset list                        list available skills (category/name)
+  skillset install [--skill <name>]   install skills into agent harnesses
+      --target <claude,opencode,cursor,codex,gemini>   (default: all)
+      --scope <global|project>         (default: global)
+      --dry-run
+      --undo                           remove installed skills
+  skillset sync [--dry-run]           re-vendor skills from upstream repos
+
+Examples:
+  skillset install                                    # everything, global
+  skillset install --skill ui/motion --skill backend/auth
+  skillset install --target claude,opencode --scope project
+  skillset install --undo                             # remove everything installed
+`);
+}
+
+switch (command) {
+  case "list":
+    cmdList();
+    break;
+  case "install":
+    cmdInstall();
+    break;
+  case "sync":
+    cmdSync();
+    break;
+  default:
+    cmdHelp();
+}

package/curations/README.md

@@ -0,0 +1,53 @@
+# Curation layer: skills are owned, not copied
+
+Upstream SKILL.md files are a **base**, never the final word. A skill you run
+every day should sound like *you*: it should encode how you like this codebase,
+how you want things done, and why, not whatever the upstream author happened
+to write.
+
+This directory is where that ownership lives. It never gets deleted,
+re-cloned, or overwritten by `scripts/sync.mjs`. Upstream can move, and your
+voice survives verbatim.
+
+## Layout
+
+```
+curations/
+  <skill>/
+    overlay/          # files copied ON TOP of skills/<skill>/ after every sync
+    WHY.md            # your rationale, read by sync output, never shipped
+```
+
+- `overlay/` files replace the same-named files in `skills/<skill>/` after each
+  re-vendor. Upstream updated the skill's scripts? They still land. Upstream
+  rewrote the SKILL.md with someone else's taste? Your `overlay/SKILL.md` wins.
+- `WHY.md` is the record of intent: what you changed and why. The first line is
+  echoed in sync output so you can see the reason at a glance.
+- Files you don't put in `overlay/` track upstream freely. Own what matters,
+  let the rest ride.
+
+## How ownership works
+
+1. Make a copy: `mkdir -p curations/<skill>/overlay`
+2. Write your version of the files you own into `overlay/` (usually just
+   `SKILL.md`).
+3. Write `WHY.md` with the real reasons: how you like things, why. This is
+   the part that makes it yours; future-you (and future agents) will ask.
+4. Run `npm run sync` (or let CI) and the overlay is re-applied after every
+   upstream update. `git diff` shows upstream changes and your layer cleanly
+   separated.
+
+## How to NOT use it
+
+- Don't hand-edit `skills/<skill>/SKILL.md` directly. The next sync deletes
+  the folder and you lose it. That's the sloppiness this layer exists to kill.
+- Don't copy a curation wholesale from someone else. The point is your
+  judgment about your codebase, not a secondhand opinion.
+
+## Template
+
+See `curations/TEMPLATE/` for a ready-to-fill skeleton:
+
+```
+cp -R curations/TEMPLATE curations/<skill>
+```

package/curations/TEMPLATE/WHY.md

@@ -0,0 +1,23 @@
+# WHY.md: why this skill is owned, not synced
+
+> First line is echoed by `npm run sync`. Write it like a note to future-you.
+
+Replace this with a one-line reason (echoed in sync output).
+
+## What I changed
+
+- (which files in overlay/ exist and what they say)
+
+## How I like things
+
+- (your preferences: tone, structure, scope, when to use this skill)
+
+## Why these changes matter to my codebase
+
+- (what upstream gets wrong / misses about how you work, and the concrete
+  consequences of having it your way)
+
+## Review cadence
+
+- (when to revisit: after each upstream update? when a project hits a
+  milestone?)

package/curations/TEMPLATE/overlay/SKILL.md

@@ -0,0 +1,6 @@
+Copy this file into overlay/ as the file you want to own (usually SKILL.md),
+then rewrite it in your voice.
+
+The version here replaces the upstream file after every sync. Upstream
+contributions to other files in the skill still land fresh. Only what you put
+in overlay/ is frozen to your taste.