@chankov/agent-skills 0.1.0 → 0.2.0

package/.versions/0.2.0/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   └── Need doc-verified code? ───→ source-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    ├── Authoring a new skill/persona? ─→ designing-agents
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1. idea-refine                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. source-driven-development   → Verify against official docs
+6. incremental-implementation  → Build slice by slice
+7. test-driven-development     → Prove each slice works
+8. code-review-and-quality     → Review before merge
+9. git-workflow-and-versioning → Clean commit history
+10. documentation-and-adrs     → Document decisions
+11. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | source-driven-development | Verify against official docs before implementing |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |
+| Author | designing-agents | Author a persona, workflow skill, or pi harness |

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # agent-skills changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 7f2be04: Initial npm release. Ships the full skills catalog, agent personas, slash
+  commands, and pi extensions as an installable package, with a thin CLI
+  (`npx agent-skills init`) that hands off to the LLM-driven
+  `guided-workspace-setup` skill. Adds version-aware updates: the install record
+  now embeds the package version, and re-running `/setup` after a version bump
+  surfaces a per-artifact three-way diff (source@recorded vs installed copy vs
+  source@current) before touching any file.
+- Add three layered update-notification paths so users are told when a newer
+  version is published, without having to remember to check:
+
+  1. **CLI update-notifier** (`bin/lib/update-notifier.js`) — every
+     `npx @chankov/agent-skills <cmd>` reads a shared 24h cache; if the cached
+     latest exceeds the running CLI version, a banner prints to stderr. Stale
+     caches are refreshed by a detached background process so the current run
+     is never blocked.
+  2. **`check-update` CLI subcommand** — standalone entry point used by hooks
+     and extensions; blocks on a single registry fetch (2s timeout) and prints
+     the banner to stdout if outdated. Always exits 0.
+  3. **Claude Code session-start hook** (`hooks/session-start.sh`) — extended
+     to call `check-update` with a 3s wall-clock cap and inject the banner into
+     the session context so Claude can surface it on its first turn.
+  4. **pi extension** (`.pi/extensions/agent-skills-update-check/`) — fires on
+     the first `agent_start` event of each pi session, reads the same shared
+     cache, emits `ctx.ui.notify` if outdated. Offered as a `★`-recommended
+     pick in install-menu Group 10.
+
+  All three share the cache at `$XDG_CACHE_HOME/agent-skills/latest-version.json`
+  so the registry is hit at most once per 24h window across all runtimes.
+
+  Opt-out via any of `AGENT_SKILLS_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`,
+  or `CI=true`.
+
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries below 0.1.0

package/bin/cli.js

@@ -21,6 +21,7 @@ import { stdin, stdout, exit } from "node:process";
 
 import { runDoctor } from "./lib/doctor.js";
 import { detectAgent, agentLabel, AGENTS } from "./lib/detect-agent.js";
