feat: add trigger phrases to skill descriptions for better model matching (v0.6.4.1) (#169)

* feat: add trigger phrases to skill descriptions for better model matching

Anthropic's skill best practices: "the description field is not a summary —
it's when to trigger." Add explicit "Use when asked to..." phrases to 12 skill
descriptions so Claude's auto-discovery works with natural language requests
like "deploy this" or "check my diff", not just explicit /slash-commands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add on-demand hooks and telemetry to TODOS.md

Captures two ideas from Anthropic's skill best practices post:
- /careful, /freeze, /guard on-demand hook skills (P3)
- Skill usage telemetry via preamble JSONL append (P3)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: bump version and changelog (v0.6.4.1)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: exclude internal details from CHANGELOG style guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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."
+
 ## [0.6.4.0] - 2026-03-17
 
 ### Added

CLAUDE.md

@@ -141,6 +141,8 @@ CHANGELOG.md is **for users**, not contributors. Write it like product release n
 
 - Lead with what the user can now **do** that they couldn't before. Sell the feature.
 - Use plain language, not implementation details. "You can now..." not "Refactored the..."
+- **Never mention TODOS.md, internal tracking, eval infrastructure, or contributor-facing
+  details.** These are invisible to users and meaningless to them.
 - Put contributor/internal changes in a separate "For contributors" section at the bottom.
 - Every entry should make someone think "oh nice, I want to try that."
 - No jargon: say "every question now tells you which project and branch you're in" not

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)

VERSION

@@ -1 +1 @@
-0.6.4.0
+0.6.4.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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