@linchpinagency/skills 0.1.9 → 0.1.11

package/README.md

@@ -12,7 +12,7 @@ GitHub Copilot, and other compatible coding agents.
 ![Zero dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)
 
 <!-- x-release-please-start-version -->
-### Latest release: 0.1.9
+### Latest release: 0.1.11
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -66,9 +66,10 @@ Then start a new session in your project and ask for something real — "what ki
 is this?" should pull in `project-context` and get you a summary of the repo shape, local
 environment, and host.
 
-**Re-run the same command to update.** There's no upgrade command; the installer overwrites
-in place and always pulls the latest published version. Do it every few weeks, or when
-someone announces a new skill.
+**Re-run the same command to update.** There's no upgrade command — the installer diffs each
+skill's version against what you have, shows what would change, and asks before applying it.
+A run with nothing to change exits immediately, so re-running costs nothing. Do it every few
+weeks, or when someone announces a new skill.
 
 Full flag reference: [Install options](#install-options).
 
@@ -87,7 +88,7 @@ The fastest way to understand the library is to run one loop end to end:
 | Handle a client support ticket | "the client says their contact form isn't sending" | `support-triage` |
 | Add guardrails before touching prod | "careful mode — I'm on production" | `safety-hooks` |
 
-The full list is in [Available skills](#available-skills) — 20 of them, each with a
+The full list is in [Available skills](#available-skills) — 23 of them, each with a
 `When to use` section that says exactly when it applies and which skill to use instead.
 
 **When you want to be explicit**, name the skill: *"use the wp-audit skill on the homepage."*
@@ -177,6 +178,9 @@ npx @linchpinagency/skills --global
 
 # Install the Linchpin skills only, without the upstream base layer
 npx @linchpinagency/skills --skip-upstream
+
+# Audit every scope for duplicate installs; install nothing
+npx @linchpinagency/skills --check
 ```
 
 > Pin a version when you need reproducibility — `npx @linchpinagency/skills@0.1.1` — or omit
@@ -188,8 +192,38 @@ npx @linchpinagency/skills --skip-upstream
 > network access and a system `tar`; if either is missing it warns and still installs the
 > Linchpin skills. Pass `--skip-upstream` to install the Linchpin skills alone.
 
-**Updating:** re-run the same command. The installer overwrites each skill in place, so a
-fresh run always pulls the latest published version.
+**Updating:** re-run the same command — that *is* the update path. Rather than overwriting
+silently, the installer compares each skill's own `version` against what is installed,
+prints the diff, and asks before touching anything:
+
+```
+@linchpinagency/skills v0.2.0 — Claude Code
+
+  task-tracking        v1.3.0 -> v1.4.0   update
+  agent-capabilities            -> v1.0.0   new
+  quality-gates        v1.0.0             local edits will be lost
+  (20 unchanged)
+
+3 change(s): 1 update, 1 new, 1 modified
+
+Apply? [y/N]
+```
+
+A run with nothing to change says so and exits without prompting, so re-running is cheap
+and safe. `--dry-run` shows the diff and writes nothing; `--yes` skips the prompt;
+`--force` reinstalls everything regardless.
+
+> A **non-interactive** run — piped stdin, CI, a script — proceeds without prompting, so
+> existing automation keeps working. Use `--dry-run` when you want a preview rather than an
+> install.
+
+Three statuses are worth knowing:
+
+- **local edits will be lost** — the installed copy was hand-edited. Skills are owned by
+  this package; change them here and re-install rather than editing an install in place.
+- **DOWNGRADE** — the package you invoked is *older* than what is installed. Usually a
+  pinned `npx @linchpinagency/skills@0.1.1` you meant to drop.
+- **new** — the skill did not exist in your installed version.
 
 ### Keeping skills current
 
@@ -231,6 +265,34 @@ skips itself whenever `CI` is set.
 A project that wants skills in more than one agent's directory should run
 `--agent all` rather than copying directories around by hand.
 
+### One scope per skill
+
+Agents load **every** skills directory they find and **do not dedupe by name**. A skill
+installed both globally and in a project is listed twice, and its `description` is loaded
+twice in every session before any work starts.
+
+So the installer refuses to create the second copy:
+
+```
+Refusing to install: 22 of these skills are already installed at another scope.
+```
+
+It reports which directory, what would be duplicated, and the command to remove just the
+overlapping skills — never the whole directory, which usually holds skills from other
+sources too. `--force` overrides it for the rare case where you want both.
+
+```bash
+npx @linchpinagency/skills --check                  # audit; exits 1 if duplicates exist
+npx @linchpinagency/skills --check --agent codex    # a different agent's directories
+```
+
+`--check` also catches the accident that is easiest to miss: an install in a *parent* of the
+repo (running the installer from `~/GitHub` rather than inside a checkout), which shadows
+nothing and duplicates everything below it.
+
+Choosing a scope, the MCP-server equivalent of the same problem, and how to record the
+decision are covered by [`agent-capabilities`](skills/agent-capabilities/SKILL.md).
+
 > Skills are loaded by the **agent/harness**, not the model — so "Copilot running Claude"
 > still needs the skill installed in Copilot's own directory. The installer handles that.
 
@@ -251,6 +313,7 @@ A project that wants skills in more than one agent's directory should run
 | `wp-implementation-choice` | WordPress | Decide what a request should become — theme work, content, a custom block, a functionality plugin, or an existing plugin — before any code is written. |
 | `design-previews` | Design | Generate three genuinely different visual directions as self-contained HTML previews, screenshot them at desktop and mobile via the Chrome DevTools MCP (or Playwright), and get a pick before theme or block work starts. |
 | `project-context` | Workflow | Orient before acting — repo shape, local environment, host, ClickUp space, and release model, read from the project's own config rather than assumed. Referenced by other skills' Preflight. |
+| `agent-capabilities` | Workflow | Right-size what a project loads — audit skill installs for cross-scope duplicates (`--check`), decide which MCP servers the repo actually needs, and scope them so every session stops paying for all of them. |
 | `quality-gates` | Workflow | Run a project's own lint, PHPCS, PHPStan, and test gates before committing — detected from `composer.json`, `package.json`, `phpcs.xml.dist`, and `lint-staged`, never assumed. |
 | `web-qa` | Workflow | QA like a real user and fix what you find — front end, wp-admin, and block editor, with severity, evidence, one atomic commit per fix, and a report-only mode. |
 | `investigate` | Workflow | Root-cause a bug before changing anything — reproduce, read the real error, isolate the layer, explain the mechanism, with WordPress first checks. |
@@ -259,8 +322,8 @@ A project that wants skills in more than one agent's directory should run
 | `engagement-types` | Project mgmt | Tell support, site maintenance, projects, product/plugin work, and pre-sales apart — each lives somewhere different in ClickUp and is planned and closed differently. |
 | `support-triage` | Project mgmt | Run a client support request end to end — clarify the real need, reproduce, judge urgency and scope, fix in the right layer, verify, and close the loop with the requester. |
 | `dependency-updates` | Workflow | Handle the dependency work Renovate can't automerge — majors, breaking changes, failing or conflicted bot PRs, security advisories, `@wordpress/*` package sets. |
-| `commit-and-release` | Workflow | Write commits, branches, and PR titles that satisfy the repo's own commitlint rules, and stay out of release-please's way (it owns versions and `CHANGELOG.md`). |
-| `task-tracking` | Workflow | Tie every unit of work to a ClickUp task (or explicit `NO-TASK`) with minimal friction via the ClickUp MCP — resolve/search a task, create one on request ("create an issue" means ClickUp, not GitHub), update it when the work lands, and carry the task key in the conventional-commit scope. |
+| `commit-and-release` | Workflow | Write commit messages and PR titles that satisfy the repo's own commitlint rules, and stay out of release-please's way (it owns versions and `CHANGELOG.md`). Branch naming lives in `task-tracking`. |
+| `task-tracking` | Workflow | Tie every unit of work to a ClickUp task (or explicit `NO-TASK`) with minimal friction via the ClickUp MCP — resolve/search a task, create one on request ("create an issue" means ClickUp, not GitHub), split work that spans sessions or PRs into parent + subtasks, name the branch, update the task when the work lands, and carry the task key in the commit scope. |
 | `write-a-linchpin-skill` | Meta | The house standard for authoring skills in this library — placement test, tier model, required frontmatter, the section skeleton, and the four house rules. Enforced by `scripts/validate-skills.mjs`. |
 
 _(More WordPress, React, Cloudflare Workers, marketing, and design skills to come.)_

package/bin/install.mjs

@@ -9,6 +9,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -40,13 +42,28 @@ function resolveAgents(id) {
 }
 
 function parseArgs(argv) {
-  const opts = { agent: 'claude-code', global: false, list: false, help: false, skipUpstream: false, skills: [] };
+  const opts = {
+    agent: 'claude-code',
+    global: false,
+    list: false,
+    help: false,
+    skipUpstream: false,
+    force: false,
+    check: false,
+    yes: false,
+    dryRun: false,
+    skills: [],
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--global' || a === '-g') opts.global = true;
     else if (a === '--list' || a === '-l') opts.list = true;
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--skip-upstream') opts.skipUpstream = true;
+    else if (a === '--force' || a === '-f') opts.force = true;
+    else if (a === '--check') opts.check = true;
+    else if (a === '--yes' || a === '-y') opts.yes = true;
+    else if (a === '--dry-run' || a === '-n') opts.dryRun = true;
     else if (a === '--agent') opts.agent = argv[++i];
     else if (a.startsWith('--agent=')) opts.agent = a.slice('--agent='.length);
     else if (a.startsWith('-')) {
@@ -78,6 +95,206 @@ function availableSkills() {
     .sort();
 }
 
+// --- Scope collisions ----------------------------------------------------------------
+// Agents load every skills directory they can see and do NOT dedupe by name. The same
+// skill installed at two scopes is therefore listed twice and its `description` is paid
+// for twice in the context window, every session, before any work starts. Installing on
+// top of an install at another scope is always waste, never a merge — so we stop.
+
+function installedSkillsIn(dir) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readStamp(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, STAMP_DIR, STAMP_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Every directory the selected agents also read, other than the ones we're about to write:
+// the opposite scope, plus any project-scope dir in a parent directory. That last case is
+// the one people hit by accident — running the installer from a checkouts folder like
+// ~/GitHub instead of inside a repo seeds a directory that shadows nothing and duplicates
+// everything.
+function rivalDirs(agentIds, opts) {
+  const home = os.homedir();
+  const seen = new Set();
+  const out = [];
+  const add = (dir, scope) => {
+    const resolved = path.resolve(dir);
+    if (seen.has(resolved)) return;
+    seen.add(resolved);
+    out.push({ dir: resolved, scope });
+  };
+
+  for (const id of agentIds) {
+    const opposite = opts.global ? AGENTS[id].project : AGENTS[id].global;
+    const oppositeRoot = opts.global ? process.cwd() : home;
+    for (const rel of opposite) add(path.join(oppositeRoot, rel), opts.global ? 'project' : 'global');
+
+    // Walk up to, but not into, home — home is the global scope, already covered above.
+    let cur = path.dirname(process.cwd());
+    while (cur.startsWith(home + path.sep)) {
+      for (const rel of AGENTS[id].project) add(path.join(cur, rel), 'ancestor');
+      const next = path.dirname(cur);
+      if (next === cur) break;
+      cur = next;
+    }
+  }
+  return out;
+}
+
+function findCollisions(agentIds, opts, wanted, targetDirs) {
+  const mine = new Set(targetDirs.map((d) => path.resolve(d)));
+  const want = new Set(wanted);
+  return rivalDirs(agentIds, opts)
+    .filter((r) => !mine.has(r.dir))
+    .map((r) => {
+      const present = installedSkillsIn(r.dir);
+      return { ...r, present, overlap: present.filter((n) => want.has(n)), stamp: readStamp(r.dir) };
+    })
+    .filter((r) => r.present.length);
+}
+
+function stampLine(stamp) {
+  if (!stamp) return 'no install stamp — copied by hand, or by a pre-0.2 installer';
+  return `v${stamp.version}, ${stamp.scope} scope, installed ${String(stamp.installedAt).slice(0, 10)}`;
+}
+
+const SCOPE_HINT = {
+  global: 'the user-global directory — loaded in every project',
+  project: 'a project directory — loaded when working in that repo',
+  ancestor: 'a parent of the current directory — almost certainly an installer run from the wrong folder',
+};
+
+// --- Update planning -----------------------------------------------------------------
+// Re-running the installer is the update path, so a re-run should say what it is about to
+// change before it changes it. Skills carry their own `version` in frontmatter, so the diff
+// is per skill rather than per package — a release usually touches two or three of them.
+
+function readSkillVersion(skillDir) {
+  try {
+    const md = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+    const fm = md.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) return null;
+    const v = fm[1].match(/^version:\s*(.*)$/m);
+    return v ? v[1].replace(/^["']|["']$/g, '').trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Content fingerprint over every file in the skill, so we can tell "same version, edited
+// in place" from "same version, untouched". Hand-edits in a consuming project get silently
+// overwritten by an install; the least we can do is name them first.
+function hashSkillDir(dir) {
+  const h = crypto.createHash('sha1');
+  const walk = (cur, rel) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const next = path.join(cur, e.name);
+      const nextRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(next, nextRel);
+      else {
+        h.update(nextRel);
+        h.update('\0');
+        try {
+          h.update(fs.readFileSync(next));
+        } catch {
+          /* unreadable file — its absence from the hash is itself a difference */
+        }
+      }
+    }
+  };
+  walk(dir, '');
+  return h.digest('hex');
+}
+
+function compareSemver(a, b) {
+  if (!a || !b) return null;
+  const pa = String(a).split('.').map((n) => parseInt(n, 10));
+  const pb = String(b).split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// What installing `wanted` into `base` would actually do, per skill.
+function planFor(base, wanted) {
+  return wanted.map((name) => {
+    const src = path.join(SKILLS_ROOT, name);
+    const dest = path.join(base, name);
+    const to = readSkillVersion(src);
+    if (!fs.existsSync(path.join(dest, 'SKILL.md'))) return { name, from: null, to, status: 'new' };
+
+    const from = readSkillVersion(dest);
+    const cmp = compareSemver(from, to);
+    if (cmp === -1) return { name, from, to, status: 'update' };
+    if (cmp === 1) return { name, from, to, status: 'downgrade' };
+    if (hashSkillDir(src) !== hashSkillDir(dest)) return { name, from, to, status: 'modified' };
+    return { name, from, to, status: 'unchanged' };
+  });
+}
+
+const PLAN_LABEL = {
+  new: 'new',
+  update: 'update',
+  downgrade: 'DOWNGRADE',
+  modified: 'local edits will be lost',
+  unchanged: 'unchanged',
+};
+
+function renderPlan(plan) {
+  const shown = plan.filter((p) => p.status !== 'unchanged');
+  const width = Math.max(0, ...shown.map((p) => p.name.length));
+  for (const p of shown) {
+    const ver =
+      p.status === 'new'
+        ? `        -> v${p.to}`
+        : p.from === p.to
+          ? `   v${p.from}`
+          : `   v${p.from} -> v${p.to}`;
+    console.log(`  ${p.name.padEnd(width)}${ver}   ${PLAN_LABEL[p.status]}`);
+  }
+  const same = plan.length - shown.length;
+  if (same) console.log(`  (${same} unchanged)`);
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      rl.close();
+      resolve(value);
+    };
+    // Ctrl-D or a closed stdin resolves as "no" — without this the promise never settles
+    // and the installer exits silently having done nothing.
+    rl.on('close', () => finish(false));
+    rl.question(question, (answer) => finish(/^y(es)?$/i.test(answer.trim())));
+  });
+}
+
 function readUpstreamManifest() {
   try {
     const m = JSON.parse(fs.readFileSync(UPSTREAM_MANIFEST, 'utf8'));
@@ -199,15 +416,35 @@ Arguments:
 
 Options:
   -l, --list        List available skills (Linchpin + pinned base layer) and exit
+      --check       Audit every scope this agent reads for duplicate skills; install nothing
   -g, --global      Install to the user-global skills dir instead of the project
       --agent <id>  Target agent: claude-code (default) | github-copilot | codex | cursor
                     | all  (installs into every agent's directory)
       --skip-upstream  Install only Linchpin skills; don't vendor the upstream base layer
+  -f, --force       Reinstall everything, and install even if these skills already exist
+                    at another scope
+  -y, --yes         Skip the confirmation prompt (implied when not a TTY)
+  -n, --dry-run     Show what would change and exit without writing anything
   -h, --help        Show this help
 
+Updating:
+  Re-running is the update path. The installer compares each skill's version against what
+  is installed, prints what would change, and asks before touching anything. A run with
+  nothing to change exits early. --dry-run shows the diff and writes nothing; note that a
+  non-interactive run (piped stdin, CI) proceeds without prompting.
+
+Scopes:
+  Agents load every skills directory they find and do not dedupe by name, so a skill
+  installed both globally and in a project is listed twice and costs its description
+  twice in every session. Installing over another scope aborts unless you pass --force.
+  Use --check to see what is already installed where.
+
 Examples:
   npx @linchpinagency/skills                    # Linchpin skills + base layer -> ./.claude/skills
   npx @linchpinagency/skills wp-studio-cli      # one Linchpin skill (+ base layer)
+  npx @linchpinagency/skills --check            # audit scopes, install nothing
+  npx @linchpinagency/skills --dry-run          # preview an update, write nothing
+  npx @linchpinagency/skills --yes              # update without the confirmation prompt
   npx @linchpinagency/skills --skip-upstream    # Linchpin skills only
   npx @linchpinagency/skills --agent github-copilot
   npx @linchpinagency/skills --agent all        # every agent dir in this project
@@ -263,16 +500,150 @@ async function main() {
   }
   if (!wanted.length && !sources.length) return console.log('No skills to install.');
 
+  const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
+
+  if (opts.check) {
+    // An audit reports what is actually installed, not just what this package ships —
+    // duplicates seeded by an older version or another library still cost context.
+    const installedHere = new Set(targets.flatMap((t) => installedSkillsIn(t.dir)));
+    const audit = findCollisions(agentIds, opts, [...installedHere], bases);
+    console.log(`Skill directories ${labels} reads, for this project:\n`);
+    for (const t of targets) {
+      const have = installedSkillsIn(t.dir);
+      console.log(`  [target]  ${t.dir}`);
+      console.log(`            ${have.length} skill(s) — ${stampLine(readStamp(t.dir))}\n`);
+    }
+    for (const c of audit) {
+      console.log(`  [${c.scope}] ${c.dir}`);
+      console.log(`            ${c.present.length} skill(s) — ${stampLine(c.stamp)}`);
+      console.log(`            ${SCOPE_HINT[c.scope]}`);
+      if (c.overlap.length) console.log(`            ${c.overlap.length} duplicate(s): ${c.overlap.join(', ')}`);
+      console.log();
+    }
+    const dupes = audit.reduce((n, c) => n + c.overlap.length, 0);
+    if (!dupes) {
+      console.log('No duplicate skills across scopes.');
+      return;
+    }
+    console.log(`${dupes} duplicate skill copies across scopes. Each one's description is loaded`);
+    console.log('once per copy, every session. Remove whichever copy you do not want.');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Plan first: whether a collision is a problem depends on whether this run would be
+  // *creating* the second copy or merely maintaining one that already exists.
+  const version = packageVersion();
+  const plans = targets.map((t) => ({ target: t, plan: planFor(t.dir, wanted) }));
+  const changed = plans.flatMap((p) => p.plan).filter((p) => p.status !== 'unchanged');
+
+  // A skill that is 'new' in every target but already present at another scope is a
+  // duplicate about to be born — that we refuse. A skill already installed here is an
+  // update; refusing it would only strand someone on a stale copy without removing the
+  // duplication, so it warns instead.
+  const arriving = new Set(
+    plans.flatMap(({ plan }) => plan.filter((p) => p.status === 'new').map((p) => p.name))
+  );
+  const existing = new Set(
+    plans.flatMap(({ plan }) => plan.filter((p) => p.status !== 'new').map((p) => p.name))
+  );
+  const collisions = findCollisions(agentIds, opts, wanted, bases);
+  const wouldCreate = collisions
+    .map((c) => ({ ...c, overlap: c.overlap.filter((n) => arriving.has(n) && !existing.has(n)) }))
+    .filter((c) => c.overlap.length);
+  const preExisting = collisions
+    .map((c) => ({ ...c, overlap: c.overlap.filter((n) => existing.has(n)) }))
+    .filter((c) => c.overlap.length);
+
+  if (wouldCreate.length && !opts.force) {
+    const dupes = wouldCreate.reduce((n, c) => n + c.overlap.length, 0);
+    console.error(`Refusing to install: ${dupes} of these skills are already installed at another scope.\n`);
+    for (const c of wouldCreate) {
+      console.error(`  ${c.dir}`);
+      console.error(`    ${SCOPE_HINT[c.scope]}`);
+      console.error(`    ${stampLine(c.stamp)}`);
+      console.error(`    would duplicate: ${c.overlap.join(', ')}\n`);
+    }
+    console.error(`${labels} loads every directory it finds and does not dedupe by name, so each`);
+    console.error('duplicate is listed twice and costs its description twice in every session.\n');
+    console.error('Pick one scope:');
+    console.error('  - keep the existing copy — nothing to do here; this install would be redundant');
+    console.error('  - move them here         — drop just the duplicates at the other scope, then re-run:');
+    for (const c of wouldCreate) {
+      console.error(`      (cd ${c.dir} && rm -rf ${c.overlap.join(' ')})`);
+    }
+    console.error('  - keep both anyway       — re-run with --force');
+    console.error('\nRun with --check to audit every scope without installing.');
+    process.exit(1);
+  }
+
+  if (preExisting.length) {
+    const dupes = preExisting.reduce((n, c) => n + c.overlap.length, 0);
+    console.log(`! ${dupes} of these skills are also installed at another scope, and were before this run:`);
+    for (const c of preExisting) console.log(`    ${c.dir}  (${c.scope})`);
+    console.log('  Updating here does not fix that. Run --check for the duplicates and how to drop them.\n');
+  }
+
+  // A re-run is the update path, so most runs land here with a handful of skills to
+  // update and the rest already current.
+  if (!changed.length && !opts.force) {
+    console.log(`Already up to date — ${wanted.length} skill(s) for ${labels}, nothing to change.`);
+    if (!opts.dryRun) console.log('Re-run with --force to reinstall anyway.');
+    return;
+  }
+
+  if (changed.length) {
+    console.log(`@linchpinagency/skills v${version} — ${labels}\n`);
+    for (const { target, plan } of plans) {
+      if (plans.length > 1) console.log(`${target.dir}`);
+      renderPlan(plan);
+      if (plans.length > 1) console.log();
+    }
+
+    const edited = changed.filter((p) => p.status === 'modified');
+    if (edited.length) {
+      console.log(`\n! ${edited.length} skill(s) were edited in place and will be overwritten.`);
+      console.log('  Skills are owned by this package — change them in the library, not the install.');
+    }
+    const down = changed.filter((p) => p.status === 'downgrade');
+    if (down.length) {
+      console.log(`\n! ${down.length} skill(s) would go BACKWARDS — this package is older than what is installed.`);
+      console.log('  Check the version you invoked before continuing.');
+    }
+
+    const counts = ['new', 'update', 'downgrade', 'modified']
+      .map((k) => [k, changed.filter((p) => p.status === k).length])
+      .filter(([, n]) => n)
+      .map(([k, n]) => `${n} ${k}`)
+      .join(', ');
+    console.log(`\n${changed.length} change(s): ${counts}`);
+
+    if (opts.dryRun) {
+      console.log('\nDry run — nothing was written.');
+      return;
+    }
+
+    if (!opts.yes && !opts.force) {
+      if (!process.stdin.isTTY) {
+        console.log('Non-interactive — proceeding. Pass --yes to silence this notice.');
+      } else if (!(await confirm('\nApply? [y/N] '))) {
+        console.log('Nothing changed.');
+        return;
+      }
+    }
+    console.log();
+  }
+
+  const applied = new Set(changed.map((p) => p.name));
   for (const base of bases) {
     fs.mkdirSync(base, { recursive: true });
     for (const name of wanted) {
       const dest = path.join(base, name);
       fs.rmSync(dest, { recursive: true, force: true });
       fs.cpSync(path.join(SKILLS_ROOT, name), dest, { recursive: true });
-      console.log(`✓ ${name} -> ${dest}`);
+      if (applied.has(name) || opts.force) console.log(`✓ ${name} -> ${dest}`);
     }
   }
-  const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
   console.log(`\nInstalled ${wanted.length} Linchpin skill(s) for ${labels}.`);
 
   const upstream = [];
@@ -286,7 +657,6 @@ async function main() {
   }
 
   // Stamp last, so `upstream` reflects what actually landed rather than what was intended.
-  const version = packageVersion();
   const stamped = targets.filter((t) => writeStamp(t, { version, opts, skills: wanted, upstream }));
   if (stamped.length && agentIds.includes('claude-code')) {
     const rel = path.join(STAMP_DIR, CHECKER);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {