fix(gen-skill-docs): quote frontmatter descriptions containing colons

design-consultation/SKILL.md

@@ -2,7 +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... (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

design-html/SKILL.md

@@ -2,7 +2,7 @@
 name: design-html
 preamble-tier: 2
 version: 1.0.0
-description: Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack)
+description: "Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack)"
 triggers:
   - build the design
   - code the mockup

design-review/SKILL.md

@@ -2,7 +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. (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

design-shotgun/SKILL.md

@@ -2,7 +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. (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

guard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: guard
 version: 0.1.0
-description: Full safety mode: destructive command warnings + directory-scoped edits. (gstack)
+description: "Full safety mode: destructive command warnings + directory-scoped edits. (gstack)"
 triggers:
   - full safety mode
   - guard against mistakes

plan-tune/SKILL.md

@@ -2,7 +2,7 @@
 name: plan-tune
 preamble-tier: 2
 version: 1.0.0
-description: Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). (gstack)
+description: "Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). (gstack)"
 triggers:
   - tune questions
   - stop asking me that

scripts/gen-skill-docs.ts

@@ -323,6 +323,20 @@ export function buildWhenToInvokeSection(parts: CatalogParts): string {
  * Returns the rewritten content plus the parts (used for proactive-suggestions
  * JSON aggregation at the end of the run).
  */
+/**
+ * Render a string as a single-line YAML scalar for frontmatter. A plain scalar
+ * is invalid YAML when it contains ": " / a trailing ":" (read as a mapping
+ * separator) or starts with an indicator character, so quote those cases with a
+ * double-quoted scalar (escaping backslash and double-quote). Descriptions
+ * commonly contain colons (e.g. "Set up gbrain: install the CLI"), which made
+ * strict loaders (Codex/OpenAI skill loading) reject the generated SKILL.md.
+ */
+export function toYamlPlainOrQuoted(value: string): string {
+  const needsQuoting = /:(\s|$)/.test(value) || /^[!&*?|>@`"'#%,\[\]{}\- ]/.test(value);
+  if (!needsQuoting) return value;
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
 export function applyCatalogTrim(content: string, skillName: string): { content: string; parts: CatalogParts } | null {
   // Locate description block in frontmatter
   if (!content.startsWith('---\n')) return null;
@@ -355,7 +369,7 @@ export function applyCatalogTrim(content: string, skillName: string): { content:
   // 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`);
+  const newFrontmatter = frontmatter.replace(descMatch[0], `description: ${toYamlPlainOrQuoted(newDesc)}\n`);
   let newContent = '---\n' + newFrontmatter + content.slice(fmEnd);
 
   // Insert body section after frontmatter (after the closing ---\n and any

setup-gbrain/SKILL.md

@@ -2,7 +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. (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

ship/SKILL.md

@@ -2,7 +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. (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