+import { checkAndNotify } from "./lib/update-notifier.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, "..");
@@ -70,11 +71,20 @@ if (opts.help) {
 
 // ── dispatch ──────────────────────────────────────────────────────────────
 
+// Update check runs first — if the cache is fresh and shows an upgrade,
+// the banner prints to stderr before the command output. If the cache is
+// stale, a background fetch refreshes it for the next invocation.
+// `update` skips this since it has its own version-delta reporting.
+if (sub !== "update" && sub !== "check-update") {
+  checkAndNotify(pkg.version);
+}
+
 switch (sub) {
-  case "init":    await cmdInit();    break;
-  case "doctor":  await cmdDoctor();  break;
-  case "update":  await cmdUpdate();  break;
-  default:        fail(`unknown command: ${sub}\n\nRun "agent-skills --help" for usage.`);
+  case "init":          await cmdInit();        break;
+  case "doctor":        await cmdDoctor();      break;
+  case "update":        await cmdUpdate();      break;
+  case "check-update":  await cmdCheckUpdate(); break;
+  default:              fail(`unknown command: ${sub}\n\nRun "agent-skills --help" for usage.`);
 }
 
 // ── commands ──────────────────────────────────────────────────────────────
@@ -190,6 +200,25 @@ async function cmdUpdate() {
   console.log("touching any file.");
 }
 
+async function cmdCheckUpdate() {
+  // Entry point for hook scripts and pi extensions. Blocks on a single
+  // registry fetch (short timeout); emits a one-line banner to stdout if an
+  // upgrade is available, otherwise prints nothing. Always exits 0 so a
+  // failed check never breaks the calling hook.
+  const { fetchLatestSync, readCacheStatus, formatBanner, gt } =
+    await import("./lib/update-notifier.js");
+
+  let latest = readCacheStatus();
+  if (!latest || latest.stale) {
+    const fetched = await fetchLatestSync(2000);
+    if (fetched) latest = { latest: fetched };
+  }
+  if (latest?.latest && gt(latest.latest, pkg.version)) {
+    process.stdout.write(formatBanner(pkg.version, latest.latest) + "\n");
+  }
+  exit(0);
+}
+
 // ── helpers ───────────────────────────────────────────────────────────────
 
 async function chooseAgent(supplied) {
@@ -356,9 +385,10 @@ Usage:
   npx agent-skills <command> [options]
 
 Commands:
-  init       Materialize the package + hand off to /setup in your agent
-  doctor     Scan for broken symlinks and stale persona references
-  update     Surface the version delta + hand off to /setup for the refresh
+  init           Materialize the package + hand off to /setup in your agent
+  doctor         Scan for broken symlinks and stale persona references
+  update         Surface the version delta + hand off to /setup for the refresh
+  check-update   One-line registry check (used by session hooks; safe to script)
 
 Options:
   -v, --version    Print the package version
@@ -370,6 +400,11 @@ Examples:
   npx agent-skills doctor --workspace ~/projects/foo
   npx agent-skills update
 
+Environment:
+  AGENT_SKILLS_NO_UPDATE_CHECK=1   Disable the background update check
+  NO_UPDATE_NOTIFIER=1             Same (conventional opt-out, also honoured)
+  CI=true                          Auto-disables the update check
+
 Docs: https://github.com/chankov/agent-skills#readme
 `);
 }

package/bin/lib/update-notifier.js

@@ -0,0 +1,195 @@
+// update-notifier — zero-dependency check for newer versions on the npm
+// registry, shared by the CLI, the Claude Code session hook, and the pi
+// extension.
+//
+// Behaviour:
+//   - Cache lives at $XDG_CACHE_HOME/agent-skills/latest-version.json
+//     (falls back to ~/.cache/agent-skills/) with a 24h TTL.
+//   - The CLI invokes checkAndNotify() at the top of every command. If the
+//     cache is fresh and shows an upgrade, we print a banner immediately.
+//     If the cache is stale or absent, we start a background fetch (detached,
+//     non-blocking) and use whatever we have right now.
+//   - Network failures, JSON parse errors, and missing cache files are all
+//     swallowed silently — update checks must NEVER block the CLI or break
+//     a hook.
+//   - Opt-out: AGENT_SKILLS_NO_UPDATE_CHECK=1 in the environment disables
+//     everything in this module.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { request } from "node:https";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "@chankov/agent-skills";
+const REGISTRY = "https://registry.npmjs.org";
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+const CACHE_DIR = join(
+  process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
+  "agent-skills",
+);
+const CACHE_FILE = join(CACHE_DIR, "latest-version.json");
+
+// ── Public surface ───────────────────────────────────────────────────────
+
+/**
+ * Run the standard check + banner flow used by the CLI.
+ *
+ * @param {string} currentVersion  The version of the running CLI
+ * @param {object} [opts]
+ * @param {boolean} [opts.silent]  If true, return the banner string instead of printing
+ * @returns {string|null}  The banner that would be (or was) printed
+ */
+export function checkAndNotify(currentVersion, opts = {}) {
+  if (isDisabled()) return null;
+
+  const cached = readCache();
+  const fresh = cached && Date.now() - cached.checkedAt < TTL_MS;
+
+  if (!fresh) startBackgroundFetch();
+
+  const latest = cached?.latest;
+  if (!latest || !gt(latest, currentVersion)) return null;
+
+  const banner = formatBanner(currentVersion, latest);
+  if (!opts.silent) process.stderr.write(banner + "\n");
+  return banner;
+}
+
+/**
+ * Synchronously fetch the latest version, write the cache, and return it.
+ * Used by the standalone check-update entry point (hooks block on this
+ * intentionally — they need the answer before the session continues).
+ *
+ * @param {number} [timeoutMs]   Default 2000ms — hooks must not stall the UI
+ * @returns {Promise<string|null>}
+ */
+export async function fetchLatestSync(timeoutMs = 2000) {
+  if (isDisabled()) return null;
+  try {
+    const latest = await fetchLatest(timeoutMs);
+    writeCache({ latest, checkedAt: Date.now() });
+    return latest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the cached latest version without touching the network. Hook scripts
+ * use this on the fast path — if the cache is fresh, no fetch is needed.
+ *
+ * @returns {{latest:string, checkedAt:number, stale:boolean}|null}
+ */
+export function readCacheStatus() {
+  const c = readCache();
+  if (!c) return null;
+  return { ...c, stale: Date.now() - c.checkedAt >= TTL_MS };
+}
+
+export function formatBanner(current, latest) {
+  const lines = [
+    `agent-skills update available: ${current} → ${latest}`,
+    `  Run: npx ${PACKAGE_NAME}@latest update`,
+    `  Releases: https://github.com/chankov/agent-skills/releases`,
+  ];
+  const w = Math.max(...lines.map((l) => l.length)) + 2;
+  const bar = "─".repeat(w);
+  return [
+    `┌${bar}┐`,
+    ...lines.map((l) => `│ ${l.padEnd(w - 1)}│`),
+    `└${bar}┘`,
+  ].join("\n");
+}
+
+// ── Internals ────────────────────────────────────────────────────────────
+
+function isDisabled() {
+  return process.env.AGENT_SKILLS_NO_UPDATE_CHECK === "1"
+      || process.env.CI === "true"   // never spam CI logs
+      || process.env.NO_UPDATE_NOTIFIER === "1";  // honour the common convention
+}
+
+function readCache() {
+  try {
+    if (!existsSync(CACHE_FILE)) return null;
+    return JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2), "utf8");
+  } catch {
+    // Read-only home dir, full disk, etc. — caching is best-effort.
+  }
+}
+
+function fetchLatest(timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME).replace("%40", "@")}/latest`;
+    const req = request(url, { method: "GET", headers: { accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`registry returned ${res.statusCode}`));
+        res.resume();
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (typeof parsed.version !== "string") throw new Error("missing version field");
+          resolve(parsed.version);
+        } catch (err) { reject(err); }
+      });
+    });
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error("timeout"));
+    });
+    req.end();
+  });
+}
+
+function startBackgroundFetch() {
+  // Detached worker: never blocks the CLI, never inherits stdio.
+  // We re-enter this module via dynamic import in a fresh node process and
+  // run fetchLatestSync there — keeps the parent CLI exit unaffected.
+  try {
+    const modPath = fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [
+      "-e",
+      `import(${JSON.stringify(modPath)}).then(m => m.fetchLatestSync(8000)).catch(() => {})`,
+    ], { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {
+    // If spawn fails (e.g. restricted env), skip — the next CLI run will retry.
+  }
+}
+
+// ── Tiny semver-gt comparator ────────────────────────────────────────────
+// Enough for X.Y.Z comparisons; anything pre-release falls back to string
+// compare on the suffix, which is good enough for "is the user behind?"
+
+export function gt(a, b) {
+  const [aMain, aPre = ""] = a.split("-", 2);
+  const [bMain, bPre = ""] = b.split("-", 2);
+  const aParts = aMain.split(".").map(Number);
+  const bParts = bMain.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const ai = aParts[i] ?? 0;
+    const bi = bParts[i] ?? 0;
+    if (ai !== bi) return ai > bi;
+  }
+  // Equal main versions: a release (no prerelease) outranks a prerelease.
+  if (!aPre && bPre) return true;
+  if (aPre && !bPre) return false;
+  return aPre > bPre;
+}

package/docs/npm-install.md

@@ -156,6 +156,66 @@ npx --yes @chankov/agent-skills@latest init --agent claude-code --method copy --
 LLM-driven `/setup` flow is not CI-runnable by design — confirmation gates
 exist precisely so a human approves every write.
 
+## Receiving update notifications
+
+Three independent mechanisms surface "a new version is published" without
+you having to remember to check. All three share a single cache at
+`$XDG_CACHE_HOME/agent-skills/latest-version.json` (24h TTL) so the
+registry is hit at most once per day.
+
+### 1. CLI update-notifier (always on)
+
+Every `npx @chankov/agent-skills <cmd>` invocation runs a fast cache read
+on entry. If the cached latest version exceeds the running CLI version, a
+banner prints to stderr before the command output:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ agent-skills update available: 0.1.0 → 0.2.0                 │
+│   Run: npx @chankov/agent-skills@latest update               │
+│   Releases: https://github.com/chankov/agent-skills/releases │
+└──────────────────────────────────────────────────────────────┘
+```
+
+If the cache is stale, a detached background process refreshes it for the
+*next* invocation — the current run is never blocked.
+
+### 2. Claude Code session-start hook
+
+When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup`),
+every new Claude Code session runs the check with a 3-second wall-clock cap.
+If an upgrade is available, the banner is injected into the session context
+so Claude can mention it on its first turn — e.g. *"Note: agent-skills 0.2.0
+is available; want me to apply it via `/setup`?"*
+
+### 3. pi extension (`agent-skills-update-check`)
+
+When installed (offered in Group 10 of `/setup`), the extension fires on the
+first `agent_start` event of each pi session and emits a `ctx.ui.notify`
+message in the pi UI if a newer version is published. Reads the same cache
+as the CLI — no double-fetching.
+
+### Opting out
+
+Any of these environment variables disables all three:
+
+```bash
+export AGENT_SKILLS_NO_UPDATE_CHECK=1   # agent-skills-specific
+export NO_UPDATE_NOTIFIER=1             # conventional, also honoured
+# CI=true is auto-detected — banners never appear in CI logs
+```
+
+### Forcing a manual check
+
+```bash
+# Block on a single registry fetch; print the banner if outdated
+npx @chankov/agent-skills check-update
+
+# Bypass the cache entirely
+rm ~/.cache/agent-skills/latest-version.json
+npx @chankov/agent-skills check-update
+```
+
 ## Troubleshooting
 
 - **"Could not auto-detect your coding agent."** Pass `--agent` or run

package/hooks/session-start.sh

@@ -1,20 +1,74 @@
 #!/bin/bash
-# agent-skills session start hook
-# Injects the using-agent-skills meta-skill into every new session
+# agent-skills session start hook (Claude Code).
+#
+# Two responsibilities:
+#   1. Inject the using-agent-skills meta-skill into the session context so
+#      Claude can route tasks to the right skill.
+#   2. Surface a one-line "update available" banner when the installed
+#      package is behind the published version on npm.
+#
+# Both are best-effort. Network errors, missing files, and missing tools
+# never block session start — the hook always exits 0 and prints a valid
+# JSON object on stdout.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-SKILLS_DIR="$(dirname "$SCRIPT_DIR")/skills"
+PACKAGE_ROOT="$(dirname "$SCRIPT_DIR")"
+SKILLS_DIR="$PACKAGE_ROOT/skills"
 META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"
+CHECK_SCRIPT="$PACKAGE_ROOT/bin/cli.js"
 
+# ── 1. Meta-skill content ────────────────────────────────────────────────
 if [ -f "$META_SKILL" ]; then
-  CONTENT=$(cat "$META_SKILL")
-  # Output as JSON for Claude Code hook consumption
-  cat <<EOF
-{
-  "priority": "IMPORTANT",
-  "message": "agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task.\n\n$CONTENT"
-}
-EOF
+  META_CONTENT=$(cat "$META_SKILL")
+  PRIORITY="IMPORTANT"
+  BASE_MESSAGE="agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task."
 else
-  echo '{"priority": "INFO", "message": "agent-skills: using-agent-skills meta-skill not found. Skills may still be available individually."}'
+  META_CONTENT=""
+  PRIORITY="INFO"
+  BASE_MESSAGE="agent-skills: using-agent-skills meta-skill not found. Skills may still be available individually."
+fi
+
+# ── 2. Update banner (silent on any error) ───────────────────────────────
+UPDATE_BANNER=""
+if [ "$AGENT_SKILLS_NO_UPDATE_CHECK" != "1" ] \
+   && [ "$NO_UPDATE_NOTIFIER" != "1" ] \
+   && [ "$CI" != "true" ] \
+   && command -v node >/dev/null 2>&1 \
+   && [ -f "$CHECK_SCRIPT" ]; then
+  # Run with a 3-second wall-clock cap so a hung registry never stalls the
+  # session. The check-update subcommand emits the banner on stdout when an
+  # upgrade is available, nothing otherwise. Errors go to /dev/null.
+  if command -v timeout >/dev/null 2>&1; then
+    UPDATE_BANNER=$(timeout 3 node "$CHECK_SCRIPT" check-update 2>/dev/null || true)
+  else
+    UPDATE_BANNER=$(node "$CHECK_SCRIPT" check-update 2>/dev/null || true)
+  fi
+fi
+
+# ── Compose the message ──────────────────────────────────────────────────
+FULL_MESSAGE="$BASE_MESSAGE"
+if [ -n "$UPDATE_BANNER" ]; then
+  FULL_MESSAGE=$(printf '%s\n\n%s' "$FULL_MESSAGE" "$UPDATE_BANNER")
+fi
+if [ -n "$META_CONTENT" ]; then
+  FULL_MESSAGE=$(printf '%s\n\n%s' "$FULL_MESSAGE" "$META_CONTENT")
+fi
+
+# ── Emit JSON (node handles escaping correctly) ──────────────────────────
+if command -v node >/dev/null 2>&1; then
+  printf '%s' "$FULL_MESSAGE" | node -e '
+    let msg = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => { msg += c; });
+    process.stdin.on("end", () => {
+      process.stdout.write(JSON.stringify({
+        priority: process.env.PRIORITY || "INFO",
+        message: msg,
+      }) + "\n");
+    });
+  '
+else
+  # Fallback: ship just the base message with minimal escaping.
+  SAFE_MSG=$(printf '%s' "$BASE_MESSAGE" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"priority": "%s", "message": "%s"}\n' "$PRIORITY" "$SAFE_MSG"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chankov/agent-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Production-grade engineering skills for AI coding agents. Ships skills, agent personas, slash commands, and pi extensions, with a thin CLI that hands off to the LLM-driven guided setup.",
   "keywords": [
     "ai",

package/skills/guided-workspace-setup/SKILL.md

@@ -168,7 +168,7 @@ Groups, in order:
 7. **Agent personas — writeable** — `builder`, `documenter`
 8. **Agent personas — read-only** (carry `tools: read,bash,grep,find,ls` and an explicit "Do NOT modify files." rule) — `code-reviewer` ★, `test-engineer` ★, `security-auditor`, `planner`, `plan-reviewer`, `scout`
 9. **Commands / prompts** (mapped to the chosen agent — items without a per-agent source are filtered out, no cross-tool substitution) — full candidate list: `spec` ★, `plan` ★, `build` ★, `test` ★, `review` ★, `code-simplify`, `ship`, `design-agent`, `prime`. The actual menu shows only items whose per-agent source file exists — for example, `.pi/prompts/design-agent.md` and `.pi/prompts/prime.md` are absent, so neither is offered when the agent is `pi`. *(`setup` and `doctor` are installer-only — never offered, since they live in the source agent-skills repo and act on target workspaces from there.)*
-10. **pi extensions** *(pi only — always-on once installed)* — `mcp-bridge`, `chrome-devtools-mcp`, `compact-and-continue`
+10. **pi extensions** *(pi only — always-on once installed)* — `mcp-bridge`, `chrome-devtools-mcp`, `compact-and-continue`, `agent-skills-update-check` ★
 11. **pi harnesses — UI / status** *(pi only, mutually exclusive at runtime — install many, load one)* — `minimal`, `tool-counter`, `tool-counter-widget`, `session-replay`, `subagent-widget`
 12. **pi harnesses — discipline / focus** *(pi only)* — `purpose-gate`, `tilldone`, `system-select`
 13. **pi harnesses — safety** *(pi only)* — `damage-control`, `damage-control-continue`