garrytan / garrytan/gstack

bug: generated SKILL.md descriptions with colons are invalid YAML

Open
#1,778 1 comment 1 reaction 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.