Fix Codex skill loading errors from unquoted descriptions

[GilbertzzzZZ]

Summary

This PR fixes Codex skill loading failures caused by generated SKILL.md frontmatter descriptions that become invalid YAML after catalog trimming.

When gstack is loaded by Codex, affected skills can be skipped with warnings like:

Skipped loading 8 skill(s) due to invalid SKILL.md files
invalid YAML: mapping values are not allowed in this context

The root cause is that the generator converts long block-scalar descriptions into one-line inline YAML values, but some descriptions contain : . Without quoting, YAML can parse that colon as a mapping delimiter.

Example

Before:

description: Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. (gstack)

After:

description: "Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. (gstack)"

Changes

• Quote catalog-trimmed inline description values in scripts/gen-skill-docs.ts so Codex can parse generated skill frontmatter safely.
• Update catalog trim tests to expect YAML-safe quoted inline descriptions.
• Regenerate affected Claude host SKILL.md files.
• Update the claude-ship-SKILL.md golden fixture.

Validation

• bun run gen:skill-docs --host all --dry-run
• YAML frontmatter parse check across generated SKILL.md files
• git diff --check
• bun test

Note: the existing ship token ceiling warning still appears during generation, but the command exits successfully and is unrelated to this Codex YAML loading fix.

Contribution context

Thank you to the gstack team for building and maintaining this project. I have benefited a lot from using it.

Claude Code is still my primary agent environment, but because my team needs it, I am starting to use Codex as well. In my own projects, I am also beginning to support both Claude Code and Codex at the same time.

I would be happy to keep contributing compatibility fixes for using the gstack skill series from Codex in the future.

[jbetala7]

Independent validation — this looks correct and fixes a real, reproducible bug.

Reproduced on origin/main (f8bb590): running applyCatalogTrim over the shipped skills and parsing the resulting frontmatter with the yaml package, design-consultation fails:

design-consultation: Nested mappings are not allowed in compact mappings at line 5, column 14

The offending generated line is:

description: Design consultation: understands your product, researches the landscape, ... and (gstack)

The trimmed lead starts with Design consultation:, and applyCatalogTrim emitted it via description: ${newDesc} unquoted — so YAML reads the second colon as a nested mapping. That matches the invalid YAML: mapping values are not allowed in this context Codex warning in the description.

With this PR's branch: the same sweep reports 0 invalid frontmatter blocks, and bun test test/catalog-trim.test.ts passes 20/20 (the one failure I initially saw was just a missing transitive diff dep in a fresh worktree, not this change). JSON.stringify output is a valid YAML double-quoted scalar, including the escaped-newline cases, so quoting is the right shape here.

One heads-up for the maintainer, not a blocker: this overlaps file-wise with the in-flight wave #1740, which regenerates ~56 SKILL.md files but does not touch scripts/gen-skill-docs.ts. So #1740 will reintroduce the unquoted descriptions, and after it lands this PR will need a rebase + bun run gen:skill-docs to refresh the generated files — but the generator fix itself is still required and is not duplicated by #1740.

[GilbertzzzZZ]

Thanks @jbetala7 for the independent repro and the heads-up about #1740 — really appreciated.

Following your note: #1740 has since landed on main. I've merged main into this branch and regenerated spec/SKILL.md (the one new file #1740 added that would have re-broken Codex loading) — see commit f6ccb27. All other generated SKILL.md files in #1740 went through applyCatalogTrim so they already have the quoted descriptions from this branch's generator fix.

@garrytan — this is unblocked and ready to merge whenever you have a moment. Conflict-free against main, generator fix + regenerated files in one PR.

[steffensiewert]

Reproduced on Codex 0.134.0 (fresh codex-firmware tmux session today): same 8 SKILL.md files fail with invalid YAML: mapping values are not allowed in this context. A local sed-based quoting workaround produces YAML identical to this patch — fix works.