From bc86a665b75f60018e37710e22426b3d0ef352c8 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Mar 2026 08:06:46 -0500 Subject: [PATCH] feat: add trigger phrases to skill descriptions for better model matching (v0.6.4.1) (#169) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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) * 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) * chore: bump version and changelog (v0.6.4.1) Co-Authored-By: Claude Opus 4.6 * docs: exclude internal details from CHANGELOG style guide Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 6 ++++++ CLAUDE.md | 2 ++ TODOS.md | 31 +++++++++++++++++++++++++++++ VERSION | 2 +- 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 +- 28 files changed, 80 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 49d9183df3859578d2a4a528a8923d423db451a5..f71c9870e664770949fb67498d8eec08e3c70a72 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CLAUDE.md b/CLAUDE.md index 0979c95efc95d3b0233934869fa6ea2183ca94f0..44247ce5271f406a5e325c88b5898bb1c86a79bf 100644 --- a/CLAUDE.md +++ b/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 diff --git a/TODOS.md b/TODOS.md index 5f771de769fc3be307a83deb01d2f0d5027f59a5..4c8433aec5e2147de92a6ed7726df54019c3743e 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) diff --git a/VERSION b/VERSION index 31d34d203562e51ebbb5c09968c90480caa70cf0..f43621550c2fced9f1e258c7a7c06bc6caf011e2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.6.4.0 +0.6.4.1 diff --git a/browse/SKILL.md b/browse/SKILL.md index 50198d5fa8142069f053fa8c684dc3f9f81d112a..7d13f0a71bb597b91810030d3c546d1dd43ba2e7 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 0c42ffcb40457f4bbefb4493169ebb5a7068204b..7030eac2b0a6fd68b20327f0a000b491d8a2f65a 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 8fd9cb4b257a348dea637aa153fdbadaf18d0acd..277c762a171e6030dac56ce5848424b55b18514b 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 141a919011c47281ead765346511a7c32e3cdf03..ecb5007881131df49058f1286bd4b4c2034a4b2d 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 b06e0827e4461ae12163a97d4dc7992ef3093b61..3726098b7171603f4faee4b5f14b526df5480f10 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 eb8dd6b81be1c0935e190042bb953c35694ec7ca..f60a9c412ece647b2e836b302462167b338c33cf 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 bc8ff4ca31855e2675d41c829f2148ad613fbdb2..dacf3d1357595a1872e7a2a8ced2c49773bee338 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 e38c243ce2aacf3c6a29e3302495b7c6d1b62262..2cd8d11726201a28f489e88e78a02f2076adb957 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 50b67dfcc38c187be14152433c1f38bf26845774..6dcc1f7c2237b3060690ea9cf3deb59d6496b2ac 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 0acf16c200ebe38c0df3a9ce460b84dc2af7b152..1d49cd1b6f67c8be96cd0dccf99a23c46ef33245 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 ce799fe17916344b503cf342d71f6ff651af76a0..f40a013157386d3215ef5ea188fe4f7160424bd3 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 1a8b065865cfd93d70085f152e08519b290e66eb..273b4a86393936d0b96a0480cd92f1dd15e74822 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 507952c4268e2ada453e731a893b54b4c9490956..e8d49df31ea5171f9e87f86707f1a0e4860965d1 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 f8f5221a28b5c74bad2b693c0fc29759caddf720..e8f9c418aef175d734670bf75fc0a3982599a81c 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 48fe7230532dbec8fd2e41949e5588bc80420735..b780ad690f02fb9b8b5a7a0bd688997a5c1a3fc7 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 91f247190b2fe9ef29e4b8d5e52be819f1367518..2b232a8070386871522bb5dec1887226d5b9f57e 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 71eab988fdb938a0930f5cc7314feb9be811f22f..c849dd8bcd5253afb755b39f3cbbc94db6454bd0 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 bfbc2003bffcf5610bfdcae09bdbf829be250379..92d5c40bf4b2da303cbf87675cfa65270ae5593f 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 3a14a9d3ab9de67fd67791b43e7d2c4c8a37f82a..bfd29a7fddd2fb5fead2e56860dc01a19d727fce 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 c1d3fae643cc2ca5822f8f6d8453e99f1917ffe4..325a522ed5627b0122bd15821b6a5b6de17b40da 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 da64dec4f964c4bb8a96490c1c60e0d86cd3c691..cf37fc82cbfa004141d3d28ca37375e0c9616f8c 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 dcab374508f49eae339f37630e471dc4af8d46d3..4496d11c55616d8e61d83a0d68941d3f56db722a 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 875845dcdd19e7cc894cd8179dfc3e5288eedc4d..c59455d06e2f7f6412e884a347d2f1b9f35aaca2 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 bb077dacade94bd95f13de71a9c1f5965e009b7e..245660b67426ede96dd1f681f21a785eabbda039 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