@sassywares/skills 0.1.0 → 0.2.0

package/CONCEPTS.md

@@ -2,11 +2,11 @@
 
 ## Source of truth
 
-The repo's `skills/` directory is the only copy of the skills. `~/.agents/skills` is a symlink to it. Changes are picked up by pi immediately; the sync service handles git commit and push.
+The repo's `skills/` directory is the only copy of the skills. It ships as the npm package `@sassywares/skills`, so consumers pin a version rather than linking a directory; the sync service handles git commit and push.
 
 ## Skill
 
-A directory containing `SKILL.md`, discovered by pi from `~/.agents/skills`. Skills are explicit workflows, not always-on instructions. Most have `disable-model-invocation: true` and are invoked with `/skill:<name>`.
+A directory containing `SKILL.md`, discovered by a harness from a project skills directory, a user skills directory, or an installed package. Skills are explicit workflows, not always-on instructions. Most have `disable-model-invocation: true` and are invoked with `/skill:<name>`.
 
 ## Agent
 
@@ -56,4 +56,4 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
 
 ## Sync
 
-There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. The sync script repairs the directory symlink, commits skill changes, rebases on `origin/main`, and pushes. New and removed skills need no per-skill symlink work.
+There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. The sync script commits the change, rebases on `origin/main`, and pushes. It installs nothing: a changed skill reaches consumers only when a new version is released and a consumer bumps its pin.

package/README.md

@@ -271,52 +271,55 @@ sassy-skills/
 
 ## Installation
 
-Sassy Skills are plain Agent Skills. Install them as a pi package from npm, or clone the repo and symlink the whole suite or copy only the skills you want.
+The suite ships as the npm package **`@sassywares/skills`**. Pin it, don't symlink it into a global directory — the version in your lockfile is the pin, and upgrading is one command.
 
-### Option 0 — install as a pi package
+### As a project dependency (recommended for teams)
 
 ```bash
-pi install npm:@sassywares/skills
+bun add -d @sassywares/skills
 ```
 
-This pins the published version and reconciles on `pi update --extensions`. Use `pi install git:github.com/sassywares/sassy-skills` to track the repo instead of a release.
-
-### Clone
+Nothing scans `node_modules` on its own, so give your harness the directory it does read:
 
 ```bash
-git clone https://github.com/sassywares/sassy-skills.git ~/sassy-skills
+mkdir -p .agents/skills
+for d in node_modules/@sassywares/skills/skills/*/; do
+  ln -sfn "../../$d" ".agents/skills/$(basename "$d")"
+done
 ```
 
-### Option A — symlink the whole suite
+`.agents/skills/` is read by Cursor and pi. Claude Code reads `.claude/skills/` only, so add one directory symlink:
 
 ```bash
-ln -s ~/sassy-skills/skills ~/.agents/skills
+mkdir -p .claude && ln -sfn ../.agents/skills .claude/skills
 ```
 
-Replace `~/.agents/skills` with your harness's skills directory if it uses a different path.
+Ignore both: they're derived from the lockfile, like any build output. A `postinstall` that runs the loop gives teammates zero setup beyond `bun install`; a preflight in the skills tells anyone who skipped it what to run.
+
+### As a pi package
 
-### Option B — symlink individual skills
+pi resolves packages directly, so no links are needed:
 
 ```bash
-mkdir -p /path/to/your/skills
-ln -s ~/sassy-skills/skills/sassy-plan /path/to/your/skills/sassy-plan
-ln -s ~/sassy-skills/skills/sassy-work /path/to/your/skills/sassy-work
+pi install npm:@sassywares/skills@0.1.0            # user-level, all projects
+pi install npm:@sassywares/skills@0.1.0 --local     # project-level → commit .pi/settings.json
 ```
 
-### Option C — copy individual skills
+### While editing the suite
+
+Point a consumer at your checkout instead of a published version:
 
 ```bash
-mkdir -p /path/to/your/skills
-cp -R ~/sassy-skills/skills/sassy-plan /path/to/your/skills/
+bun link @sassywares/skills
 ```
 
