bug: generated SKILL.md descriptions with colons are invalid YAML
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## What happened
Codex/OpenAI skill loading skips several gstack skills because generated `SKILL.md` frontmatter contains inline plain YAML scalars with unescaped colons.
Example generated frontmatter:
```yaml
---
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)
triggers:
- setup gbrain
---
```
A strict YAML parser treats the second colon (`agent: install`) as a mapping separator and fails with:
```text
invalid YAML: mapping values are not allowed in this context
```
## Affected examples
Observed in exported gstack skills:
- `setup-gbrain/SKILL.md`
- `guard/SKILL.md`
- `design-html/SKILL.md`
- `design-shotgun/SKILL.md`
- `design-review/SKILL.md`
- `ship/SKILL.md`
- `design-consultation/SKILL.md`
- `plan-tune/SKILL.md`
## Expected
Generated `SKILL.md` frontmatter should parse as YAML in strict loaders.
## Suggested fix
Quote one-line generated `description:` values or emit block scalars consistently. The generator should also parse every generated frontmatter block in tests, not just check that `name:` and `description:` strings exist.
Locally, this shape fixed the issue:
- Quote inline `description:` values with `JSON.stringify(...)`
- In `gen-skill-docs.ts`, normalize inline descriptions before writing generated content
- In `gen-skill-docs.test.ts`, parse generated frontmatter with `Bun.YAML.parse(...)`
## Verification
Local validation after patching exported skills:
```text
checked 545 SKILL.md files, bad=0
```
Also no remaining unquoted inline descriptions with colons were found by:
```bash
rg -n '^description: [^|"'"'].*:' /path/to/exported/gstack --glob 'SKILL.md'
```
Contributor guide
Assessment
This issue has not been assessed yet.