From 0d68ef1a3917737dda21968c68607a97d88eee57 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 25 May 2026 20:35:15 -0700 Subject: [PATCH] =?UTF-8?q?feat(catalog):=20T4=20=E2=80=94=20catalog=20tri?= =?UTF-8?q?m=20+=20proactive-suggestions.json=20(Phase=20A.4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shortens frontmatter `description:` in every Claude SKILL.md to a single lead sentence + (gstack) tag. The routing prose ("Use when asked to...", "Proactively suggest...") and voice triggers move to a "## When to invoke" body section so they remain discoverable inside the skill. A per-run registry at scripts/proactive-suggestions.json aggregates the routing/ voice text for all 52 skills so agents can pull guidance on demand without paying for it in the always-loaded catalog. Build flag --catalog-mode=full restores v1.44 legacy behavior (full multi-line descriptions in frontmatter). Default is trim. splitCatalogDescription() extracts: lead sentence, routing paragraphs, voice-triggers line, (gstack) tag presence. Short descriptions (<120 chars, already trimmed) are skipped via a guard so re-runs are idempotent. Measured impact (vs v1.44.1 baseline): - Catalog tokens (sum of description bytes / 4): 9,319 → 4,045 (-56.6%) - Total SKILL.md corpus bytes: 2,915 KB → 2,880 KB (-1.2%) - Routing prose preserved as in-skill "## When to invoke" sections - 52 skill entries in scripts/proactive-suggestions.json (on-demand registry) The corpus drop is small because catalog trim MOVES text from frontmatter to body, it doesn't delete it. The headline win is the catalog: the always-loaded system prompt surface drops by more than half. Test plan: - bun test test/gen-skill-docs.test.ts: 389 pass, 0 fail - Manual: ship/SKILL.md frontmatter description is now ONE line ending with `(gstack)`; allowed-tools field on next line (YAML well-formed) - Manual: scripts/proactive-suggestions.json contains 52 entries - bun run gen:skill-docs --catalog-mode=full restores legacy behavior 53 files changed (52 SKILL.md across hosts + the new proactive-suggestions.json). Co-Authored-By: Claude Opus 4.7 (1M context) --- SKILL.md | 14 +- autoplan/SKILL.md | 24 +-- benchmark-models/SKILL.md | 21 ++- benchmark/SKILL.md | 19 +- browse/SKILL.md | 18 +- canary/SKILL.md | 16 +- careful/SKILL.md | 16 +- codex/SKILL.md | 19 +- context-restore/SKILL.md | 20 ++- context-save/SKILL.md | 19 +- cso/SKILL.md | 21 ++- design-consultation/SKILL.md | 12 +- design-html/SKILL.md | 24 +-- design-review/SKILL.md | 19 +- design-shotgun/SKILL.md | 17 +- devex-review/SKILL.md | 23 ++- document-generate/SKILL.md | 17 +- document-release/SKILL.md | 20 ++- freeze/SKILL.md | 16 +- gstack-upgrade/SKILL.md | 15 +- guard/SKILL.md | 15 +- health/SKILL.md | 16 +- investigate/SKILL.md | 20 ++- ios-clean/SKILL.md | 22 ++- ios-design-review/SKILL.md | 27 +-- ios-fix/SKILL.md | 25 +-- ios-qa/SKILL.md | 27 +-- ios-sync/SKILL.md | 20 ++- land-and-deploy/SKILL.md | 14 +- landing-report/SKILL.md | 16 +- learn/SKILL.md | 16 +- make-pdf/SKILL.md | 19 +- office-hours/SKILL.md | 28 +-- open-gstack-browser/SKILL.md | 18 +- pair-agent/SKILL.md | 21 ++- plan-ceo-review/SKILL.md | 22 ++- plan-design-review/SKILL.md | 19 +- plan-devex-review/SKILL.md | 25 +-- plan-eng-review/SKILL.md | 21 ++- plan-tune/SKILL.md | 29 ++-- qa-only/SKILL.md | 19 +- qa/SKILL.md | 25 +-- retro/SKILL.md | 16 +- review/SKILL.md | 14 +- scrape/SKILL.md | 18 +- scripts/gen-skill-docs.ts | 218 ++++++++++++++++++++++- scripts/proactive-suggestions.json | 268 +++++++++++++++++++++++++++++ setup-browser-cookies/SKILL.md | 13 +- setup-deploy/SKILL.md | 18 +- setup-gbrain/SKILL.md | 14 +- ship/SKILL.md | 15 +- skillify/SKILL.md | 19 +- sync-gbrain/SKILL.md | 16 +- unfreeze/SKILL.md | 13 +- 54 files changed, 1078 insertions(+), 398 deletions(-) create mode 100644 scripts/proactive-suggestions.json diff --git a/SKILL.md b/SKILL.md index c6441014c..56f74ba07 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,11 +2,7 @@ name: gstack preamble-tier: 1 version: 1.1.0 -description: | - Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with - elements, verify state, diff before/after, take annotated screenshots, test responsive - layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or - test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack) +description: Fast headless browser for QA testing and site dogfooding. (gstack) allowed-tools: - Bash - Read @@ -21,6 +17,14 @@ triggers: + +## When to invoke this skill + +Navigate pages, interact with +elements, verify state, diff before/after, take annotated screenshots, test responsive +layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or +test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. + ## Preamble (run first) ```bash diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 0b4479d4a..073ba4b86 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -2,16 +2,7 @@ name: autoplan preamble-tier: 3 version: 1.0.0 -description: | - Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk - and runs them sequentially with auto-decisions using 6 decision principles. Surfaces - taste decisions (close approaches, borderline scope, codex disagreements) at a final - approval gate. One command, fully reviewed plan out. - Use when asked to "auto review", "autoplan", "run all reviews", "review this plan - automatically", or "make the decisions for me". - Proactively suggest when the user has a plan file and wants to run the full review - gauntlet without answering 15-30 intermediate questions. (gstack) - Voice triggers (speech-to-text aliases): "auto plan", "automatic review". +description: Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk and runs them sequentially with auto-decisions using 6 decision principles. (gstack) benefits-from: [office-hours] triggers: - run all reviews @@ -30,6 +21,19 @@ allowed-tools: + +## When to invoke this skill + +Surfaces +taste decisions (close approaches, borderline scope, codex disagreements) at a final +approval gate. One command, fully reviewed plan out. +Use when asked to "auto review", "autoplan", "run all reviews", "review this plan +automatically", or "make the decisions for me". +Proactively suggest when the user has a plan file and wants to run the full review +gauntlet without answering 15-30 intermediate questions. + +Voice triggers (speech-to-text aliases): "auto plan", "automatic review". + ## Preamble (run first) ```bash diff --git a/benchmark-models/SKILL.md b/benchmark-models/SKILL.md index 47050855b..ef821a3ea 100644 --- a/benchmark-models/SKILL.md +++ b/benchmark-models/SKILL.md @@ -2,14 +2,7 @@ name: benchmark-models preamble-tier: 1 version: 1.0.0 -description: | - Cross-model benchmark for gstack skills. Runs the same prompt through Claude, - GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, - and optionally quality via LLM judge. Answers "which model is actually best - for this skill?" with data instead of vibes. Separate from /benchmark, which - measures web page performance. Use when: "benchmark models", "compare models", - "which model is best for X", "cross-model comparison", "model shootout". (gstack) - Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best". +description: Cross-model benchmark for gstack skills. (gstack) triggers: - cross model benchmark - compare claude gpt gemini @@ -23,6 +16,18 @@ allowed-tools: + +## When to invoke this skill + +Runs the same prompt through Claude, +GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, +and optionally quality via LLM judge. Answers "which model is actually best +for this skill?" with data instead of vibes. Separate from /benchmark, which +measures web page performance. Use when: "benchmark models", "compare models", +"which model is best for X", "cross-model comparison", "model shootout". + +Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best". + ## Preamble (run first) ```bash diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index b6dc81373..841fb95b6 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -2,13 +2,7 @@ name: benchmark preamble-tier: 1 version: 1.0.0 -description: | - Performance regression detection using the browse daemon. Establishes - baselines for page load times, Core Web Vitals, and resource sizes. - Compares before/after on every PR. Tracks performance trends over time. - Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals", - "bundle size", "load time". (gstack) - Voice triggers (speech-to-text aliases): "speed test", "check performance". +description: Performance regression detection using the browse daemon. (gstack) triggers: - performance benchmark - check page speed @@ -23,6 +17,17 @@ allowed-tools: + +## When to invoke this skill + +Establishes +baselines for page load times, Core Web Vitals, and resource sizes. +Compares before/after on every PR. Tracks performance trends over time. +Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals", +"bundle size", "load time". + +Voice triggers (speech-to-text aliases): "speed test", "check performance". + ## Preamble (run first) ```bash diff --git a/browse/SKILL.md b/browse/SKILL.md index 6a4f5c269..74cf086fd 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -2,13 +2,7 @@ name: browse preamble-tier: 1 version: 1.1.0 -description: | - Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with - 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. Use when asked to "open in browser", "test the - site", "take a screenshot", or "dogfood this". (gstack) +description: Fast headless browser for QA testing and site dogfooding. (gstack) triggers: - browse a page - headless browser @@ -22,6 +16,16 @@ allowed-tools: + +## When to invoke this skill + +Navigate any URL, interact with +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. Use when asked to "open in browser", "test the +site", "take a screenshot", or "dogfood this". + ## Preamble (run first) ```bash diff --git a/canary/SKILL.md b/canary/SKILL.md index a013617b1..b305bfd45 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -2,12 +2,7 @@ name: canary preamble-tier: 2 version: 1.0.0 -description: | - Post-deploy canary monitoring. Watches the live app for console errors, - performance regressions, and page failures using the browse daemon. Takes - periodic screenshots, compares against pre-deploy baselines, and alerts - on anomalies. Use when: "monitor deploy", "canary", "post-deploy check", - "watch production", "verify deploy". (gstack) +description: Post-deploy canary monitoring. (gstack) allowed-tools: - Bash - Read @@ -22,6 +17,15 @@ triggers: + +## When to invoke this skill + +Watches the live app for console errors, +performance regressions, and page failures using the browse daemon. Takes +periodic screenshots, compares against pre-deploy baselines, and alerts +on anomalies. Use when: "monitor deploy", "canary", "post-deploy check", +"watch production", "verify deploy". + ## Preamble (run first) ```bash diff --git a/careful/SKILL.md b/careful/SKILL.md index 91a5776e3..678d66c16 100644 --- a/careful/SKILL.md +++ b/careful/SKILL.md @@ -1,12 +1,7 @@ --- name: careful version: 0.1.0 -description: | - Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE, - force-push, git reset --hard, kubectl delete, and similar destructive operations. - User can override each warning. Use when touching prod, debugging live systems, - or working in a shared environment. Use when asked to "be careful", "safety mode", - "prod mode", or "careful mode". (gstack) +description: Safety guardrails for destructive commands. (gstack) triggers: - be careful - warn before destructive @@ -25,6 +20,15 @@ hooks: + +## When to invoke this skill + +Warns before rm -rf, DROP TABLE, +force-push, git reset --hard, kubectl delete, and similar destructive operations. +User can override each warning. Use when touching prod, debugging live systems, +or working in a shared environment. Use when asked to "be careful", "safety mode", +"prod mode", or "careful mode". + # /careful — Destructive Command Guardrails Safety mode is now **active**. Every bash command will be checked for destructive diff --git a/codex/SKILL.md b/codex/SKILL.md index e568d33e8..8051a80b6 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -2,13 +2,7 @@ name: codex preamble-tier: 3 version: 1.0.0 -description: | - OpenAI Codex CLI wrapper — three modes. Code review: independent diff review via - codex review with pass/fail gate. Challenge: adversarial mode that tries to break - your code. Consult: ask codex anything with session continuity for follow-ups. - The "200 IQ autistic developer" second opinion. Use when asked to "codex review", - "codex challenge", "ask codex", "second opinion", or "consult codex". (gstack) - Voice triggers (speech-to-text aliases): "code x", "code ex", "get another opinion". +description: OpenAI Codex CLI wrapper — three modes. (gstack) triggers: - codex review - second opinion @@ -24,6 +18,17 @@ allowed-tools: + +## When to invoke this skill + +Code review: independent diff review via +codex review with pass/fail gate. Challenge: adversarial mode that tries to break +your code. Consult: ask codex anything with session continuity for follow-ups. +The "200 IQ autistic developer" second opinion. Use when asked to "codex review", +"codex challenge", "ask codex", "second opinion", or "consult codex". + +Voice triggers (speech-to-text aliases): "code x", "code ex", "get another opinion". + ## Preamble (run first) ```bash diff --git a/context-restore/SKILL.md b/context-restore/SKILL.md index 88c50b2ac..d385ecdfe 100644 --- a/context-restore/SKILL.md +++ b/context-restore/SKILL.md @@ -2,14 +2,7 @@ name: context-restore preamble-tier: 2 version: 1.0.0 -description: | - Restore working context saved earlier by /context-save. Loads the most recent - saved state (across all branches by default) so you can pick up where you - left off — even across Conductor workspace handoffs. - Use when asked to "resume", "restore context", "where was I", or - "pick up where I left off". Pair with /context-save. - Formerly /checkpoint resume — renamed because Claude Code treats /checkpoint - as a native rewind alias in current environments. (gstack) +description: Restore working context saved earlier by /context-save. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Loads the most recent +saved state (across all branches by default) so you can pick up where you +left off — even across Conductor workspace handoffs. +Use when asked to "resume", "restore context", "where was I", or +"pick up where I left off". Pair with /context-save. +Formerly /checkpoint resume — renamed because Claude Code treats /checkpoint +as a native rewind alias in current environments. + ## Preamble (run first) ```bash diff --git a/context-save/SKILL.md b/context-save/SKILL.md index 3bf42f569..fae5e29d7 100644 --- a/context-save/SKILL.md +++ b/context-save/SKILL.md @@ -2,14 +2,7 @@ name: context-save preamble-tier: 2 version: 1.0.0 -description: | - Save working context. Captures git state, decisions made, and remaining work - so any future session can pick up without losing a beat. - Use when asked to "save progress", "save state", "context save", or - "save my work". Pair with /context-restore to resume later. - Formerly /checkpoint — renamed because Claude Code treats /checkpoint as a - native rewind alias in current environments, which was shadowing this skill. - (gstack) +description: Save working context. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,16 @@ triggers: + +## When to invoke this skill + +Captures git state, decisions made, and remaining work +so any future session can pick up without losing a beat. +Use when asked to "save progress", "save state", "context save", or +"save my work". Pair with /context-restore to resume later. +Formerly /checkpoint — renamed because Claude Code treats /checkpoint as a +native rewind alias in current environments, which was shadowing this skill. + ## Preamble (run first) ```bash diff --git a/cso/SKILL.md b/cso/SKILL.md index e83e3b815..50bb4fee1 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -2,14 +2,7 @@ name: cso preamble-tier: 2 version: 2.0.0 -description: | - Chief Security Officer mode. Infrastructure-first security audit: secrets archaeology, - dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain - scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification. - Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep - scan, 2/10 bar). Trend tracking across audit runs. - Use when: "security audit", "threat model", "pentest review", "OWASP", "CSO review". (gstack) - Voice triggers (speech-to-text aliases): "see-so", "see so", "security review", "security check", "vulnerability scan", "run security". +description: Chief Security Officer mode. (gstack) allowed-tools: - Bash - Read @@ -27,6 +20,18 @@ triggers: + +## When to invoke this skill + +Infrastructure-first security audit: secrets archaeology, +dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain +scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification. +Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep +scan, 2/10 bar). Trend tracking across audit runs. +Use when: "security audit", "threat model", "pentest review", "OWASP", "CSO review". + +Voice triggers (speech-to-text aliases): "see-so", "see so", "security review", "security check", "vulnerability scan", "run security". + ## Preamble (run first) ```bash diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index f9291ce5d..3f7db26da 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -2,14 +2,7 @@ name: design-consultation preamble-tier: 3 version: 1.0.0 -description: | - Design consultation: understands your product, researches the landscape, proposes a - 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". - Proactively suggest when starting a new project's UI with no existing - design system or DESIGN.md. (gstack) +description: Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview... (gstack) allowed-tools: - Bash - Read @@ -50,6 +43,9 @@ gbrain: + +## When to invoke this skill + ## Preamble (run first) ```bash diff --git a/design-html/SKILL.md b/design-html/SKILL.md index b3f1c84f1..b0e8a5f30 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -2,16 +2,7 @@ name: design-html preamble-tier: 2 version: 1.0.0 -description: | - Design finalization: generates production-quality Pretext-native HTML/CSS. - Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review, - design review context from /plan-design-review, or from scratch with a user - description. Text actually reflows, heights are computed, layouts are dynamic. - 30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns - for each design type. Use when: "finalize this design", "turn this into HTML", - "build me a page", "implement this design", or after any planning skill. - Proactively suggest when user has approved a design or has a plan ready. (gstack) - Voice triggers (speech-to-text aliases): "build the design", "code the mockup", "make it real". +description: Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack) triggers: - build the design - code the mockup @@ -29,6 +20,19 @@ allowed-tools: + +## When to invoke this skill + +Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review, +design review context from /plan-design-review, or from scratch with a user +description. Text actually reflows, heights are computed, layouts are dynamic. +30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns +for each design type. Use when: "finalize this design", "turn this into HTML", +"build me a page", "implement this design", or after any planning skill. +Proactively suggest when user has approved a design or has a plan ready. + +Voice triggers (speech-to-text aliases): "build the design", "code the mockup", "make it real". + ## Preamble (run first) ```bash diff --git a/design-review/SKILL.md b/design-review/SKILL.md index faf371b33..87b04124f 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -2,14 +2,7 @@ name: design-review preamble-tier: 4 version: 2.0.0 -description: | - Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, - 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". - Proactively suggest when the user mentions visual inconsistencies or - wants to polish the look of a live site. (gstack) +description: Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. (gstack) allowed-tools: - Bash - Read @@ -27,6 +20,16 @@ triggers: + +## When to invoke this skill + +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". +Proactively suggest when the user mentions visual inconsistencies or +wants to polish the look of a live site. + ## Preamble (run first) ```bash diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index f14db3764..7433a2a78 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -2,13 +2,7 @@ name: design-shotgun preamble-tier: 2 version: 1.0.0 -description: | - Design shotgun: generate multiple AI design variants, open a comparison board, - collect structured feedback, and iterate. Standalone design exploration you can - run anytime. Use when: "explore designs", "show me options", "design variants", - "visual brainstorm", or "I don't like how this looks". - Proactively suggest when the user describes a UI feature but hasn't seen - what it could look like. (gstack) +description: Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate. (gstack) triggers: - explore design variants - show me design options @@ -44,6 +38,15 @@ gbrain: + +## When to invoke this skill + +Standalone design exploration you can +run anytime. Use when: "explore designs", "show me options", "design variants", +"visual brainstorm", or "I don't like how this looks". +Proactively suggest when the user describes a UI feature but hasn't seen +what it could look like. + ## Preamble (run first) ```bash diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index db5b8f2cd..de339fbe6 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -2,15 +2,7 @@ name: devex-review preamble-tier: 3 version: 1.0.0 -description: | - Live developer experience audit. Uses the browse tool to actually TEST the - developer experience: navigates docs, tries the getting started flow, times - TTHW, screenshots error messages, evaluates CLI help text. Produces a DX - scorecard with evidence. Compares against /plan-devex-review scores if they - exist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to - "test the DX", "DX audit", "developer experience test", or "try the - onboarding". Proactively suggest after shipping a developer-facing feature. (gstack) - Voice triggers (speech-to-text aliases): "dx audit", "test the developer experience", "try the onboarding", "developer experience test". +description: Live developer experience audit. (gstack) triggers: - live dx audit - test developer experience @@ -27,6 +19,19 @@ allowed-tools: + +## When to invoke this skill + +Uses the browse tool to actually TEST the +developer experience: navigates docs, tries the getting started flow, times +TTHW, screenshots error messages, evaluates CLI help text. Produces a DX +scorecard with evidence. Compares against /plan-devex-review scores if they +exist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to +"test the DX", "DX audit", "developer experience test", or "try the +onboarding". Proactively suggest after shipping a developer-facing feature. + +Voice triggers (speech-to-text aliases): "dx audit", "test the developer experience", "try the onboarding", "developer experience test". + ## Preamble (run first) ```bash diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md index 4b59529cf..fb53315e8 100644 --- a/document-generate/SKILL.md +++ b/document-generate/SKILL.md @@ -2,13 +2,7 @@ name: document-generate preamble-tier: 2 version: 1.0.0 -description: | - Generate missing documentation from scratch for a feature, module, or entire project. - Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce - complete, structured documentation. Can be invoked standalone or called by - /document-release when it finds coverage gaps. Use when asked to "write docs", - "generate documentation", "document this feature", "create a tutorial", or - "explain this module". (gstack) +description: Generate missing documentation from scratch for a feature, module, or entire project. (gstack) allowed-tools: - Bash - Read @@ -29,6 +23,15 @@ triggers: + +## When to invoke this skill + +Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce +complete, structured documentation. Can be invoked standalone or called by +/document-release when it finds coverage gaps. Use when asked to "write docs", +"generate documentation", "document this feature", "create a tutorial", or +"explain this module". + ## Preamble (run first) ```bash diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 694fcf243..10ce70573 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -2,14 +2,7 @@ name: document-release preamble-tier: 2 version: 1.0.0 -description: | - Post-ship documentation update. Reads all project docs, cross-references the - diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), - updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, - detects architecture diagram drift, polishes CHANGELOG voice with a sell-test - rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation - debt in the PR body. Use when asked to "update the docs", "sync documentation", - or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack) +description: Post-ship documentation update. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Reads all project docs, cross-references the +diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), +updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, +detects architecture diagram drift, polishes CHANGELOG voice with a sell-test +rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation +debt in the PR body. Use when asked to "update the docs", "sync documentation", +or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. + ## Preamble (run first) ```bash diff --git a/freeze/SKILL.md b/freeze/SKILL.md index 87f8506ca..fc82b1bea 100644 --- a/freeze/SKILL.md +++ b/freeze/SKILL.md @@ -1,12 +1,7 @@ --- name: freeze version: 0.1.0 -description: | - Restrict file edits to a specific directory for the session. Blocks Edit and - Write outside the allowed path. Use when debugging to prevent accidentally - "fixing" unrelated code, or when you want to scope changes to one module. - Use when asked to "freeze", "restrict edits", "only edit this folder", - or "lock down edits". (gstack) +description: Restrict file edits to a specific directory for the session. (gstack) triggers: - freeze edits to directory - lock editing scope @@ -31,6 +26,15 @@ hooks: + +## When to invoke this skill + +Blocks Edit and +Write outside the allowed path. Use when debugging to prevent accidentally +"fixing" unrelated code, or when you want to scope changes to one module. +Use when asked to "freeze", "restrict edits", "only edit this folder", +or "lock down edits". + # /freeze — Restrict Edits to a Directory Lock file edits to a specific directory. Any Edit or Write operation targeting diff --git a/gstack-upgrade/SKILL.md b/gstack-upgrade/SKILL.md index 81bb1228c..9f0f2f7ea 100644 --- a/gstack-upgrade/SKILL.md +++ b/gstack-upgrade/SKILL.md @@ -1,11 +1,7 @@ --- 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. Use when asked to "upgrade gstack", - "update gstack", or "get latest version". - Voice triggers (speech-to-text aliases): "upgrade the tools", "update the tools", "gee stack upgrade", "g stack upgrade". +description: Upgrade gstack to the latest version. triggers: - upgrade gstack - update gstack version @@ -19,6 +15,15 @@ allowed-tools: + +## When to invoke this skill + +Detects global vs vendored install, +runs the upgrade, and shows what's new. Use when asked to "upgrade gstack", +"update gstack", or "get latest version". + +Voice triggers (speech-to-text aliases): "upgrade the tools", "update the tools", "gee stack upgrade", "g stack upgrade". + # /gstack-upgrade Upgrade gstack to the latest version and show what's new. diff --git a/guard/SKILL.md b/guard/SKILL.md index 36216ac16..8d4a57448 100644 --- a/guard/SKILL.md +++ b/guard/SKILL.md @@ -1,12 +1,7 @@ --- name: guard version: 0.1.0 -description: | - Full safety mode: destructive command warnings + directory-scoped edits. - Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with - /freeze (blocks edits outside a specified directory). Use for maximum safety - when touching prod or debugging live systems. Use when asked to "guard mode", - "full safety", "lock it down", or "maximum safety". (gstack) +description: Full safety mode: destructive command warnings + directory-scoped edits. (gstack) triggers: - full safety mode - guard against mistakes @@ -36,6 +31,14 @@ hooks: + +## When to invoke this skill + +Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with +/freeze (blocks edits outside a specified directory). Use for maximum safety +when touching prod or debugging live systems. Use when asked to "guard mode", +"full safety", "lock it down", or "maximum safety". + # /guard — Full Safety Mode Activates both destructive command warnings and directory-scoped edit restrictions. diff --git a/health/SKILL.md b/health/SKILL.md index 01d2a7e59..3343c5551 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -2,12 +2,7 @@ name: health preamble-tier: 2 version: 1.0.0 -description: | - Code quality dashboard. Wraps existing project tools (type checker, linter, - test runner, dead code detector, shell linter), computes a weighted composite - 0-10 score, and tracks trends over time. Use when: "health check", - "code quality", "how healthy is the codebase", "run all checks", - "quality score". (gstack) +description: Code quality dashboard. (gstack) triggers: - code health check - quality dashboard @@ -24,6 +19,15 @@ allowed-tools: + +## When to invoke this skill + +Wraps existing project tools (type checker, linter, +test runner, dead code detector, shell linter), computes a weighted composite +0-10 score, and tracks trends over time. Use when: "health check", +"code quality", "how healthy is the codebase", "run all checks", +"quality score". + ## Preamble (run first) ```bash diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 2f3542572..75400287e 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -2,14 +2,7 @@ name: investigate preamble-tier: 2 version: 1.0.0 -description: | - Systematic debugging with root cause investigation. Four phases: investigate, - analyze, hypothesize, implement. Iron Law: no fixes without root cause. - Use when asked to "debug this", "fix this bug", "why is this broken", - "investigate this error", or "root cause analysis". - Proactively invoke this skill (do NOT debug directly) when the user reports - errors, 500 errors, stack traces, unexpected behavior, "it was working - yesterday", or is troubleshooting why something stopped working. (gstack) +description: Systematic debugging with root cause investigation. (gstack) allowed-tools: - Bash - Read @@ -63,6 +56,17 @@ gbrain: + +## When to invoke this skill + +Four phases: investigate, +analyze, hypothesize, implement. Iron Law: no fixes without root cause. +Use when asked to "debug this", "fix this bug", "why is this broken", +"investigate this error", or "root cause analysis". +Proactively invoke this skill (do NOT debug directly) when the user reports +errors, 500 errors, stack traces, unexpected behavior, "it was working +yesterday", or is troubleshooting why something stopped working. + ## Preamble (run first) ```bash diff --git a/ios-clean/SKILL.md b/ios-clean/SKILL.md index 50dd4f424..77809e26b 100644 --- a/ios-clean/SKILL.md +++ b/ios-clean/SKILL.md @@ -2,15 +2,7 @@ name: ios-clean preamble-tier: 3 version: 1.0.0 -description: | - Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS - app. Cleans up StateServer, DebugOverlay, accessor codegen output, and - app-side hooks installed by /ios-qa. This is a convenience wrapper — - the structural Release-build guard (Package.swift conditional + CI - swift build -c release check) is the safety-critical path. - Use when asked to "clean the iOS debug bridge", "remove DebugBridge", - or "strip the gstack iOS instrumentation". (gstack) - Voice triggers (speech-to-text aliases): "clean the iOS debug bridge", "remove DebugBridge", "strip the gstack iOS instrumentation". +description: Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack) allowed-tools: - Bash - Read @@ -26,6 +18,18 @@ triggers: + +## When to invoke this skill + +Cleans up StateServer, DebugOverlay, accessor codegen output, and +app-side hooks installed by /ios-qa. This is a convenience wrapper — +the structural Release-build guard (Package.swift conditional + CI +swift build -c release check) is the safety-critical path. +Use when asked to "clean the iOS debug bridge", "remove DebugBridge", +or "strip the gstack iOS instrumentation". + +Voice triggers (speech-to-text aliases): "clean the iOS debug bridge", "remove DebugBridge", "strip the gstack iOS instrumentation". + ## Preamble (run first) ```bash diff --git a/ios-design-review/SKILL.md b/ios-design-review/SKILL.md index cca93c41d..0560719fe 100644 --- a/ios-design-review/SKILL.md +++ b/ios-design-review/SKILL.md @@ -2,17 +2,7 @@ name: ios-design-review preamble-tier: 3 version: 1.0.0 -description: | - Visual design audit for iOS apps on real hardware. Connects to a real - iPhone via the same StateServer as /ios-qa, screenshots every screen, - evaluates against Apple HIG, DESIGN.md, and design best practices. Scores - each dimension 0-10 with "what would make it a 10" framing — mirrors - /plan-design-review for browser. For plan-stage design review (before - implementation), use /plan-design-review. For live web visual audits, use - /design-review. - Use when asked to "review the iOS design", "audit the iPhone app's - visuals", or "design QA the iOS app". (gstack) - Voice triggers (speech-to-text aliases): "review the iOS design", "audit the iPhone app's visuals", "design QA the iPhone app". +description: Visual design audit for iOS apps on real hardware. (gstack) allowed-tools: - Bash - Read @@ -27,6 +17,21 @@ triggers: + +## When to invoke this skill + +Connects to a real +iPhone via the same StateServer as /ios-qa, screenshots every screen, +evaluates against Apple HIG, DESIGN.md, and design best practices. Scores +each dimension 0-10 with "what would make it a 10" framing — mirrors +/plan-design-review for browser. For plan-stage design review (before +implementation), use /plan-design-review. For live web visual audits, use +/design-review. +Use when asked to "review the iOS design", "audit the iPhone app's +visuals", or "design QA the iOS app". + +Voice triggers (speech-to-text aliases): "review the iOS design", "audit the iPhone app's visuals", "design QA the iPhone app". + ## Preamble (run first) ```bash diff --git a/ios-fix/SKILL.md b/ios-fix/SKILL.md index 36c83f71a..f0659bfa2 100644 --- a/ios-fix/SKILL.md +++ b/ios-fix/SKILL.md @@ -2,16 +2,7 @@ name: ios-fix preamble-tier: 3 version: 1.0.0 -description: | - Autonomous iOS bug fixer. Takes a bug found by /ios-qa, reads the source, - writes the fix, rebuilds, redeploys, and verifies the fix on the real - device. Closes the loop: find bug → fix bug → confirm fix — zero human - intervention. Captures the pre-bug state snapshot as a regression test - fixture, so the bug can never recur silently. - Use when /ios-qa reports a bug and you want it fixed automatically, or - when asked to "fix this iOS bug", "patch the iPhone app", or "auto-fix - the iOS issue". (gstack) - Voice triggers (speech-to-text aliases): "fix the iOS bug", "patch the iPhone app", "auto-fix the iOS issue". +description: Autonomous iOS bug fixer. (gstack) allowed-tools: - Bash - Read @@ -28,6 +19,20 @@ triggers: + +## When to invoke this skill + +Takes a bug found by /ios-qa, reads the source, +writes the fix, rebuilds, redeploys, and verifies the fix on the real +device. Closes the loop: find bug → fix bug → confirm fix — zero human +intervention. Captures the pre-bug state snapshot as a regression test +fixture, so the bug can never recur silently. +Use when /ios-qa reports a bug and you want it fixed automatically, or +when asked to "fix this iOS bug", "patch the iPhone app", or "auto-fix +the iOS issue". + +Voice triggers (speech-to-text aliases): "fix the iOS bug", "patch the iPhone app", "auto-fix the iOS issue". + ## Preamble (run first) ```bash diff --git a/ios-qa/SKILL.md b/ios-qa/SKILL.md index fabbc2100..347dab978 100644 --- a/ios-qa/SKILL.md +++ b/ios-qa/SKILL.md @@ -2,17 +2,7 @@ name: ios-qa preamble-tier: 3 version: 1.0.0 -description: | - Live-device iOS QA for SwiftUI apps. Connects to a real iPhone via USB - CoreDevice IPv6 tunnel, reads Swift source to understand every screen, then - runs a vision-driven agent loop: screenshot → analyze → decide → act → - verify → repeat. All interaction happens via HTTP to an embedded - StateServer in the app under test. Optionally exposes the device over - Tailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can - run iOS QA from anywhere without touching the hardware. - Use when asked to "ios qa", "test my iPhone app", "find bugs on the device", - or "qa the iOS app". (gstack) - Voice triggers (speech-to-text aliases): "iOS quality check", "test the iPhone app", "run iOS QA". +description: Live-device iOS QA for SwiftUI apps. (gstack) allowed-tools: - Bash - Read @@ -31,6 +21,21 @@ triggers: + +## When to invoke this skill + +Connects to a real iPhone via USB +CoreDevice IPv6 tunnel, reads Swift source to understand every screen, then +runs a vision-driven agent loop: screenshot → analyze → decide → act → +verify → repeat. All interaction happens via HTTP to an embedded +StateServer in the app under test. Optionally exposes the device over +Tailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can +run iOS QA from anywhere without touching the hardware. +Use when asked to "ios qa", "test my iPhone app", "find bugs on the device", +or "qa the iOS app". + +Voice triggers (speech-to-text aliases): "iOS quality check", "test the iPhone app", "run iOS QA". + ## Preamble (run first) ```bash diff --git a/ios-sync/SKILL.md b/ios-sync/SKILL.md index dc8e9fdb2..ce0c81929 100644 --- a/ios-sync/SKILL.md +++ b/ios-sync/SKILL.md @@ -2,14 +2,7 @@ name: ios-sync preamble-tier: 3 version: 1.0.0 -description: | - Regenerate the iOS debug bridge against the latest upstream gstack - templates. Updates StateServer.swift, DebugOverlay.swift, Package.swift, - and the typed @Observable state accessors. Use after you upgrade gstack - or add new ViewModels/properties that need accessor coverage. - Use when asked to "resync the iOS debug bridge", "regenerate iOS - accessors", or "update the gstack iOS instrumentation". (gstack) - Voice triggers (speech-to-text aliases): "resync the iOS debug bridge", "regenerate iOS accessors", "update the gstack iOS instrumentation". +description: Regenerate the iOS debug bridge against the latest upstream gstack templates. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Updates StateServer.swift, DebugOverlay.swift, Package.swift, +and the typed @Observable state accessors. Use after you upgrade gstack +or add new ViewModels/properties that need accessor coverage. +Use when asked to "resync the iOS debug bridge", "regenerate iOS +accessors", or "update the gstack iOS instrumentation". + +Voice triggers (speech-to-text aliases): "resync the iOS debug bridge", "regenerate iOS accessors", "update the gstack iOS instrumentation". + ## Preamble (run first) ```bash diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index d14f63623..3c67cbfe0 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -2,11 +2,7 @@ name: land-and-deploy preamble-tier: 4 version: 1.0.0 -description: | - Land and deploy workflow. Merges the PR, waits for CI and deploy, - verifies production health via canary checks. Takes over after /ship - creates the PR. Use when: "merge", "land", "deploy", "merge and verify", - "land it", "ship it to production". (gstack) +description: Land and deploy workflow. (gstack) allowed-tools: - Bash - Read @@ -21,6 +17,14 @@ triggers: + +## When to invoke this skill + +Merges the PR, waits for CI and deploy, +verifies production health via canary checks. Takes over after /ship +creates the PR. Use when: "merge", "land", "deploy", "merge and verify", +"land it", "ship it to production". + ## Preamble (run first) ```bash diff --git a/landing-report/SKILL.md b/landing-report/SKILL.md index dacab7834..921299863 100644 --- a/landing-report/SKILL.md +++ b/landing-report/SKILL.md @@ -1,12 +1,7 @@ --- name: landing-report version: 0.1.0 -description: | - Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots - are currently claimed by open PRs, which sibling Conductor workspaces have - WIP work likely to ship soon, and what slot /ship would pick next. No - mutations — just a snapshot. Use when asked to "landing report", "what's in - the queue", "show me open PRs", or "which version do I claim next". (gstack) +description: Read-only queue dashboard for workspace-aware ship. (gstack) triggers: - landing report - version queue @@ -20,6 +15,15 @@ allowed-tools: + +## When to invoke this skill + +Shows which VERSION slots +are currently claimed by open PRs, which sibling Conductor workspaces have +WIP work likely to ship soon, and what slot /ship would pick next. No +mutations — just a snapshot. Use when asked to "landing report", "what's in +the queue", "show me open PRs", or "which version do I claim next". + # /landing-report — Version Queue Dashboard ## Preamble (run first) diff --git a/learn/SKILL.md b/learn/SKILL.md index f7c68582e..8fe745816 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -2,12 +2,7 @@ name: learn preamble-tier: 2 version: 1.0.0 -description: | - Manage project learnings. Review, search, prune, and export what gstack - has learned across sessions. Use when asked to "what have we learned", - "show learnings", "prune stale learnings", or "export learnings". - Proactively suggest when the user asks about past patterns or wonders - "didn't we fix this before?" +description: Manage project learnings. triggers: - show learnings - what have we learned @@ -24,6 +19,15 @@ allowed-tools: + +## When to invoke this skill + +Review, search, prune, and export what gstack +has learned across sessions. Use when asked to "what have we learned", +"show learnings", "prune stale learnings", or "export learnings". +Proactively suggest when the user asks about past patterns or wonders +"didn't we fix this before?" + ## Preamble (run first) ```bash diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index 045e31516..f46b0d501 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -2,13 +2,7 @@ name: make-pdf preamble-tier: 1 version: 1.0.0 -description: | - Turn any markdown file into a publication-quality PDF. Proper 1in margins, - intelligent page breaks, page numbers, cover pages, running headers, curly - quotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft - artifact — a finished artifact. Use when asked to "make a PDF", "export to - PDF", "turn this markdown into a PDF", or "generate a document". (gstack) - Voice triggers (speech-to-text aliases): "make this a pdf", "make it a pdf", "export to pdf", "turn this into a pdf", "turn this markdown into a pdf", "generate a pdf", "make a pdf from", "pdf this markdown". +description: Turn any markdown file into a publication-quality PDF. (gstack) triggers: - markdown to pdf - generate pdf @@ -22,6 +16,17 @@ allowed-tools: + +## When to invoke this skill + +Proper 1in margins, +intelligent page breaks, page numbers, cover pages, running headers, curly +quotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft +artifact — a finished artifact. Use when asked to "make a PDF", "export to +PDF", "turn this markdown into a PDF", or "generate a document". + +Voice triggers (speech-to-text aliases): "make this a pdf", "make it a pdf", "export to pdf", "turn this into a pdf", "turn this markdown into a pdf", "generate a pdf", "make a pdf from", "pdf this markdown". + ## Preamble (run first) ```bash diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 10e292941..b44ef3e10 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -2,18 +2,7 @@ name: office-hours preamble-tier: 3 version: 2.0.0 -description: | - YC Office Hours — two modes. Startup mode: six forcing questions that expose - demand reality, status quo, desperate specificity, narrowest wedge, observation, - and future-fit. Builder mode: design thinking brainstorming for side projects, - hackathons, learning, and open source. Saves a design doc. - Use when asked to "brainstorm this", "I have an idea", "help me think through - this", "office hours", or "is this worth building". - Proactively invoke this skill (do NOT answer directly) when the user describes - a new product idea, asks whether something is worth building, wants to think - through design decisions for something that doesn't exist yet, or is exploring - a concept before any code is written. - Use before /plan-ceo-review or /plan-eng-review. (gstack) +description: YC Office Hours — two modes. (gstack) allowed-tools: - Bash - Read @@ -59,6 +48,21 @@ gbrain: + +## When to invoke this skill + +Startup mode: six forcing questions that expose +demand reality, status quo, desperate specificity, narrowest wedge, observation, +and future-fit. Builder mode: design thinking brainstorming for side projects, +hackathons, learning, and open source. Saves a design doc. +Use when asked to "brainstorm this", "I have an idea", "help me think through +this", "office hours", or "is this worth building". +Proactively invoke this skill (do NOT answer directly) when the user describes +a new product idea, asks whether something is worth building, wants to think +through design decisions for something that doesn't exist yet, or is exploring +a concept before any code is written. +Use before /plan-ceo-review or /plan-eng-review. + ## Preamble (run first) ```bash diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index b93215ead..bb9f808ee 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -1,13 +1,7 @@ --- name: open-gstack-browser version: 0.2.0 -description: | - Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. - Opens a visible browser window where you can watch every action in real time. - The sidebar shows a live activity feed and chat. Anti-bot stealth built in. - Use when asked to "open gstack browser", "launch browser", "connect chrome", - "open chrome", "real browser", "launch chrome", "side panel", or "control my browser". - Voice triggers (speech-to-text aliases): "show me the browser". +description: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. triggers: - open gstack browser - launch chromium @@ -21,6 +15,16 @@ allowed-tools: + +## When to invoke this skill + +Opens a visible browser window where you can watch every action in real time. +The sidebar shows a live activity feed and chat. Anti-bot stealth built in. +Use when asked to "open gstack browser", "launch browser", "connect chrome", +"open chrome", "real browser", "launch chrome", "side panel", or "control my browser". + +Voice triggers (speech-to-text aliases): "show me the browser". + ## Preamble (run first) ```bash diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index aba0ab2d7..0f6a75c54 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -1,14 +1,7 @@ --- name: pair-agent version: 0.1.0 -description: | - Pair a remote AI agent with your browser. One command generates a setup key and - prints instructions the other agent can follow to connect. Works with OpenClaw, - Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent - gets its own tab with scoped access (read+write by default, admin on request). - Use when asked to "pair agent", "connect agent", "share browser", "remote browser", - "let another agent use my browser", or "give browser access". (gstack) - Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access". +description: Pair a remote AI agent with your browser. (gstack) triggers: - pair with agent - connect remote agent @@ -22,6 +15,18 @@ allowed-tools: + +## When to invoke this skill + +One command generates a setup key and +prints instructions the other agent can follow to connect. Works with OpenClaw, +Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent +gets its own tab with scoped access (read+write by default, admin on request). +Use when asked to "pair agent", "connect agent", "share browser", "remote browser", +"let another agent use my browser", or "give browser access". + +Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access". + ## Preamble (run first) ```bash diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 12870bd8f..e0d269709 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -3,15 +3,7 @@ name: plan-ceo-review preamble-tier: 3 interactive: true version: 1.0.0 -description: | - CEO/founder-mode plan review. Rethink the problem, find the 10-star product, - 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". - Proactively suggest when the user is questioning scope or ambition of a plan, - or when the plan feels like it could be thinking bigger. (gstack) +description: CEO/founder-mode plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -53,6 +45,18 @@ gbrain: + +## When to invoke this skill + +Rethink the problem, find the 10-star product, +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". +Proactively suggest when the user is questioning scope or ambition of a plan, +or when the plan feels like it could be thinking bigger. + ## Preamble (run first) ```bash diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 42efe541f..de71e18c1 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -3,14 +3,7 @@ name: plan-design-review preamble-tier: 3 interactive: true version: 2.0.0 -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. Use when asked to "review the design plan" - or "design critique". - Proactively suggest when the user has a plan with UI/UX components that - should be reviewed before implementation. (gstack) +description: Designer's eye plan review — interactive, like CEO and Eng review. (gstack) allowed-tools: - Read - Edit @@ -26,6 +19,16 @@ triggers: + +## When to invoke this skill + +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. Use when asked to "review the design plan" +or "design critique". +Proactively suggest when the user has a plan with UI/UX components that +should be reviewed before implementation. + ## Preamble (run first) ```bash diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index d7cc26f30..cacd8f76f 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -3,16 +3,7 @@ name: plan-devex-review preamble-tier: 3 interactive: true version: 2.0.0 -description: | - Interactive developer experience plan review. Explores developer personas, - benchmarks against competitors, designs magical moments, and traces friction - points before scoring. Three modes: DX EXPANSION (competitive advantage), - DX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only). - Use when asked to "DX review", "developer experience audit", "devex review", - or "API design review". - Proactively suggest when the user has a plan for developer-facing products - (APIs, CLIs, SDKs, libraries, platforms, docs). (gstack) - Voice triggers (speech-to-text aliases): "dx review", "developer experience review", "devex review", "devex audit", "API design review", "onboarding review". +description: Interactive developer experience plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -30,6 +21,20 @@ triggers: + +## When to invoke this skill + +Explores developer personas, +benchmarks against competitors, designs magical moments, and traces friction +points before scoring. Three modes: DX EXPANSION (competitive advantage), +DX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only). +Use when asked to "DX review", "developer experience audit", "devex review", +or "API design review". +Proactively suggest when the user has a plan for developer-facing products +(APIs, CLIs, SDKs, libraries, platforms, docs). + +Voice triggers (speech-to-text aliases): "dx review", "developer experience review", "devex review", "devex audit", "API design review", "onboarding review". + ## Preamble (run first) ```bash diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 9a6cf913d..66edf982a 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -3,14 +3,7 @@ name: plan-eng-review preamble-tier: 3 interactive: true 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. Use when asked to - "review the architecture", "engineering review", or "lock in the plan". - Proactively suggest when the user has a plan or design doc and is about to - start coding — to catch architecture issues before implementation. (gstack) - Voice triggers (speech-to-text aliases): "tech review", "technical review", "plan engineering review". +description: Eng manager-mode plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -28,6 +21,18 @@ triggers: + +## When to invoke this skill + +Lock in the execution plan — architecture, +data flow, diagrams, edge cases, test coverage, performance. Walks through +issues interactively with opinionated recommendations. Use when asked to +"review the architecture", "engineering review", or "lock in the plan". +Proactively suggest when the user has a plan or design doc and is about to +start coding — to catch architecture issues before implementation. + +Voice triggers (speech-to-text aliases): "tech review", "technical review", "plan engineering review". + ## Preamble (run first) ```bash diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index 2fc40e52c..f56fb5b43 100644 --- a/plan-tune/SKILL.md +++ b/plan-tune/SKILL.md @@ -2,19 +2,7 @@ name: plan-tune preamble-tier: 2 version: 1.0.0 -description: | - Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). - Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences - (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track - profile (what you declared vs what your behavior suggests), and enable/disable - question tuning. Conversational interface — no CLI syntax required. - - Use when asked to "tune questions", "stop asking me that", "too many questions", - "show my profile", "what questions have I been asked", "show my vibe", - "developer profile", or "turn off question tuning". (gstack) - - Proactively suggest when the user says the same gstack question has come up before, - or when they explicitly override a recommendation for the Nth time. +description: Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). (gstack) triggers: - tune questions - stop asking me that @@ -35,6 +23,21 @@ allowed-tools: + +## When to invoke this skill + +Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences +(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track +profile (what you declared vs what your behavior suggests), and enable/disable +question tuning. Conversational interface — no CLI syntax required. + +Use when asked to "tune questions", "stop asking me that", "too many questions", +"show my profile", "what questions have I been asked", "show my vibe", +"developer profile", or "turn off question tuning". + +Proactively suggest when the user says the same gstack question has come up before, +or when they explicitly override a recommendation for the Nth time. + ## Preamble (run first) ```bash diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 9e49cd432..b04749f63 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -2,13 +2,7 @@ name: qa-only preamble-tier: 4 version: 1.0.0 -description: | - Report-only QA testing. Systematically tests a web application and produces a - structured report with health score, screenshots, and repro steps — but never - fixes anything. Use when asked to "just report bugs", "qa report only", or - "test but don't fix". For the full test-fix-verify loop, use /qa instead. - Proactively suggest when the user wants a bug report without any code changes. (gstack) - Voice triggers (speech-to-text aliases): "bug report", "just check for bugs". +description: Report-only QA testing. (gstack) allowed-tools: - Bash - Read @@ -23,6 +17,17 @@ triggers: + +## When to invoke this skill + +Systematically tests a web application and produces a +structured report with health score, screenshots, and repro steps — but never +fixes anything. Use when asked to "just report bugs", "qa report only", or +"test but don't fix". For the full test-fix-verify loop, use /qa instead. +Proactively suggest when the user wants a bug report without any code changes. + +Voice triggers (speech-to-text aliases): "bug report", "just check for bugs". + ## Preamble (run first) ```bash diff --git a/qa/SKILL.md b/qa/SKILL.md index 744a8c957..3832f01ac 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -2,16 +2,7 @@ name: qa preamble-tier: 4 version: 2.0.0 -description: | - Systematically QA test a web application and fix bugs found. Runs QA testing, - then iteratively fixes bugs in source code, committing each fix atomically and - re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs", - "test and fix", or "fix what's broken". - Proactively suggest when the user says a feature is ready for testing - or asks "does this work?". Three tiers: Quick (critical/high only), - Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores, - fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. (gstack) - Voice triggers (speech-to-text aliases): "quality check", "test the app", "run QA". +description: Systematically QA test a web application and fix bugs found. (gstack) allowed-tools: - Bash - Read @@ -29,6 +20,20 @@ triggers: + +## When to invoke this skill + +Runs QA testing, +then iteratively fixes bugs in source code, committing each fix atomically and +re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs", +"test and fix", or "fix what's broken". +Proactively suggest when the user says a feature is ready for testing +or asks "does this work?". Three tiers: Quick (critical/high only), +Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores, +fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. + +Voice triggers (speech-to-text aliases): "quality check", "test the app", "run QA". + ## Preamble (run first) ```bash diff --git a/retro/SKILL.md b/retro/SKILL.md index a7e4a3402..cffb82cf3 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -2,12 +2,7 @@ name: retro preamble-tier: 2 version: 2.0.0 -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". - Proactively suggest at the end of a work week or sprint. (gstack) +description: Weekly engineering retrospective. (gstack) allowed-tools: - Bash - Read @@ -41,6 +36,15 @@ gbrain: + +## When to invoke this skill + +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". +Proactively suggest at the end of a work week or sprint. + ## Preamble (run first) ```bash diff --git a/review/SKILL.md b/review/SKILL.md index 14ef17d49..fe505daee 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -2,11 +2,7 @@ name: review preamble-tier: 4 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. Use when - asked to "review this PR", "code review", "pre-landing review", or "check my diff". - Proactively suggest when the user is about to merge or land code changes. (gstack) +description: Pre-landing PR review. (gstack) allowed-tools: - Bash - Read @@ -26,6 +22,14 @@ triggers: + +## When to invoke this skill + +Analyzes diff against the base branch for SQL safety, LLM trust +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". +Proactively suggest when the user is about to merge or land code changes. + ## Preamble (run first) ```bash diff --git a/scrape/SKILL.md b/scrape/SKILL.md index dd38bc208..024d634e5 100644 --- a/scrape/SKILL.md +++ b/scrape/SKILL.md @@ -1,13 +1,7 @@ --- name: scrape version: 1.0.0 -description: | - Pull data from a web page. First call on a new intent prototypes the flow - via $B primitives and returns JSON. Subsequent calls on a matching intent - route to a codified browser-skill and return in ~200ms. Read-only — for - mutating flows (form fills, clicks, submissions), use /automate. - Use when asked to "scrape", "get data from", "pull", "extract from", or - "what's on" a page. (gstack) +description: Pull data from a web page. (gstack) allowed-tools: - Bash - Read @@ -22,6 +16,16 @@ triggers: + +## When to invoke this skill + +First call on a new intent prototypes the flow +via $B primitives and returns JSON. Subsequent calls on a matching intent +route to a codified browser-skill and return in ~200ms. Read-only — for +mutating flows (form fills, clicks, submissions), use /automate. +Use when asked to "scrape", "get data from", "pull", "extract from", or +"what's on" a page. + ## Preamble (run first) ```bash diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index c8822fbab..bde328a1a 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -59,6 +59,23 @@ const MODEL_ARG_VAL: Model = (() => { return resolved; })(); +// ─── Catalog Mode (v1.45.0.0 T4) ──────────────────────────── +// 'trim' (default): shorten frontmatter description to lead sentence, +// move routing/voice prose into a "## When to invoke" body section, and +// emit scripts/proactive-suggestions.json (single file across all skills). +// 'full': legacy v1.44 behavior — full description stays in frontmatter. +const CATALOG_MODE_ARG = process.argv.find(a => a.startsWith('--catalog-mode')); +const CATALOG_MODE: 'trim' | 'full' = (() => { + if (!CATALOG_MODE_ARG) return 'trim'; + const val = CATALOG_MODE_ARG.includes('=') + ? CATALOG_MODE_ARG.split('=')[1] + : process.argv[process.argv.indexOf(CATALOG_MODE_ARG) + 1]; + if (val !== 'trim' && val !== 'full') { + throw new Error(`Unknown catalog mode: ${val}. Use 'trim' (default) or 'full'.`); + } + return val; +})(); + // ─── Explain-level Overlay ────────────────────────────────── // --explain-level=terse compresses preamble prose (writing-style, completeness, // confusion-protocol, context-health) to a single pointer line at gen time. @@ -190,6 +207,160 @@ function processVoiceTriggers(content: string): string { // Export for testing export { extractVoiceTriggers, processVoiceTriggers }; +// ─── Catalog Trim (v1.45.0.0 T4) ───────────────────────────── +// +// Frontmatter `description:` blocks today pack: a one-line outcome, "Use when +// asked to..." voice triggers, "Proactively..." routing guidance, and a +// "(gstack)" tag. This pile is the always-loaded catalog surface — every +// session pays for the full text. The catalog trim splits the description +// into a one-line catalog entry (lead sentence + "(gstack)") that stays in +// the frontmatter, and a "## When to invoke" body section that holds the +// routing/voice triggers prose for in-skill discovery. A registry written +// to scripts/proactive-suggestions.json (one entry per skill) makes routing +// available to agents that need it without paying the always-loaded cost. +// +// Opt-out: `--catalog-mode=full` keeps v1.44 behavior (no trim, full +// description in frontmatter). Use when debugging routing regressions or +// when shipping skills to hosts that depend on the legacy fat catalog. + +export interface CatalogParts { + lead: string; // First sentence — kept in catalog + routingProse: string; // "Use when asked to...", "Proactively..." paragraphs + voiceLine: string | null; // "Voice triggers (speech-to-text aliases): ..." line if present + hasGstackTag: boolean; +} + +export function splitCatalogDescription(description: string): CatalogParts { + // Voice triggers line (folded in by processVoiceTriggers earlier) + const voiceMatch = description.match(/Voice triggers \(speech-to-text aliases\):[^\n]+/); + const voiceLine = voiceMatch ? voiceMatch[0] : null; + let working = voiceLine ? description.replace(voiceLine, '').trim() : description.trim(); + + const hasGstackTag = /\(gstack\)/.test(working); + if (hasGstackTag) working = working.replace(/\(gstack\)/, '').trim(); + + // Lead = first sentence (up to first period followed by space or end of string). + // We tolerate sentences with embedded periods (URLs, "v1.45.0.0") by requiring + // the period to be followed by whitespace OR end-of-text. + // First normalize to single-line for sentence detection, then back out. + const collapsed = working.replace(/\s+/g, ' ').trim(); + const sentenceMatch = collapsed.match(/^([^.!?]*[.!?])(?:\s|$)/); + let lead = sentenceMatch ? sentenceMatch[1].trim() : collapsed.split(/\s/).slice(0, 20).join(' '); + + // If the lead would be too long, trim to the first 140 chars at a word boundary + if (lead.length > 200) { + const trunc = lead.slice(0, 197); + const lastSpace = trunc.lastIndexOf(' '); + lead = (lastSpace > 60 ? trunc.slice(0, lastSpace) : trunc) + '...'; + } + + const leadInCollapsed = collapsed.indexOf(lead); + const routingCollapsed = leadInCollapsed >= 0 + ? collapsed.slice(leadInCollapsed + lead.length).trim() + : ''; + // Restore line breaks for routing prose by mapping back to original layout. + // Use original whitespace structure where possible; fall back to collapsed. + let routingProse = routingCollapsed; + // Try to recover the multi-line layout: split working at the lead boundary. + const collapsedLeadIdx = working.replace(/\s+/g, ' ').indexOf(lead); + if (collapsedLeadIdx >= 0) { + // Walk the original working string until we've consumed lead.length collapsed chars + let consumed = 0; + let cut = 0; + for (let i = 0; i < working.length && consumed < collapsedLeadIdx + lead.length; i++) { + if (/\s/.test(working[i])) { + if (i === 0 || /\s/.test(working[i - 1])) continue; + consumed += 1; + } else { + consumed += 1; + } + cut = i + 1; + } + const tail = working.slice(cut).trim(); + if (tail.length > 0) routingProse = tail; + } + + return { lead, routingProse, voiceLine, hasGstackTag }; +} + +/** Build the catalog-trimmed `description:` block. */ +export function buildTrimmedDescription(parts: CatalogParts): string { + const lead = parts.lead.trim(); + const suffix = parts.hasGstackTag ? ' (gstack)' : ''; + return `${lead}${suffix}`; +} + +/** Build the body section that holds the routing/voice prose. */ +export function buildWhenToInvokeSection(parts: CatalogParts): string { + const lines: string[] = ['## When to invoke this skill', '']; + if (parts.routingProse) { + lines.push(parts.routingProse); + lines.push(''); + } + if (parts.voiceLine) { + lines.push(parts.voiceLine); + lines.push(''); + } + return lines.join('\n'); +} + +/** + * Apply catalog trim to a SKILL.md body: + * - shorten frontmatter `description:` to lead + (gstack) + * - insert "## When to invoke" body section AFTER the generated header + * (so it lands near the top of body content, where routing guidance + * belongs) + * + * Returns the rewritten content plus the parts (used for proactive-suggestions + * JSON aggregation at the end of the run). + */ +export function applyCatalogTrim(content: string, skillName: string): { content: string; parts: CatalogParts } | null { + // Locate description block in frontmatter + if (!content.startsWith('---\n')) return null; + const fmEnd = content.indexOf('\n---', 4); + if (fmEnd === -1) return null; + const frontmatter = content.slice(4, fmEnd); + + // Match `description: |` block + indented body lines + const descMatch = frontmatter.match(/^description:\s*\|?\s*\n((?:\s{2,}.*(?:\n|$))+)/m) + || frontmatter.match(/^description:\s+(.+)$/m); + if (!descMatch) return null; + + // Extract full description text + let descText: string; + if (descMatch[0].startsWith('description: |') || /^description:\s*\|/.test(descMatch[0])) { + descText = descMatch[1].split('\n').map(l => l.replace(/^\s{2}/, '')).join('\n').trim(); + } else { + descText = descMatch[1].trim(); + } + + // Skip skills with very short descriptions (already trimmed or no routing prose). + // Below ~120 chars, splitting adds no value. + if (descText.length < 120) return null; + + const parts = splitCatalogDescription(descText); + // If lead + (gstack) is already most of the text, no trim needed. + const trimmedLen = buildTrimmedDescription(parts).length; + if (trimmedLen >= descText.length - 20) return null; + + // Replace description in frontmatter — keep trailing newline so the next + // YAML field doesn't collide on the same line as the description value. + const newDesc = buildTrimmedDescription(parts); + const newFrontmatter = frontmatter.replace(descMatch[0], `description: ${newDesc}\n`); + let newContent = '---\n' + newFrontmatter + content.slice(fmEnd); + + // Insert body section after frontmatter (after the closing ---\n and any + // existing GENERATED header). We insert before the first non-comment line. + const bodyStart = newContent.indexOf('\n---\n') + 5; + const whenToInvoke = '\n' + buildWhenToInvokeSection(parts).trim() + '\n'; + // Skip past the generated header if present (it lives after frontmatter close) + const headerMatch = newContent.slice(bodyStart).match(/^(\s*\n)+/); + const insertAt = bodyStart + (headerMatch ? headerMatch[0].length : 0); + newContent = newContent.slice(0, insertAt) + whenToInvoke + '\n' + newContent.slice(insertAt); + + return { content: newContent, parts }; +} + const OPENAI_SHORT_DESCRIPTION_LIMIT = 120; function condenseOpenAIShortDescription(description: string): string { @@ -419,7 +590,7 @@ function processExternalHost( return { content: result, outputPath, outputDir, symlinkLoop }; } -function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: string; content: string; symlinkLoop?: boolean } { +function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: string; content: string; symlinkLoop?: boolean; catalogParts?: CatalogParts | null } { const tmplContent = fs.readFileSync(tmplPath, 'utf-8'); const relTmplPath = path.relative(ROOT, tmplPath); let outputPath = tmplPath.replace(/\.tmpl$/, ''); @@ -503,7 +674,17 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: content = header + content; } - return { outputPath, content, symlinkLoop }; + // Catalog trim (Claude only — external hosts have their own frontmatter shapes) + let catalogParts: CatalogParts | null = null; + if (host === 'claude' && CATALOG_MODE === 'trim') { + const trimmed = applyCatalogTrim(content, skillName); + if (trimmed) { + content = trimmed.content; + catalogParts = trimmed.parts; + } + } + + return { outputPath, content, symlinkLoop, catalogParts }; } // ─── Main ─────────────────────────────────────────────────── @@ -523,6 +704,14 @@ for (const currentHost of hostsToRun) { let hasChanges = false; const tokenBudget: Array<{ skill: string; lines: number; tokens: number }> = []; + // T4 catalog trim: collect routing/voice parts across all Claude skills, + // then write scripts/proactive-suggestions.json once per gen-skill-docs run. + const proactiveAggregate: Record = {}; + const currentHostConfig = getHostConfig(currentHost); for (const tmplPath of findTemplates()) { const dir = path.basename(path.dirname(tmplPath)); @@ -536,7 +725,15 @@ for (const currentHost of hostsToRun) { if (currentHostConfig.generation.skipSkills.includes(dir)) continue; } - const { outputPath, content, symlinkLoop } = processTemplate(tmplPath, currentHost); + const { outputPath, content, symlinkLoop, catalogParts } = processTemplate(tmplPath, currentHost); + if (catalogParts) { + const key = dir === '' ? 'gstack' : dir; + proactiveAggregate[key] = { + lead: catalogParts.lead, + routing: catalogParts.routingProse, + voice_line: catalogParts.voiceLine, + }; + } const relOutput = path.relative(ROOT, outputPath); if (symlinkLoop) { @@ -640,6 +837,21 @@ The orchestrator will persist the plan link to its own memory/knowledge store. failures.push({ host: currentHost, error: new Error('Stale files detected') }); } + // T4 catalog trim: write aggregated proactive-suggestions.json (Claude only). + // The JSON registry lets agents pull voice triggers / routing prose for any + // skill on demand instead of paying for it always-loaded in the catalog. + if (currentHost === 'claude' && CATALOG_MODE === 'trim' && Object.keys(proactiveAggregate).length > 0 && !DRY_RUN) { + const proactivePath = path.join(ROOT, 'scripts', 'proactive-suggestions.json'); + const payload = { + $schema: 'https://gstack.dev/schemas/proactive-suggestions.json', + generated_at: new Date().toISOString(), + catalog_mode: 'trim', + note: 'Routing / voice-trigger prose extracted from SKILL.md frontmatter descriptions during catalog trim. Loaded on demand when routing guidance is needed.', + skills: proactiveAggregate, + }; + fs.writeFileSync(proactivePath, JSON.stringify(payload, null, 2) + '\n'); + } + // Print token budget summary if (!DRY_RUN && tokenBudget.length > 0) { tokenBudget.sort((a, b) => b.lines - a.lines); diff --git a/scripts/proactive-suggestions.json b/scripts/proactive-suggestions.json new file mode 100644 index 000000000..1d622afc0 --- /dev/null +++ b/scripts/proactive-suggestions.json @@ -0,0 +1,268 @@ +{ + "$schema": "https://gstack.dev/schemas/proactive-suggestions.json", + "generated_at": "2026-05-26T03:35:08.717Z", + "catalog_mode": "trim", + "note": "Routing / voice-trigger prose extracted from SKILL.md frontmatter descriptions during catalog trim. Loaded on demand when routing guidance is needed.", + "skills": { + "seville-v3": { + "lead": "Fast headless browser for QA testing and site dogfooding.", + "routing": "Navigate pages, interact with\nelements, verify state, diff before/after, take annotated screenshots, test responsive\nlayouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or\ntest a site, verify a deployment, dogfood a user flow, or file a bug with screenshots.", + "voice_line": null + }, + "pair-agent": { + "lead": "Pair a remote AI agent with your browser.", + "routing": "One command generates a setup key and\nprints instructions the other agent can follow to connect. Works with OpenClaw,\nHermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent\ngets its own tab with scoped access (read+write by default, admin on request).\nUse when asked to \"pair agent\", \"connect agent\", \"share browser\", \"remote browser\",\n\"let another agent use my browser\", or \"give browser access\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"pair agent\", \"connect agent\", \"share my browser\", \"remote browser access\"." + }, + "benchmark": { + "lead": "Performance regression detection using the browse daemon.", + "routing": "Establishes\nbaselines for page load times, Core Web Vitals, and resource sizes.\nCompares before/after on every PR. Tracks performance trends over time.\nUse when: \"performance\", \"benchmark\", \"page speed\", \"lighthouse\", \"web vitals\",\n\"bundle size\", \"load time\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"speed test\", \"check performance\"." + }, + "design-html": { + "lead": "Design finalization: generates production-quality Pretext-native HTML/CSS.", + "routing": "Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review,\ndesign review context from /plan-design-review, or from scratch with a user\ndescription. Text actually reflows, heights are computed, layouts are dynamic.\n30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns\nfor each design type. Use when: \"finalize this design\", \"turn this into HTML\",\n\"build me a page\", \"implement this design\", or after any planning skill.\nProactively suggest when user has approved a design or has a plan ready.", + "voice_line": "Voice triggers (speech-to-text aliases): \"build the design\", \"code the mockup\", \"make it real\"." + }, + "plan-tune": { + "lead": "Self-tuning question sensitivity + developer psychographic for gstack (v1: observational).", + "routing": "Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences\n(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track\nprofile (what you declared vs what your behavior suggests), and enable/disable\nquestion tuning. Conversational interface — no CLI syntax required.\n\nUse when asked to \"tune questions\", \"stop asking me that\", \"too many questions\",\n\"show my profile\", \"what questions have I been asked\", \"show my vibe\",\n\"developer profile\", or \"turn off question tuning\". \n\nProactively suggest when the user says the same gstack question has come up before,\nor when they explicitly override a recommendation for the Nth time.", + "voice_line": null + }, + "design-shotgun": { + "lead": "Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate.", + "routing": "Standalone design exploration you can\nrun anytime. Use when: \"explore designs\", \"show me options\", \"design variants\",\n\"visual brainstorm\", or \"I don't like how this looks\".\nProactively suggest when the user describes a UI feature but hasn't seen\nwhat it could look like.", + "voice_line": null + }, + "plan-design-review": { + "lead": "Designer's eye plan review — interactive, like CEO and Eng review.", + "routing": "Rates each design dimension 0-10, explains what would make it a 10,\nthen fixes the plan to get there. Works in plan mode. For live site\nvisual audits, use /design-review. Use when asked to \"review the design plan\"\nor \"design critique\".\nProactively suggest when the user has a plan with UI/UX components that\nshould be reviewed before implementation.", + "voice_line": null + }, + "autoplan": { + "lead": "Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk and runs them sequentially with auto-decisions using 6 decision principles.", + "routing": "Surfaces\ntaste decisions (close approaches, borderline scope, codex disagreements) at a final\napproval gate. One command, fully reviewed plan out.\nUse when asked to \"auto review\", \"autoplan\", \"run all reviews\", \"review this plan\nautomatically\", or \"make the decisions for me\".\nProactively suggest when the user has a plan file and wants to run the full review\ngauntlet without answering 15-30 intermediate questions.", + "voice_line": "Voice triggers (speech-to-text aliases): \"auto plan\", \"automatic review\"." + }, + "design-consultation": { + "lead": "Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview...", + "routing": "", + "voice_line": null + }, + "learn": { + "lead": "Manage project learnings.", + "routing": "Review, search, prune, and export what gstack\nhas learned across sessions. Use when asked to \"what have we learned\",\n\"show learnings\", \"prune stale learnings\", or \"export learnings\".\nProactively suggest when the user asks about past patterns or wonders\n\"didn't we fix this before?\"", + "voice_line": null + }, + "freeze": { + "lead": "Restrict file edits to a specific directory for the session.", + "routing": "Blocks Edit and\nWrite outside the allowed path. Use when debugging to prevent accidentally\n\"fixing\" unrelated code, or when you want to scope changes to one module.\nUse when asked to \"freeze\", \"restrict edits\", \"only edit this folder\",\nor \"lock down edits\".", + "voice_line": null + }, + "ios-qa": { + "lead": "Live-device iOS QA for SwiftUI apps.", + "routing": "Connects to a real iPhone via USB\nCoreDevice IPv6 tunnel, reads Swift source to understand every screen, then\nruns a vision-driven agent loop: screenshot → analyze → decide → act →\nverify → repeat. All interaction happens via HTTP to an embedded\nStateServer in the app under test. Optionally exposes the device over\nTailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can\nrun iOS QA from anywhere without touching the hardware.\nUse when asked to \"ios qa\", \"test my iPhone app\", \"find bugs on the device\",\nor \"qa the iOS app\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"iOS quality check\", \"test the iPhone app\", \"run iOS QA\"." + }, + "careful": { + "lead": "Safety guardrails for destructive commands.", + "routing": "Warns before rm -rf, DROP TABLE,\nforce-push, git reset --hard, kubectl delete, and similar destructive operations.\nUser can override each warning. Use when touching prod, debugging live systems,\nor working in a shared environment. Use when asked to \"be careful\", \"safety mode\",\n\"prod mode\", or \"careful mode\".", + "voice_line": null + }, + "cso": { + "lead": "Chief Security Officer mode.", + "routing": "Infrastructure-first security audit: secrets archaeology,\ndependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain\nscanning, plus OWASP Top 10, STRIDE threat modeling, and active verification.\nTwo modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep\nscan, 2/10 bar). Trend tracking across audit runs.\nUse when: \"security audit\", \"threat model\", \"pentest review\", \"OWASP\", \"CSO review\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"see-so\", \"see so\", \"security review\", \"security check\", \"vulnerability scan\", \"run security\"." + }, + "canary": { + "lead": "Post-deploy canary monitoring.", + "routing": "Watches the live app for console errors,\nperformance regressions, and page failures using the browse daemon. Takes\nperiodic screenshots, compares against pre-deploy baselines, and alerts\non anomalies. Use when: \"monitor deploy\", \"canary\", \"post-deploy check\",\n\"watch production\", \"verify deploy\".", + "voice_line": null + }, + "open-gstack-browser": { + "lead": "Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.", + "routing": "Opens a visible browser window where you can watch every action in real time.\nThe sidebar shows a live activity feed and chat. Anti-bot stealth built in.\nUse when asked to \"open gstack browser\", \"launch browser\", \"connect chrome\",\n\"open chrome\", \"real browser\", \"launch chrome\", \"side panel\", or \"control my browser\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"show me the browser\"." + }, + "investigate": { + "lead": "Systematic debugging with root cause investigation.", + "routing": "Four phases: investigate,\nanalyze, hypothesize, implement. Iron Law: no fixes without root cause.\nUse when asked to \"debug this\", \"fix this bug\", \"why is this broken\",\n\"investigate this error\", or \"root cause analysis\".\nProactively invoke this skill (do NOT debug directly) when the user reports\nerrors, 500 errors, stack traces, unexpected behavior, \"it was working\nyesterday\", or is troubleshooting why something stopped working.", + "voice_line": null + }, + "context-restore": { + "lead": "Restore working context saved earlier by /context-save.", + "routing": "Loads the most recent\nsaved state (across all branches by default) so you can pick up where you\nleft off — even across Conductor workspace handoffs.\nUse when asked to \"resume\", \"restore context\", \"where was I\", or\n\"pick up where I left off\". Pair with /context-save.\nFormerly /checkpoint resume — renamed because Claude Code treats /checkpoint\nas a native rewind alias in current environments.", + "voice_line": null + }, + "document-release": { + "lead": "Post-ship documentation update.", + "routing": "Reads all project docs, cross-references the\ndiff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),\nupdates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,\ndetects architecture diagram drift, polishes CHANGELOG voice with a sell-test\nrubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation\ndebt in the PR body. Use when asked to \"update the docs\", \"sync documentation\",\nor \"post-ship docs\". Proactively suggest after a PR is merged or code is shipped.", + "voice_line": null + }, + "health": { + "lead": "Code quality dashboard.", + "routing": "Wraps existing project tools (type checker, linter,\ntest runner, dead code detector, shell linter), computes a weighted composite\n0-10 score, and tracks trends over time. Use when: \"health check\",\n\"code quality\", \"how healthy is the codebase\", \"run all checks\",\n\"quality score\".", + "voice_line": null + }, + "gstack-upgrade": { + "lead": "Upgrade gstack to the latest version.", + "routing": "Detects global vs vendored install,\nruns the upgrade, and shows what's new. Use when asked to \"upgrade gstack\",\n\"update gstack\", or \"get latest version\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"upgrade the tools\", \"update the tools\", \"gee stack upgrade\", \"g stack upgrade\"." + }, + "land-and-deploy": { + "lead": "Land and deploy workflow.", + "routing": "Merges the PR, waits for CI and deploy,\nverifies production health via canary checks. Takes over after /ship\ncreates the PR. Use when: \"merge\", \"land\", \"deploy\", \"merge and verify\",\n\"land it\", \"ship it to production\".", + "voice_line": null + }, + "codex": { + "lead": "OpenAI Codex CLI wrapper — three modes.", + "routing": "Code review: independent diff review via\ncodex review with pass/fail gate. Challenge: adversarial mode that tries to break\nyour code. Consult: ask codex anything with session continuity for follow-ups.\nThe \"200 IQ autistic developer\" second opinion. Use when asked to \"codex review\",\n\"codex challenge\", \"ask codex\", \"second opinion\", or \"consult codex\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"code x\", \"code ex\", \"get another opinion\"." + }, + "qa": { + "lead": "Systematically QA test a web application and fix bugs found.", + "routing": "Runs QA testing,\nthen iteratively fixes bugs in source code, committing each fix atomically and\nre-verifying. Use when asked to \"qa\", \"QA\", \"test this site\", \"find bugs\",\n\"test and fix\", or \"fix what's broken\".\nProactively suggest when the user says a feature is ready for testing\nor asks \"does this work?\". Three tiers: Quick (critical/high only),\nStandard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores,\nfix evidence, and a ship-readiness summary. For report-only mode, use /qa-only.", + "voice_line": "Voice triggers (speech-to-text aliases): \"quality check\", \"test the app\", \"run QA\"." + }, + "scrape": { + "lead": "Pull data from a web page.", + "routing": "First call on a new intent prototypes the flow\nvia $B primitives and returns JSON. Subsequent calls on a matching intent\nroute to a codified browser-skill and return in ~200ms. Read-only — for\nmutating flows (form fills, clicks, submissions), use /automate.\nUse when asked to \"scrape\", \"get data from\", \"pull\", \"extract from\", or\n\"what's on\" a page.", + "voice_line": null + }, + "qa-only": { + "lead": "Report-only QA testing.", + "routing": "Systematically tests a web application and produces a\nstructured report with health score, screenshots, and repro steps — but never\nfixes anything. Use when asked to \"just report bugs\", \"qa report only\", or\n\"test but don't fix\". For the full test-fix-verify loop, use /qa instead.\nProactively suggest when the user wants a bug report without any code changes.", + "voice_line": "Voice triggers (speech-to-text aliases): \"bug report\", \"just check for bugs\"." + }, + "skillify": { + "lead": "Codify the most recent successful /scrape flow into a permanent browser-skill on disk.", + "routing": "Future /scrape calls with the same intent run\nthe codified script in ~200ms instead of re-driving the page. Walks\nback through the conversation, synthesizes script.ts + script.test.ts\n+ fixture, runs the test in a temp dir, and asks before committing.\nUse when asked to \"skillify\", \"codify\", \"save this scrape\", or\n\"make this permanent\".", + "voice_line": null + }, + "sync-gbrain": { + "lead": "Keep gbrain current with this repo's code and refresh agent search guidance in CLAUDE.md. Wraps the gstack-gbrain-sync orchestrator with state", + "routing": "probing, native code-surface registration, capability checks,\nand a verdict block. Re-runnable, idempotent. Use when: \"sync gbrain\",\n\"refresh gbrain\", \"re-index this repo\", \"gbrain search isn't finding\nthings\".", + "voice_line": null + }, + "setup-browser-cookies": { + "lead": "Import cookies from your real Chromium browser into the headless browse session.", + "routing": "Opens an interactive picker UI where you select which cookie domains to import.\nUse before QA testing authenticated pages. Use when asked to \"import cookies\",\n\"login to the site\", or \"authenticate the browser\".", + "voice_line": null + }, + "ios-fix": { + "lead": "Autonomous iOS bug fixer.", + "routing": "Takes a bug found by /ios-qa, reads the source,\nwrites the fix, rebuilds, redeploys, and verifies the fix on the real\ndevice. Closes the loop: find bug → fix bug → confirm fix — zero human\nintervention. Captures the pre-bug state snapshot as a regression test\nfixture, so the bug can never recur silently.\nUse when /ios-qa reports a bug and you want it fixed automatically, or\nwhen asked to \"fix this iOS bug\", \"patch the iPhone app\", or \"auto-fix\nthe iOS issue\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"fix the iOS bug\", \"patch the iPhone app\", \"auto-fix the iOS issue\"." + }, + "ios-clean": { + "lead": "Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app.", + "routing": "Cleans up StateServer, DebugOverlay, accessor codegen output, and\napp-side hooks installed by /ios-qa. This is a convenience wrapper —\nthe structural Release-build guard (Package.swift conditional + CI\nswift build -c release check) is the safety-critical path.\nUse when asked to \"clean the iOS debug bridge\", \"remove DebugBridge\",\nor \"strip the gstack iOS instrumentation\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"clean the iOS debug bridge\", \"remove DebugBridge\", \"strip the gstack iOS instrumentation\"." + }, + "setup-gbrain": { + "lead": "Set up gbrain for this coding agent: install the CLI, initialize a local PGLite or Supabase brain, register MCP, capture per-remote trust policy.", + "routing": "One command from zero to \"gbrain is running, and this agent\ncan call it.\" Use when: \"setup gbrain\", \"connect gbrain\", \"start\ngbrain\", \"install gbrain\", \"configure gbrain for this machine\".", + "voice_line": null + }, + "document-generate": { + "lead": "Generate missing documentation from scratch for a feature, module, or entire project.", + "routing": "Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce\ncomplete, structured documentation. Can be invoked standalone or called by\n/document-release when it finds coverage gaps. Use when asked to \"write docs\",\n\"generate documentation\", \"document this feature\", \"create a tutorial\", or\n\"explain this module\".", + "voice_line": null + }, + "review": { + "lead": "Pre-landing PR review.", + "routing": "Analyzes diff against the base branch for SQL safety, LLM trust\nboundary violations, conditional side effects, and other structural issues. Use when\nasked to \"review this PR\", \"code review\", \"pre-landing review\", or \"check my diff\".\nProactively suggest when the user is about to merge or land code changes.", + "voice_line": null + }, + "plan-ceo-review": { + "lead": "CEO/founder-mode plan review.", + "routing": "Rethink the problem, find the 10-star product,\nchallenge premises, expand scope when it creates a better product. Four modes:\nSCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick\nexpansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).\nUse when asked to \"think bigger\", \"expand scope\", \"strategy review\", \"rethink this\",\nor \"is this ambitious enough\".\nProactively suggest when the user is questioning scope or ambition of a plan,\nor when the plan feels like it could be thinking bigger.", + "voice_line": null + }, + "office-hours": { + "lead": "YC Office Hours — two modes.", + "routing": "Startup mode: six forcing questions that expose\ndemand reality, status quo, desperate specificity, narrowest wedge, observation,\nand future-fit. Builder mode: design thinking brainstorming for side projects,\nhackathons, learning, and open source. Saves a design doc.\nUse when asked to \"brainstorm this\", \"I have an idea\", \"help me think through\nthis\", \"office hours\", or \"is this worth building\".\nProactively invoke this skill (do NOT answer directly) when the user describes\na new product idea, asks whether something is worth building, wants to think\nthrough design decisions for something that doesn't exist yet, or is exploring\na concept before any code is written.\nUse before /plan-ceo-review or /plan-eng-review.", + "voice_line": null + }, + "landing-report": { + "lead": "Read-only queue dashboard for workspace-aware ship.", + "routing": "Shows which VERSION slots\nare currently claimed by open PRs, which sibling Conductor workspaces have\nWIP work likely to ship soon, and what slot /ship would pick next. No\nmutations — just a snapshot. Use when asked to \"landing report\", \"what's in\nthe queue\", \"show me open PRs\", or \"which version do I claim next\".", + "voice_line": null + }, + "retro": { + "lead": "Weekly engineering retrospective.", + "routing": "Analyzes commit history, work patterns,\nand code quality metrics with persistent history and trend tracking.\nTeam-aware: breaks down per-person contributions with praise and growth areas.\nUse when asked to \"weekly retro\", \"what did we ship\", or \"engineering retrospective\".\nProactively suggest at the end of a work week or sprint.", + "voice_line": null + }, + "ios-design-review": { + "lead": "Visual design audit for iOS apps on real hardware.", + "routing": "Connects to a real\niPhone via the same StateServer as /ios-qa, screenshots every screen,\nevaluates against Apple HIG, DESIGN.md, and design best practices. Scores\neach dimension 0-10 with \"what would make it a 10\" framing — mirrors\n/plan-design-review for browser. For plan-stage design review (before\nimplementation), use /plan-design-review. For live web visual audits, use\n/design-review.\nUse when asked to \"review the iOS design\", \"audit the iPhone app's\nvisuals\", or \"design QA the iOS app\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"review the iOS design\", \"audit the iPhone app's visuals\", \"design QA the iPhone app\"." + }, + "devex-review": { + "lead": "Live developer experience audit.", + "routing": "Uses the browse tool to actually TEST the\ndeveloper experience: navigates docs, tries the getting started flow, times\nTTHW, screenshots error messages, evaluates CLI help text. Produces a DX\nscorecard with evidence. Compares against /plan-devex-review scores if they\nexist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to\n\"test the DX\", \"DX audit\", \"developer experience test\", or \"try the\nonboarding\". Proactively suggest after shipping a developer-facing feature.", + "voice_line": "Voice triggers (speech-to-text aliases): \"dx audit\", \"test the developer experience\", \"try the onboarding\", \"developer experience test\"." + }, + "benchmark-models": { + "lead": "Cross-model benchmark for gstack skills.", + "routing": "Runs the same prompt through Claude,\nGPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost,\nand optionally quality via LLM judge. Answers \"which model is actually best\nfor this skill?\" with data instead of vibes. Separate from /benchmark, which\nmeasures web page performance. Use when: \"benchmark models\", \"compare models\",\n\"which model is best for X\", \"cross-model comparison\", \"model shootout\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"compare models\", \"model shootout\", \"which model is best\"." + }, + "plan-devex-review": { + "lead": "Interactive developer experience plan review.", + "routing": "Explores developer personas,\nbenchmarks against competitors, designs magical moments, and traces friction\npoints before scoring. Three modes: DX EXPANSION (competitive advantage),\nDX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only).\nUse when asked to \"DX review\", \"developer experience audit\", \"devex review\",\nor \"API design review\".\nProactively suggest when the user has a plan for developer-facing products\n(APIs, CLIs, SDKs, libraries, platforms, docs).", + "voice_line": "Voice triggers (speech-to-text aliases): \"dx review\", \"developer experience review\", \"devex review\", \"devex audit\", \"API design review\", \"onboarding review\"." + }, + "ios-sync": { + "lead": "Regenerate the iOS debug bridge against the latest upstream gstack templates.", + "routing": "Updates StateServer.swift, DebugOverlay.swift, Package.swift,\nand the typed @Observable state accessors. Use after you upgrade gstack\nor add new ViewModels/properties that need accessor coverage.\nUse when asked to \"resync the iOS debug bridge\", \"regenerate iOS\naccessors\", or \"update the gstack iOS instrumentation\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"resync the iOS debug bridge\", \"regenerate iOS accessors\", \"update the gstack iOS instrumentation\"." + }, + "browse": { + "lead": "Fast headless browser for QA testing and site dogfooding.", + "routing": "Navigate any URL, interact with\nelements, verify page state, diff before/after actions, take annotated screenshots, check\nresponsive layouts, test forms and uploads, handle dialogs, and assert element states.\n~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a\nuser flow, or file a bug with evidence. Use when asked to \"open in browser\", \"test the\nsite\", \"take a screenshot\", or \"dogfood this\".", + "voice_line": null + }, + "design-review": { + "lead": "Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them.", + "routing": "Iteratively fixes issues\nin source code, committing each fix atomically and re-verifying with before/after\nscreenshots. For plan-mode design review (before implementation), use /plan-design-review.\nUse when asked to \"audit the design\", \"visual QA\", \"check if it looks good\", or \"design polish\".\nProactively suggest when the user mentions visual inconsistencies or\nwants to polish the look of a live site.", + "voice_line": null + }, + "ship": { + "lead": "Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.", + "routing": "Use when asked to \"ship\", \"deploy\",\n\"push to main\", \"create a PR\", \"merge and push\", or \"get it deployed\".\nProactively invoke this skill (do NOT push/PR directly) when the user says code\nis ready, asks about deploying, wants to push code up, or asks to create a PR.", + "voice_line": null + }, + "plan-eng-review": { + "lead": "Eng manager-mode plan review.", + "routing": "Lock in the execution plan — architecture,\ndata flow, diagrams, edge cases, test coverage, performance. Walks through\nissues interactively with opinionated recommendations. Use when asked to\n\"review the architecture\", \"engineering review\", or \"lock in the plan\".\nProactively suggest when the user has a plan or design doc and is about to\nstart coding — to catch architecture issues before implementation.", + "voice_line": "Voice triggers (speech-to-text aliases): \"tech review\", \"technical review\", \"plan engineering review\"." + }, + "guard": { + "lead": "Full safety mode: destructive command warnings + directory-scoped edits.", + "routing": "Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with\n/freeze (blocks edits outside a specified directory). Use for maximum safety\nwhen touching prod or debugging live systems. Use when asked to \"guard mode\",\n\"full safety\", \"lock it down\", or \"maximum safety\".", + "voice_line": null + }, + "make-pdf": { + "lead": "Turn any markdown file into a publication-quality PDF.", + "routing": "Proper 1in margins,\nintelligent page breaks, page numbers, cover pages, running headers, curly\nquotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft\nartifact — a finished artifact. Use when asked to \"make a PDF\", \"export to\nPDF\", \"turn this markdown into a PDF\", or \"generate a document\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"make this a pdf\", \"make it a pdf\", \"export to pdf\", \"turn this into a pdf\", \"turn this markdown into a pdf\", \"generate a pdf\", \"make a pdf from\", \"pdf this markdown\"." + }, + "unfreeze": { + "lead": "Clear the freeze boundary set by /freeze, allowing edits to all directories again.", + "routing": "Use when you want to widen edit scope without ending the session.\nUse when asked to \"unfreeze\", \"unlock edits\", \"remove freeze\", or\n\"allow all edits\".", + "voice_line": null + }, + "context-save": { + "lead": "Save working context.", + "routing": "Captures git state, decisions made, and remaining work\nso any future session can pick up without losing a beat.\nUse when asked to \"save progress\", \"save state\", \"context save\", or\n\"save my work\". Pair with /context-restore to resume later.\nFormerly /checkpoint — renamed because Claude Code treats /checkpoint as a\nnative rewind alias in current environments, which was shadowing this skill.", + "voice_line": null + }, + "setup-deploy": { + "lead": "Configure deployment settings for /land-and-deploy.", + "routing": "Detects your deploy\nplatform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom),\nproduction URL, health check endpoints, and deploy status commands. Writes\nthe configuration to CLAUDE.md so all future deploys are automatic.\nUse when: \"setup deploy\", \"configure deployment\", \"set up land-and-deploy\",\n\"how do I deploy with gstack\", \"add deploy config\".", + "voice_line": null + } + } +} diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index 8b80fd58b..0daff31df 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -2,11 +2,7 @@ name: setup-browser-cookies preamble-tier: 1 version: 1.0.0 -description: | - Import cookies from your real Chromium browser into the headless browse session. - Opens an interactive picker UI where you select which cookie domains to import. - Use before QA testing authenticated pages. Use when asked to "import cookies", - "login to the site", or "authenticate the browser". (gstack) +description: Import cookies from your real Chromium browser into the headless browse session. (gstack) triggers: - import browser cookies - login to test site @@ -19,6 +15,13 @@ allowed-tools: + +## When to invoke this skill + +Opens an interactive picker UI where you select which cookie domains to import. +Use before QA testing authenticated pages. Use when asked to "import cookies", +"login to the site", or "authenticate the browser". + ## Preamble (run first) ```bash diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index e824d3ed8..ee4807f34 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -2,13 +2,7 @@ name: setup-deploy preamble-tier: 2 version: 1.0.0 -description: | - Configure deployment settings for /land-and-deploy. Detects your deploy - platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), - production URL, health check endpoints, and deploy status commands. Writes - the configuration to CLAUDE.md so all future deploys are automatic. - Use when: "setup deploy", "configure deployment", "set up land-and-deploy", - "how do I deploy with gstack", "add deploy config". +description: Configure deployment settings for /land-and-deploy. triggers: - configure deploy - setup deployment @@ -25,6 +19,16 @@ allowed-tools: + +## When to invoke this skill + +Detects your deploy +platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), +production URL, health check endpoints, and deploy status commands. Writes +the configuration to CLAUDE.md so all future deploys are automatic. +Use when: "setup deploy", "configure deployment", "set up land-and-deploy", +"how do I deploy with gstack", "add deploy config". + ## Preamble (run first) ```bash diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index 8fd689c36..5376b58bb 100644 --- a/setup-gbrain/SKILL.md +++ b/setup-gbrain/SKILL.md @@ -2,12 +2,7 @@ name: setup-gbrain preamble-tier: 2 version: 1.0.0 -description: | - Set up gbrain for this coding agent: install the CLI, initialize a - local PGLite or Supabase brain, register MCP, capture per-remote trust - policy. One command from zero to "gbrain is running, and this agent - can call it." Use when: "setup gbrain", "connect gbrain", "start - gbrain", "install gbrain", "configure gbrain for this machine". (gstack) +description: Set up gbrain for this coding agent: install the CLI, initialize a local PGLite or Supabase brain, register MCP, capture per-remote trust policy. (gstack) triggers: - setup gbrain - install gbrain @@ -26,6 +21,13 @@ allowed-tools: + +## When to invoke this skill + +One command from zero to "gbrain is running, and this agent +can call it." Use when: "setup gbrain", "connect gbrain", "start +gbrain", "install gbrain", "configure gbrain for this machine". + ## Preamble (run first) ```bash diff --git a/ship/SKILL.md b/ship/SKILL.md index ab5521c67..090798914 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -2,12 +2,7 @@ name: ship preamble-tier: 4 version: 1.0.0 -description: | - 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", "merge and push", or "get it deployed". - Proactively invoke this skill (do NOT push/PR directly) when the user says code - is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) +description: Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. (gstack) allowed-tools: - Bash - Read @@ -27,6 +22,14 @@ triggers: + +## When to invoke this skill + +Use when asked to "ship", "deploy", +"push to main", "create a PR", "merge and push", or "get it deployed". +Proactively invoke this skill (do NOT push/PR directly) when the user says code +is ready, asks about deploying, wants to push code up, or asks to create a PR. + ## Preamble (run first) ```bash diff --git a/skillify/SKILL.md b/skillify/SKILL.md index 21fcf5673..cfefe936b 100644 --- a/skillify/SKILL.md +++ b/skillify/SKILL.md @@ -1,14 +1,7 @@ --- name: skillify version: 1.0.0 -description: | - Codify the most recent successful /scrape flow into a permanent - browser-skill on disk. Future /scrape calls with the same intent run - the codified script in ~200ms instead of re-driving the page. Walks - back through the conversation, synthesizes script.ts + script.test.ts - + fixture, runs the test in a temp dir, and asks before committing. - Use when asked to "skillify", "codify", "save this scrape", or - "make this permanent". (gstack) +description: Codify the most recent successful /scrape flow into a permanent browser-skill on disk. (gstack) allowed-tools: - Bash - Read @@ -23,6 +16,16 @@ triggers: + +## When to invoke this skill + +Future /scrape calls with the same intent run +the codified script in ~200ms instead of re-driving the page. Walks +back through the conversation, synthesizes script.ts + script.test.ts ++ fixture, runs the test in a temp dir, and asks before committing. +Use when asked to "skillify", "codify", "save this scrape", or +"make this permanent". + ## Preamble (run first) ```bash diff --git a/sync-gbrain/SKILL.md b/sync-gbrain/SKILL.md index 669e69e9d..f6b64edb3 100644 --- a/sync-gbrain/SKILL.md +++ b/sync-gbrain/SKILL.md @@ -2,13 +2,7 @@ name: sync-gbrain preamble-tier: 2 version: 1.0.0 -description: | - Keep gbrain current with this repo's code and refresh agent search - guidance in CLAUDE.md. Wraps the gstack-gbrain-sync orchestrator with - state probing, native code-surface registration, capability checks, - and a verdict block. Re-runnable, idempotent. Use when: "sync gbrain", - "refresh gbrain", "re-index this repo", "gbrain search isn't finding - things". (gstack) +description: Keep gbrain current with this repo's code and refresh agent search guidance in CLAUDE.md. Wraps the gstack-gbrain-sync orchestrator with state (gstack) triggers: - sync gbrain - refresh gbrain @@ -26,6 +20,14 @@ allowed-tools: + +## When to invoke this skill + +probing, native code-surface registration, capability checks, +and a verdict block. Re-runnable, idempotent. Use when: "sync gbrain", +"refresh gbrain", "re-index this repo", "gbrain search isn't finding +things". + ## Preamble (run first) ```bash diff --git a/unfreeze/SKILL.md b/unfreeze/SKILL.md index 415137bcd..a07f1cf5f 100644 --- a/unfreeze/SKILL.md +++ b/unfreeze/SKILL.md @@ -1,11 +1,7 @@ --- name: unfreeze version: 0.1.0 -description: | - Clear the freeze boundary set by /freeze, allowing edits to all directories - again. Use when you want to widen edit scope without ending the session. - Use when asked to "unfreeze", "unlock edits", "remove freeze", or - "allow all edits". (gstack) +description: Clear the freeze boundary set by /freeze, allowing edits to all directories again. (gstack) triggers: - unfreeze edits - unlock all directories @@ -17,6 +13,13 @@ allowed-tools: + +## When to invoke this skill + +Use when you want to widen edit scope without ending the session. +Use when asked to "unfreeze", "unlock edits", "remove freeze", or +"allow all edits". + # /unfreeze — Clear Freeze Boundary Remove the edit restriction set by `/freeze`, allowing edits to all directories.