garrytan · garrytan · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.4.1] - 2026-03-18
+
+### Added
+
+- **Skills now discoverable via natural language.** All 12 skills that were missing explicit trigger phrases now have them — say "deploy this" and Claude finds `/ship`, say "check my diff" and it finds `/review`. Following Anthropic's best practice: "the description field is not a summary — it's when to trigger."
+- **On-demand hooks and telemetry captured in TODOS.md.** `/careful` (destructive command guardrails), `/freeze` (edit restriction), `/guard` (meta-skill), and skill usage telemetry — all scoped as P3 with implementation notes from eng review.
+
 ## [0.6.4.0] - 2026-03-17
 
 ### Added

diff --git a/TODOS.md b/TODOS.md
@@ -482,6 +482,37 @@ Shipped as `/design-consultation` on garrytan/design branch. Renamed from `/setu
 **Priority:** P3
 **Depends on:** Boil the Lake shipped (v0.6.1)
 
+## Safety & Observability
+
+### On-demand hook skills (/careful, /freeze, /guard)
+
+**What:** Three new skills that use Claude Code's session-scoped PreToolUse hooks to add safety guardrails on demand.
+
+**Why:** Anthropic's internal skill best practices recommend on-demand hooks for safety. Claude Code already handles destructive command permissions, but these add an explicit opt-in layer for high-risk sessions (touching prod, debugging live systems).
+
+**Skills:**
+- `/careful` — PreToolUse hook on Bash tool. Warns (not blocks) before destructive commands: `rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `kubectl delete`, `docker system prune`. Uses `permissionDecision: "ask"` so user can override.
+- `/freeze` — PreToolUse hook on Edit/Write tools. Restricts file edits to a user-specified directory. Great for debugging without accidentally "fixing" unrelated code.
+- `/guard` — meta-skill composing `/careful` + `/freeze` into one command.
+
+**Implementation notes:** Use `${CLAUDE_SKILL_DIR}` (not `${SKILL_DIR}`) for script paths in hook commands. Pure bash JSON parsing (no jq dependency). Freeze dir storage: `${CLAUDE_PLUGIN_DATA}/freeze-dir.txt` with `~/.gstack/freeze-dir.txt` fallback. Ensure trailing `/` on freeze dir paths to prevent `/src` matching `/src-old`.
+
+**Effort:** M (human) / S (CC)
+**Priority:** P3
+**Depends on:** None
+
+### Skill usage telemetry
+
+**What:** Track which skills get invoked, how often, from which repo.
+
+**Why:** Enables finding undertriggering skills and measuring adoption. Anthropic uses a PreToolUse hook for this; simpler approach is appending JSONL from the preamble.
+
+**Context:** Add to `generatePreamble()` in `scripts/gen-skill-docs.ts`. Append to `~/.gstack/analytics/skill-usage.jsonl` with skill name, timestamp, and repo name. `mkdir -p` ensures the directory exists.
+
+**Effort:** S (human) / S (CC)
+**Priority:** P3
+**Depends on:** None
+
 ## Completed
 
 ### Phase 1: Foundations (v0.2.0)

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.6.4.0
+0.6.4.1
diff --git a/browse/SKILL.md b/browse/SKILL.md
@@ -6,7 +6,8 @@ description: |
   elements, verify page state, diff before/after actions, take annotated screenshots, check
   responsive layouts, test forms and uploads, handle dialogs, and assert element states.
   ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
-  user flow, or file a bug with evidence.
+  user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
+  site", "take a screenshot", or "dogfood this".
 allowed-tools:
   - Bash
   - Read

diff --git a/browse/SKILL.md.tmpl b/browse/SKILL.md.tmpl
@@ -6,7 +6,8 @@ description: |
   elements, verify page state, diff before/after actions, take annotated screenshots, check
   responsive layouts, test forms and uploads, handle dialogs, and assert element states.
   ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
-  user flow, or file a bug with evidence.
+  user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
+  site", "take a screenshot", or "dogfood this".
 allowed-tools:
   - Bash
   - Read

diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md
@@ -6,6 +6,7 @@ description: |
   complete design system (aesthetic, typography, color, layout, spacing, motion), and
   generates font+color preview pages. Creates DESIGN.md as your project's design source
   of truth. For existing sites, use /plan-design-review to infer the system instead.
+  Use when asked to "design system", "brand guidelines", or "create DESIGN.md".
 allowed-tools:
   - Bash
   - Read

diff --git a/design-consultation/SKILL.md.tmpl b/design-consultation/SKILL.md.tmpl
@@ -6,6 +6,7 @@ description: |
   complete design system (aesthetic, typography, color, layout, spacing, motion), and
   generates font+color preview pages. Creates DESIGN.md as your project's design source
   of truth. For existing sites, use /plan-design-review to infer the system instead.
+  Use when asked to "design system", "brand guidelines", or "create DESIGN.md".
 allowed-tools:
   - Bash
   - Read

diff --git a/design-review/SKILL.md b/design-review/SKILL.md
@@ -6,6 +6,7 @@ description: |
   AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
   in source code, committing each fix atomically and re-verifying with before/after
   screenshots. For plan-mode design review (before implementation), use /plan-design-review.
+  Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
 allowed-tools:
   - Bash
   - Read

diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl
@@ -6,6 +6,7 @@ description: |
   AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
   in source code, committing each fix atomically and re-verifying with before/after
   screenshots. For plan-mode design review (before implementation), use /plan-design-review.
+  Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
 allowed-tools:
   - Bash
   - Read

diff --git a/document-release/SKILL.md b/document-release/SKILL.md
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Post-ship documentation update. Reads all project docs, cross-references the
   diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
-  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION.
+  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
+  asked to "update the docs", "sync documentation", or "post-ship docs".
 allowed-tools:
   - Bash
   - Read

diff --git a/document-release/SKILL.md.tmpl b/document-release/SKILL.md.tmpl
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Post-ship documentation update. Reads all project docs, cross-references the
   diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
-  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION.
+  polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
+  asked to "update the docs", "sync documentation", or "post-ship docs".
 allowed-tools:
   - Bash
   - Read

diff --git a/gstack-upgrade/SKILL.md b/gstack-upgrade/SKILL.md
@@ -3,7 +3,8 @@ name: gstack-upgrade
 version: 1.1.0
 description: |
   Upgrade gstack to the latest version. Detects global vs vendored install,
-  runs the upgrade, and shows what's new.
+  runs the upgrade, and shows what's new. Use when asked to "upgrade gstack",
+  "update gstack", or "get latest version".
 allowed-tools:
   - Bash
   - Read

diff --git a/gstack-upgrade/SKILL.md.tmpl b/gstack-upgrade/SKILL.md.tmpl
@@ -3,7 +3,8 @@ name: gstack-upgrade
 version: 1.1.0
 description: |
   Upgrade gstack to the latest version. Detects global vs vendored install,
-  runs the upgrade, and shows what's new.
+  runs the upgrade, and shows what's new. Use when asked to "upgrade gstack",
+  "update gstack", or "get latest version".
 allowed-tools:
   - Bash
   - Read

diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md
@@ -6,6 +6,8 @@ description: |
   challenge premises, expand scope when it creates a better product. Four modes:
   SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick
   expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
+  Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
+  or "is this ambitious enough".
 allowed-tools:
   - Read
   - Grep

diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl
@@ -6,6 +6,8 @@ description: |
   challenge premises, expand scope when it creates a better product. Four modes:
   SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick
   expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
+  Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
+  or "is this ambitious enough".
 allowed-tools:
   - Read
   - Grep

diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md
@@ -5,7 +5,8 @@ description: |
   Designer's eye plan review — interactive, like CEO and Eng review.
   Rates each design dimension 0-10, explains what would make it a 10,
   then fixes the plan to get there. Works in plan mode. For live site
-  visual audits, use /design-review.
+  visual audits, use /design-review. Use when asked to "review the design plan"
+  or "design critique".
 allowed-tools:
   - Read
   - Edit

diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl
@@ -5,7 +5,8 @@ description: |
   Designer's eye plan review — interactive, like CEO and Eng review.
   Rates each design dimension 0-10, explains what would make it a 10,
   then fixes the plan to get there. Works in plan mode. For live site
-  visual audits, use /design-review.
+  visual audits, use /design-review. Use when asked to "review the design plan"
+  or "design critique".
 allowed-tools:
   - Read
   - Edit

diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Eng manager-mode plan review. Lock in the execution plan — architecture,
   data flow, diagrams, edge cases, test coverage, performance. Walks through
-  issues interactively with opinionated recommendations.
+  issues interactively with opinionated recommendations. Use when asked to
+  "review the architecture", "engineering review", or "lock in the plan".
 allowed-tools:
   - Read
   - Write

diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Eng manager-mode plan review. Lock in the execution plan — architecture,
   data flow, diagrams, edge cases, test coverage, performance. Walks through
-  issues interactively with opinionated recommendations.
+  issues interactively with opinionated recommendations. Use when asked to
+  "review the architecture", "engineering review", or "lock in the plan".
 allowed-tools:
   - Read
   - Write

diff --git a/retro/SKILL.md b/retro/SKILL.md
@@ -5,6 +5,7 @@ description: |
   Weekly engineering retrospective. Analyzes commit history, work patterns,
   and code quality metrics with persistent history and trend tracking.
   Team-aware: breaks down per-person contributions with praise and growth areas.
+  Use when asked to "weekly retro", "what did we ship", or "engineering retrospective".
 allowed-tools:
   - Bash
   - Read

diff --git a/retro/SKILL.md.tmpl b/retro/SKILL.md.tmpl
@@ -5,6 +5,7 @@ description: |
   Weekly engineering retrospective. Analyzes commit history, work patterns,
   and code quality metrics with persistent history and trend tracking.
   Team-aware: breaks down per-person contributions with praise and growth areas.
+  Use when asked to "weekly retro", "what did we ship", or "engineering retrospective".
 allowed-tools:
   - Bash
   - Read

diff --git a/review/SKILL.md b/review/SKILL.md
@@ -3,7 +3,8 @@ name: review
 version: 1.0.0
 description: |
   Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust
-  boundary violations, conditional side effects, and other structural issues.
+  boundary violations, conditional side effects, and other structural issues. Use when
+  asked to "review this PR", "code review", "pre-landing review", or "check my diff".
 allowed-tools:
   - Bash
   - Read

diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl
@@ -3,7 +3,8 @@ name: review
 version: 1.0.0
 description: |
   Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust
-  boundary violations, conditional side effects, and other structural issues.
+  boundary violations, conditional side effects, and other structural issues. Use when
+  asked to "review this PR", "code review", "pre-landing review", or "check my diff".
 allowed-tools:
   - Bash
   - Read

diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the
   headless browse session. Opens an interactive picker UI where you select which
-  cookie domains to import. Use before QA testing authenticated pages.
+  cookie domains to import. Use before QA testing authenticated pages. Use when asked
+  to "import cookies", "login to the site", or "authenticate the browser".
 allowed-tools:
   - Bash
   - Read

diff --git a/setup-browser-cookies/SKILL.md.tmpl b/setup-browser-cookies/SKILL.md.tmpl
@@ -4,7 +4,8 @@ version: 1.0.0
 description: |
   Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the
   headless browse session. Opens an interactive picker UI where you select which
-  cookie domains to import. Use before QA testing authenticated pages.
+  cookie domains to import. Use before QA testing authenticated pages. Use when asked
+  to "import cookies", "login to the site", or "authenticate the browser".
 allowed-tools:
   - Bash
   - Read

diff --git a/ship/SKILL.md b/ship/SKILL.md
@@ -2,7 +2,7 @@
 name: ship
 version: 1.0.0
 description: |
-  Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.
+  Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", "push to main", "create a PR", or "merge and push".
 allowed-tools:
   - Bash
   - Read

diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl
@@ -2,7 +2,7 @@
 name: ship
 version: 1.0.0
 description: |
-  Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.
+  Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", "push to main", "create a PR", or "merge and push".
 allowed-tools:
   - Bash
   - Read