-Use this when you only want a few workflows and do not want to track the repo.
+Inside this repo, `.pi/settings.json` already declares `./skills`, so pi loads the working copy directly.
 
-Invoke the skills using your harness's skill syntax.
+Get the skills however they arrive — package, link, or vendored copy — and invoke them with your harness's skill syntax.
 
 ## Repository maintenance
 
-`scripts/sync.sh` repairs the symlink, commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. `AGENTS.md` documents the workflow for agents working on this repo.
+`scripts/sync.sh` commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere — a change reaches consumers when a version is released and they bump their pin. `AGENTS.md` documents the workflow for agents working on this repo.
 
 ### Releases
 

package/bin/sassy-skills.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// sassy-skills — wire this package's skills into a project.
+//
+// Nothing scans node_modules on its own, so the harnesses that read a project
+// skills directory need links. This tool creates them, checks them, and updates
+// the pinned version.
+//
+//   sassy-skills sync            link skills into .agents/skills (and .claude/skills)
+//   sassy-skills check           exit 1 if the wiring is missing or stale
+//   sassy-skills update          bump to the latest published version, then sync
+//
+// Options: --root <dir>  --quiet  --help
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = resolve(HERE, "..", "skills");
+const PKG = JSON.parse(readFileSync(resolve(HERE, "..", "package.json"), "utf8"));
+const NAME = PKG.name;
+const VERSION = PKG.version;
+const REGISTRY = process.env.SASSY_SKILLS_REGISTRY ?? "https://registry.npmjs.org";
+
+const args = process.argv.slice(2);
+const quiet = args.includes("--quiet");
+const rootFlag = args.indexOf("--root");
+const rootValueIndex = rootFlag >= 0 ? rootFlag + 1 : -1;
+const ROOT = rootFlag >= 0 ? resolve(args[rootFlag + 1] ?? ".") : process.cwd();
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`sassy-skills@${VERSION}\n\n  sync     link skills into .agents/skills and .claude/skills\n  check    exit 1 when the wiring is missing or stale\n  update   bump ${NAME} to the latest version, then sync\n  outdated print a one-line nudge when a newer version is published (throttled, offline-safe)\n\nOptions: --root <dir>  --quiet  --force`);
+  process.exit(0);
+}
+
+const command = args.find((a, i) => !a.startsWith("-") && i !== rootValueIndex) ?? "sync";
+
+const log = (...a) => { if (!quiet) console.log(...a); };
+const ok = (m) => log(`  ✓ ${m}`);
+const warn = (m) => console.error(`  ! ${m}`);
+const die = (m) => { console.error(`  ✗ ${m}`); process.exit(1); };
+
+const IS_WIN = process.platform === "win32";
+
+function linkedSkills() {
+  if (!existsSync(SKILLS_DIR)) die(`package has no skills/ directory at ${SKILLS_DIR}`);
+  return readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(SKILLS_DIR, e.name, "SKILL.md")))
+    .map((e) => e.name)
+    .sort();
+}
+
+function makeLink(target, linkPath) {
+  try {
+    if (lstatSync(linkPath).isSymbolicLink()) rmSync(linkPath);
+    else { warn(`${linkPath} exists and is not a symlink — leaving it alone`); return false; }
+  } catch { /* does not exist */ }
+  symlinkSync(target, linkPath, IS_WIN ? "junction" : "dir");
+  return true;
+}
+
+function sync() {
+  const skills = linkedSkills();
+  const agents = join(ROOT, ".agents", "skills");
+  mkdirSync(agents, { recursive: true });
+
+  let made = 0;
+  for (const name of skills) {
+    const target = resolve(SKILLS_DIR, name);
+    if (makeLink(target, join(agents, name))) made++;
+  }
+  ok(`${skills.length} skills linked into .agents/skills (${NAME}@${VERSION})`);
+
+  // Claude Code reads .claude/skills only. A directory symlink is enough, and it
+  // is the least invasive form when the directory does not already exist.
+  const claude = join(ROOT, ".claude", "skills");
+  try {
+    const st = lstatSync(claude);
+    if (!st.isSymbolicLink()) {
+      warn(".claude/skills exists and is not a symlink — Claude Code will not see the project skills unless you link them yourself");
+    }
+  } catch {
+    mkdirSync(dirname(claude), { recursive: true });
+    symlinkSync(IS_WIN ? join(ROOT, ".agents", "skills") : "../.agents/skills", claude, IS_WIN ? "junction" : "dir");
+    ok("linked .claude/skills → .agents/skills");
+  }
+
+  if (made) log(`\nRestart or /reload your harness to pick up the new skills.`);
+  return 0;
+}
+
+function check() {
+  const skills = linkedSkills();
+  const agents = join(ROOT, ".agents", "skills");
+  let problems = 0;
+
+  for (const name of skills) {
+    const link = join(agents, name);
+    const target = resolve(SKILLS_DIR, name);
+    try {
+      const st = lstatSync(link);
+      if (!st.isSymbolicLink()) { warn(`${name}: real directory, not a link`); problems++; continue; }
+      const points = resolve(agents, readlinkSync(link));
+      if (points !== target) { warn(`${name}: points at ${points}, expected ${target}`); problems++; }
+    } catch {
+      warn(`${name}: not linked`);
+      problems++;
+    }
+  }
+  if (!existsSync(join(ROOT, ".claude", "skills"))) warn(".claude/skills missing (Claude Code only)");
+  if (problems) { console.error(`  ✗ ${problems} skill link(s) need attention — run: sassy-skills sync`); return 1; }
+  ok(`${skills.length} skills correctly linked (${NAME}@${VERSION})`);
+  return 0;
+}
+
+function detectPM() {
+  if (existsSync(join(ROOT, "bun.lock")) || existsSync(join(ROOT, "bun.lockb"))) return "bun";
+  if (existsSync(join(ROOT, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(ROOT, "yarn.lock"))) return "yarn";
+  if (existsSync(join(ROOT, "package-lock.json"))) return "npm";
+  return null;
+}
+
+function update() {
+  const pm = detectPM();
+  if (!pm) die("no lockfile found — cannot tell which package manager to update with");
+  const spec = `${NAME}@latest`;
+  const cmd = {
+    bun: ["bun", ["add", "--dev", "--exact", spec]],
+    npm: ["npm", ["install", "--save-dev", "--save-exact", spec]],
+    pnpm: ["pnpm", ["add", "--save-dev", "--save-exact", spec]],
+    yarn: ["yarn", ["add", "--dev", "--exact", spec]],
+  }[pm];
+  log(`Updating ${NAME} with ${pm}…`);
+  execFileSync(cmd[0], cmd[1], { cwd: ROOT, stdio: "inherit" });
+  return sync();
+}
+
+function newerThan(a, b) {
+  const pa = String(a).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+function updateHint() {
+  const pm = detectPM();
+  const script = pm === "bun" ? "bun run skills:update"
+    : pm ? `${pm} run skills:update`
+    : "sassy-skills update";
+  return script;
+}
+
+// Non-blocking version nudge. Throttled to once a day per machine, silent when
+// offline, and it never fails a run — a stale pin is worth mentioning, not
+// worth blocking work over.
+async function outdated(force = false) {
+  const cacheFile = join(tmpdir(), "sassy-skills-version-check.json");
+  const TTL = 24 * 60 * 60 * 1000;
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cacheFile, "utf8")); } catch { /* first run */ }
+
+  let latest = null;
+  const fresh = cached && typeof cached.checkedAt === "number" && Date.now() - cached.checkedAt < TTL;
+  if (fresh && !force) {
+    latest = cached.latest ?? null;
+  } else {
+    try {
+      const res = await fetch(`${REGISTRY}/${encodeURIComponent(NAME)}/latest`, {
+        signal: AbortSignal.timeout(2000),
+        headers: { accept: "application/json" },
+      });
+      const body = await res.json();
+      latest = typeof body?.version === "string" ? body.version : null;
+    } catch { latest = null; }
+    try { writeFileSync(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest })); } catch { /* read-only tmp */ }
+  }
+
+  if (!latest || !newerThan(latest, VERSION)) return 0;
+  console.log(`  ↑ ${NAME} ${VERSION} → ${latest} available — ${updateHint()}`);
+  return 0;
+}
+
+switch (command) {
+  case "outdated": process.exit(await outdated(args.includes("--force")));
+  case "sync": process.exit(sync());
+  case "check": process.exit(check());
+  case "update": process.exit(update());
+  default:
+    die(`unknown command: ${command} (try --help)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   ],
   "files": [
     "skills",
+    "bin",
     "README.md",
     "CONCEPTS.md",
     "LICENSE"
@@ -35,5 +36,8 @@
     "skills": [
       "./skills"
     ]
+  },
+  "bin": {
+    "sassy-skills": "./bin/sassy-skills.mjs"
   }
 }

package/skills/sassy-babysit/SKILL.md

@@ -21,7 +21,7 @@ Keep an open PR moving toward merge by reacting to three streams as each arrives
 
 An explicit token always beats the config.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.*` seeds `merge` and `delete_branch`; `hooks.pr.before_merge` and `hooks.pr.after_merge` inject project steps around a merge.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.*` seeds `merge` and `delete_branch`; `hooks.pr.before_merge` and `hooks.pr.after_merge` inject project steps around a merge.
 
 **One PR per run.** This skill watches the PR resolved from the argument or the current branch. A workspace fan-out is N runs, one per PR, and `pr.merge` never merges a fan-out — that needs an explicit say-so per PR.
 

package/skills/sassy-commit/SKILL.md

@@ -28,7 +28,7 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 
 **Never bypass hooks.** No `--no-verify`, and never pass it through to a project script this run invokes. A repo's git hooks are the layer that cannot be skipped, so disabling them silently removes an enforcement the project relies on.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. `commit.branch` supplies the default.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `commit.branch` supplies the default.
 
 **Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `repos[<dir>]` in a workspace config, else `git.default_branch`, else the probed base — named `<name>` when given, else from the change. `sassy-commit-push-pr` forwards its own `branch` choice here.
 

package/skills/sassy-commit-push-pr/SKILL.md

@@ -16,7 +16,7 @@ disable-model-invocation: true
 
 **Options.** `branch:new|current` selects the branch policy below. `babysit:on|off` (default `on`) controls the closing babysit. `checkpoint` bounds that babysit to a single tick. `merge:on|off` and `delete-branch:on|off` (both default `off`) are forwarded unchanged to `sassy-babysit`.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. `commit.branch` seeds the branch policy, `pr.*` seeds the babysit options, and `hooks.pr.before_create` / `hooks.pr.after_create` inject project steps around the PR.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `commit.branch` seeds the branch policy, `pr.*` seeds the babysit options, and `hooks.pr.before_create` / `hooks.pr.after_create` inject project steps around the PR.
 
 ## Context
 

package/skills/sassy-compound/SKILL.md

@@ -15,7 +15,7 @@ disable-model-invocation: true
 
 **Modes.** Default `mode:manual` asks before the `AGENTS.md` pointer edit; `mode:auto` applies that edit silently. Ship passes `mode:auto` after its own gate. Never toggle it yourself.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. Paths come from `artifacts.solutions` and `artifacts.concepts`; never hardcode them.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. Paths come from `artifacts.solutions` and `artifacts.concepts`; never hardcode them.
 
 ## When it qualifies — the durable bar
 

package/skills/sassy-debug/SKILL.md

@@ -23,7 +23,9 @@ Establish the exact input, the observed symptom, the expected behavior, and how
 
 Trivial bugs whose cause is readable from the input may skip the scout, but still state the causal chain and pass the fix gate before changing code, then run the fix through `sassy-cycle`.
 
-**Search prior learnings first.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. For every existing path in `knowledge.read`, search the docs for the symptom's keywords, the module, and the failure type. A matching doc **seeds or confirms** a hypothesis — it never replaces the causal chain or the reproduction. Name the docs you consulted, and say plainly when none matched: no match is not evidence that nothing similar has happened.
+**Search prior learnings first.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. For every existing path in `knowledge.read`, search the docs for the symptom's keywords, the module, and the failure type. A matching doc **seeds or confirms** a hypothesis — it never replaces the causal chain or the reproduction. Name the docs you consulted, and say plainly when none matched: no match is not evidence that nothing similar has happened.
+
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
 
 ## Phase 1 — Diagnose inline, with `scout` as a helper
 

package/skills/sassy-handbook/SKILL.md

@@ -15,7 +15,7 @@ disable-model-invocation: true
 
 **Not this skill:** durable gotcha learnings (`sassy-compound`), implementation plans, or shipping code.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Handbooks land in `artifacts.handbooks`.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Handbooks land in `artifacts.handbooks`.
 
 ## When to run
 

package/skills/sassy-lfg/SKILL.md

@@ -14,7 +14,9 @@ disable-model-invocation: true
 
 **The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle` per phase, then `sassy-ship`. Never edit application code. Keep the main context small — all heavy work happens in subagents.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. Plans live under `artifacts.plans`; `git.repo` decides how the close-out persists.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. Plans live under `artifacts.plans`; `git.repo` decides how the close-out persists.
+
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
 
 ## Input
 

package/skills/sassy-plan/SKILL.md

@@ -15,7 +15,9 @@ disable-model-invocation: true
 
 **Does not implement.** Planning never implements. Execution belongs to `sassy-work` or `sassy-lfg`, and only after the user picks.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. Plans land in `artifacts.plans`.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. Plans land in `artifacts.plans`.
+
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
 
 ## Phase A — Discuss (brainstorm)
 

package/skills/sassy-plan/marker

@@ -0,0 +1 @@
+keep

package/skills/sassy-review/SKILL.md

@@ -13,6 +13,8 @@ disable-model-invocation: true
 
 **Outcome:** the scope reviewed with concrete findings; the approved fixes applied; everything left uncommitted.
 
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
+
 **Orchestrator only.** Never edit code yourself. The `reviewer` finds; the `worker` fixes.
 
 ## Review dimensions

package/skills/sassy-setup/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: true
 
 # Sassy Setup
 
-**Outcome:** `.sassywares/config.yaml` at the project root, matching the tree it describes. In `workspace` mode, also `.sassywares/workspace/snapshot` and `.sassywares/workspace/.gitignore`.
+**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills wired as a pinned dependency and visible to the harness, and — in `workspace` mode — the snapshot tooling installed.
 
 **Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
 
@@ -20,7 +20,7 @@ disable-model-invocation: true
 
 ## Steps
 
-1. **Resolve the start.** The argument's path, else the working directory. If a `.sassywares/config.yaml` is already found walking up, this is a **verify run**: skip to step 5 with `--check`.
+1. **Resolve the start.** The argument's path, else the working directory. If a `.sassywares/config.yaml` is already found walking up, this is a **verify run**: run the checks in step 7 and report, without rewriting anything.
 2. **Detect.** Run `scripts/detect.sh --root <path>`. It prints a proposed config: topology (`repo`, `workspace`, `none`), the remote name, a probed base branch, nested repos with their bases, and which artifact paths exist.
 3. **Ask only what detection cannot answer.** Never re-ask what the tree already said.
    - **`workspace`** — the snapshot mirror: create a **private** GitHub repo, or connect an existing one (`owner/name` or URL)? For creating it, get explicit approval and name the slug before running anything. Automatic creation is `gh repo create` inside `snapshot`, and only after that approval.
@@ -31,7 +31,18 @@ disable-model-invocation: true
    - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
    - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and write the skills they name. Leave them `[]` when they have nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
 4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
-5. **Install, `workspace` only.** The layout is fixed, and everything the snapshot owns lives under one directory:
+5. **Wire the skills.** The suite is the package `@sassywares/skills`, and its own CLI creates the links. Never copy skill files into a project.
+
+   - **It needs a `package.json`.** With none, say so and ask whether to add a minimal manifest or skip the wiring. Do not create one unasked, and do not invent a second distribution mechanism for non-JS projects.
+   - **Detect the package manager** from the lockfile: `bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`. Ask when several disagree or none exists.
+   - **Add the dependency pinned exactly** — `bun add --dev --exact @sassywares/skills@<version>`, `npm install --save-dev --save-exact …`, `pnpm add --save-dev --save-exact …`, `yarn add --dev --exact …`. Exact, because one pinned version for every teammate and every harness is the entire point.
+   - **Scripts**, adding only what is missing: `"skills:sync": "sassy-skills sync"`, `"skills:update": "sassy-skills update"`, and `"postinstall": "sassy-skills sync"`. **Never overwrite an existing `postinstall`** — if one is there, leave it alone and tell the user to chain `&& sassy-skills sync`, so setup cannot erase someone's install steps.
+   - **Run `sassy-skills sync`.** The package's CLI is now in `node_modules/.bin`; it links `.agents/skills/sassy-*` and creates `.claude/skills → ../.agents/skills`. The linking rules travel with the lockfile, so they upgrade with the suite instead of drifting in the repo.
+   - **Ignore the derived links.** Add `/.agents/skills/sassy-*` and `/.claude/skills` to `.gitignore` when missing. Create `.gitignore` only when there is none.
+   - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
+   - **Tell the user to `/reload`.** The links are invisible to the harness until it rescans.
+
+6. **Install the snapshot, `workspace` only.** The layout is fixed, and everything the snapshot owns lives under one directory:
 
    ```text
    .sassywares/
@@ -46,8 +57,8 @@ disable-model-invocation: true
    - Write `.sassywares/workspace/.gitignore` for excluded paths (vendored trees, generated dirs, `.run/`). One pattern per line, `.gitignore` style. Skip it when there is nothing to exclude; the snapshot syncs without it. The mirror itself needs no line — the script excludes it.
    - Do **not** add a `.gitignore` at the project root, and do not modify one that exists.
    - Do **not** run the snapshot during setup. It clones and pushes; that is the user's call. Offer `--dry-run` and run it only if they ask.
-6. **Verify.** Run `scripts/detect.sh --root <path> --check`. Report every `drift:` line it prints — including an outdated `snapshot` version — or that the config matches the tree.
-7. **Report.** The config path, the topology, the resolved artifact and knowledge paths, and in `workspace` mode what was installed. **Commit nothing.**
+7. **Verify.** Run `scripts/detect.sh --root <path> --check`, then `sassy-skills check` for the links. Report every `drift:` line it prints — including an outdated `snapshot` version — or that the config matches the tree.
+8. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the skills version pinned and that `/reload` is needed, and in `workspace` mode what was installed. **Commit nothing.**
 
 ## Hard rules
 
@@ -58,7 +69,9 @@ disable-model-invocation: true
 | No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
 | Version is reported | Setup names the snapshot version it installed; `--check` flags an installed copy older than the skill's. |
 | Never commit | Setup writes files and stops. Committing is `sassy-commit`. |
-| Write boundary | Only `.sassywares/config.yaml`, `.sassywares/workspace/snapshot`, and `.sassywares/workspace/.gitignore`. Nothing at the project root. |
+| Skills are a dependency | Pin `@sassywares/skills`; never copy skill files into a project or maintain hand-made links. |
+| Scripts are shared | Adding a missing script is fine; rewriting an existing `postinstall` or `skills:*` entry is not. |
+| Write boundary | Only `.sassywares/`, the `package.json` scripts and devDependency, the lockfile, and two `.gitignore` lines. Never skill content. |
 | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
 | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
 | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |

package/skills/sassy-setup/assets/sassywares-readme.md

@@ -0,0 +1,30 @@
+# .sassywares
+
+Project config and tooling for the Sassy Skills suite. Written by `sassy-setup`.
+
+## Skills
+
+Installed as the npm package `@sassywares/skills`, pinned exactly in `package.json`. The entries in `.agents/skills/` and the `.claude/skills` symlink are **derived** from that package — never edit them by hand and never commit them.
+
+```bash
+bun run skills:sync     # recreate the links after a fresh clone
+bun run skills:update   # bump to the latest published version, then relink
+```
+
+Skills print a one-line nudge when a newer version is published — once a day, and silently nothing when offline. It is never a blocker.
+
+`.agents/skills/` is read by pi and Cursor; Claude Code reads `.claude/skills/` only, which is why that symlink exists. After any change, `/reload` your harness.
+
+If a skill tells you another skill is missing, run `skills:sync` and restart. Substituted package managers: run the same script through `npm`, `pnpm`, or `yarn`.
+
+## Config
+
+`config.yaml` holds the project's paths, git topology, and PR defaults. Every key is documented inline, including its allowed values, and the full schema is in the `sassy-setup` skill's `references/config.md`. Verify the file still matches the tree:
+
+```bash
+node_modules/@sassywares/skills/skills/sassy-setup/scripts/detect.sh --root . --check
+```
+
+## Hooks
+
+`hooks.pr.*` names project skills that run inside the PR pipeline: `before_create`, `after_create`, `before_merge`, `after_merge`. They are ordinary skills in `.agents/skills/`, which means they are **code** — review them like code, and never point a hook at a copy of a suite skill.

package/skills/sassy-ship/SKILL.md

@@ -16,23 +16,25 @@ disable-model-invocation: true
 
 **Modes.** `mode:manual` (default) reviews the whole close-out before any side effect; `mode:auto` is pre-authorized and skips that review. Never toggle it on your own.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline.
+
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
 
 **Subagent-maximal by design.** The orchestrator delegates every heavy step (docs, tree reads, git, gh) to subagents and only receives compact summaries. It never reads diffs, file contents, or the tree itself.
 
 ## Steps (in order)
 
 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, and **the hooks this run will trigger, by point and name, or that none are declared** — and wait. In `mode:auto`, skip this gate.
-2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *read `~/.agents/skills/sassy-compound/SKILL.md` and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
-3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *read `~/.agents/skills/sassy-handbook/SKILL.md` and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
+2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
+3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
 4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
-   - **`git.repo` is a remote.** Dispatch a `worker`: *read `~/.agents/skills/sassy-commit/SKILL.md` and follow it*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. Use `branch:current` when already on a feature branch, so the docs land with the phase commits. When the checked-out branch is the base branch, use `branch:new <name>` so the branch is created from `origin/<base>` and carries every phase commit; a workspace run passes the run's shared branch name. Never push directly to the base branch. It returns the hash and subject.
+   - **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. Use `branch:current` when already on a feature branch, so the docs land with the phase commits. When the checked-out branch is the base branch, use `branch:new <name>` so the branch is created from `origin/<base>` and carries every phase commit; a workspace run passes the run's shared branch name. Never push directly to the base branch. It returns the hash and subject.
    - **`git.repo: workspace`.** Commit code inside each affected repo on the run's shared branch (cut once on the run's first commit, `branch:current` after), then run `.sassywares/workspace/snapshot`. The snapshot is the workspace's commit and it runs every time, right after approval. A missing or outdated `.sassywares/workspace/snapshot` is a blocker: report it and say to run `sassy-setup`.
    - **`git.repo: none`.** No commit exists here. Report that the work is not persisted and stop.
-5. **PR.** In a `remote` repo, dispatch a `worker`: *read `~/.agents/skills/sassy-commit-push-pr/SKILL.md` and follow it with `branch:current` and `babysit:off`* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
+5. **PR.** In a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
 
    **The PR step owns the PR hooks.** `before_create` and `after_create` run inside `sassy-commit-push-pr`, once per PR; ship neither runs nor repeats them.
-6. **Babysit.** With `pr.babysit` (default `true`), dispatch a `worker`: *read `~/.agents/skills/sassy-babysit/SKILL.md` and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
+6. **Babysit.** With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
 
    **One PR per run.** Babysitting a workspace fan-out means one `sassy-babysit` run per PR, and a fan-out is never auto-merged: `pr.merge` and `pr.merge:on` apply to a single-PR run only. A multi-repo merge needs an explicit per-PR say-so.
 

package/skills/sassy-skill/SKILL.md

@@ -23,6 +23,7 @@ disable-model-invocation: true
 - **Frontmatter fields:** `name`, `description` (required); optional `license`, `compatibility`, `metadata`, `allowed-tools`, `disable-model-invocation`.
 - Use `disable-model-invocation: true` for skills that should run only via explicit `/skill:name`.
 - **Locations:** user `~/.agents/skills/<name>/`; project `<repo>/.agents/skills/<name>/` (discovered from cwd up to the repo root). Also the `skills` array in settings and pi packages.
+- **Reference other skills by name, never by absolute path.** The suite can live in `~/.agents/skills/`, a project `.agents/skills/`, or inside `node_modules/`, so "load the sassy-commit skill" is portable where a `~/…` path is not. Name a bundled file as "the sassy-setup skill's `references/config.md`".
 - Pi **validates at startup**; malformed or descriptionless skills warn. `/reload` applies changes.
 - Pi implements the **Agent Skills specification** (agentskills.io). For the full spec, pi's own `docs/skills.md` is authoritative — read it when the rules here are not enough.
 

package/skills/sassy-validate/SKILL.md

@@ -13,6 +13,8 @@ disable-model-invocation: true
 
 **Outcome:** a grounded conformance judgment against an intent; the approved gaps closed; everything left uncommitted.
 
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
+
 **Orchestrator only.** Never edit code yourself. The `validator` finds gaps; the `worker` closes them.
 
 **This skill needs an intent.** Validation without something to validate against is meaningless. If the user gave no plan path or intent, ask for one before doing anything.

package/skills/sassy-work/SKILL.md

@@ -17,7 +17,9 @@ disable-model-invocation: true
 
 **The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle`, apply its result, update the plan's tracking table, dispatch `sassy-commit` or the snapshot, and report. Never edit application code.
 
-**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per `~/.agents/skills/sassy-setup/references/config.md`. Precedence: explicit token > session instruction > config > skill default. `git.repo` decides what the phase commit does, `artifacts.plans` decides where the plan lives.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `git.repo` decides what the phase commit does, `artifacts.plans` decides where the plan lives.
+
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
 
 ## Input
 
@@ -58,7 +60,7 @@ Always gate before committing. One worker fixes findings, one re-check, then pre
    - **Any QA row fails** → run `sassy-cycle` once more on the same phase, with the failing rows as the intent reference and a work brief that fixes exactly those failures. Then present the gate again. If a row still fails after that one pass, mark it `Blocked` with the reason and stop.
 6. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
 
-   - **A remote** — dispatch a `worker` whose task is: *read `~/.agents/skills/sassy-commit/SKILL.md` and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject.
+   - **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject.
    - **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch (cut once on the run's first commit with `branch:new <name>`, `branch:current` after), then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
    - **`none`** — nothing is persisted. Report that the phase's work is uncommitted and stop; never hand off on top of it.