From 72dee3b083e5b6822280aa520a7cd12ed610d5b2 Mon Sep 17 00:00:00 2001 From: genisis0x Date: Fri, 29 May 2026 18:27:30 +0530 Subject: [PATCH 1/2] fix(gen-skill-docs): quote frontmatter descriptions containing colons applyCatalogTrim wrote the trimmed description as a plain YAML scalar. When the text contains a colon-space or trailing colon, a strict YAML parser reads it as a mapping separator and rejects the frontmatter, so Codex/OpenAI skill loading skipped those skills. Render the value through a toYamlPlainOrQuoted helper that double-quotes (with escaping) only when the plain scalar would be invalid. Closes #1778. --- scripts/gen-skill-docs.ts | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 30853f6776..54ffe0c98c 100644 --- a/scripts/gen-skill-docs.ts +++ b/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 From 11586e8b1bc3b489e5fe1dee0cda1c705a928ef0 Mon Sep 17 00:00:00 2001 From: genisis0x Date: Fri, 29 May 2026 18:27:42 +0530 Subject: [PATCH 2/2] chore: regenerate SKILL.md with quoted colon descriptions Regenerated by bun run gen:skill-docs after the frontmatter quoting fix. Eight skills whose descriptions contain colons now emit valid YAML. --- design-consultation/SKILL.md | 2 +- design-html/SKILL.md | 2 +- design-review/SKILL.md | 2 +- design-shotgun/SKILL.md | 2 +- guard/SKILL.md | 2 +- plan-tune/SKILL.md | 2 +- setup-gbrain/SKILL.md | 2 +- ship/SKILL.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 1e8762964b..9bab21e2df 100644 --- a/design-consultation/SKILL.md +++ b/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 diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 2d1b3cfb52..f6e9e17f89 100644 --- a/design-html/SKILL.md +++ b/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 diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 97f365f132..e874a94aa1 100644 --- a/design-review/SKILL.md +++ b/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 diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index b504b79fe7..9fd662ce68 100644 --- a/design-shotgun/SKILL.md +++ b/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 diff --git a/guard/SKILL.md b/guard/SKILL.md index 8d4a57448c..e4dff7936f 100644 --- a/guard/SKILL.md +++ b/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 diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index 8e61abc58b..41c45342ec 100644 --- a/plan-tune/SKILL.md +++ b/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 diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index e0415d5646..2f89ba7147 100644 --- a/setup-gbrain/SKILL.md +++ b/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 diff --git a/ship/SKILL.md b/ship/SKILL.md index 12e4c7799f..c175f67d48 100644 --- a/ship/SKILL.md +++ b/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