From 3891cd70657983af4374d8120c6cffab7b2cc6ce Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 22:23:53 -0700 Subject: [PATCH 1/3] feat: add trigger phrases to skill descriptions for better model matching MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- browse/SKILL.md | 3 ++- browse/SKILL.md.tmpl | 3 ++- design-consultation/SKILL.md | 1 + design-consultation/SKILL.md.tmpl | 1 + design-review/SKILL.md | 1 + design-review/SKILL.md.tmpl | 1 + document-release/SKILL.md | 3 ++- document-release/SKILL.md.tmpl | 3 ++- gstack-upgrade/SKILL.md | 3 ++- gstack-upgrade/SKILL.md.tmpl | 3 ++- plan-ceo-review/SKILL.md | 2 ++ plan-ceo-review/SKILL.md.tmpl | 2 ++ plan-design-review/SKILL.md | 3 ++- plan-design-review/SKILL.md.tmpl | 3 ++- plan-eng-review/SKILL.md | 3 ++- plan-eng-review/SKILL.md.tmpl | 3 ++- retro/SKILL.md | 1 + retro/SKILL.md.tmpl | 1 + review/SKILL.md | 3 ++- review/SKILL.md.tmpl | 3 ++- setup-browser-cookies/SKILL.md | 3 ++- setup-browser-cookies/SKILL.md.tmpl | 3 ++- ship/SKILL.md | 2 +- ship/SKILL.md.tmpl | 2 +- 24 files changed, 40 insertions(+), 16 deletions(-) diff --git a/browse/SKILL.md b/browse/SKILL.md index 50198d5f..7d13f0a7 100644 --- 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 index 0c42ffcb..7030eac2 100644 --- 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 index 8fd9cb4b..277c762a 100644 --- 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 index 141a9190..ecb50078 100644 --- 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 index b06e0827..3726098b 100644 --- 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 index eb8dd6b8..f60a9c41 100644 --- 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 index bc8ff4ca..dacf3d13 100644 --- 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 index e38c243c..2cd8d117 100644 --- 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 index 50b67dfc..6dcc1f7c 100644 --- 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 index 0acf16c2..1d49cd1b 100644 --- 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 index ce799fe1..f40a0131 100644 --- 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 index 1a8b0658..273b4a86 100644 --- 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 index 507952c4..e8d49df3 100644 --- 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 index f8f5221a..e8f9c418 100644 --- 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 index 48fe7230..b780ad69 100644 --- 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 index 91f24719..2b232a80 100644 --- 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 index 71eab988..c849dd8b 100644 --- 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 index bfbc2003..92d5c40b 100644 --- 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 index 3a14a9d3..bfd29a7f 100644 --- 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 index c1d3fae6..325a522e 100644 --- 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 index da64dec4..cf37fc82 100644 --- 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 index dcab3745..4496d11c 100644 --- 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 index 875845dc..c59455d0 100644 --- 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 index bb077dac..245660b6 100644 --- 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 From 60837ee66bccdd0467bfa6dda98da9932ddfb91b Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 22:23:57 -0700 Subject: [PATCH 2/3] 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) --- TODOS.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/TODOS.md b/TODOS.md index 5f771de7..4c8433ae 100644 --- 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) From 33cd575cc046e84ae87a8df856ff55326e626df9 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 23:50:42 -0700 Subject: [PATCH 3/3] chore: bump version and changelog (v0.6.4.1) Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 7 +++++++ VERSION | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 49d9183d..5c740986 100644 --- 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/VERSION b/VERSION index 31d34d20..f4362155 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.6.4.0 +0.6.4.1