Skip to content

fix(build): quote YAML descriptions containing ': ', trailing ':', or reserved indicators#104

Open
mvanhorn wants to merge 1 commit intopbakaus:mainfrom
mvanhorn:osc/102-yaml-description-unquoted-colon
Open

fix(build): quote YAML descriptions containing ': ', trailing ':', or reserved indicators#104
mvanhorn wants to merge 1 commit intopbakaus:mainfrom
mvanhorn:osc/102-yaml-description-unquoted-colon

Conversation

@mvanhorn
Copy link
Copy Markdown
Contributor

@mvanhorn mvanhorn commented Apr 19, 2026

Summary

Closes #102.

`generateYamlFrontmatter` (scripts/lib/utils.js) only quoted values beginning with `[` or `{`, so scalars containing a colon-space were written unquoted. Strict YAML parsers, including Codex's skill loader and GitHub's frontmatter preview, then rejected the emitted file with `mapping values are not allowed in this context` and skipped loading the skill. The `harden` skill's description, which reads `Make interfaces production-ready: error handling, ...`, hit this path; every generated provider copy (`.codex`, `.claude`, `.cursor`, `.gemini`, `.agents`, `.kiro`, `.opencode`, `.pi`, `.rovodev`, `.trae-cn`, `.trae`) ended up with an invalid front matter block even though `source/skills/harden/SKILL.md` was already quoted.

Broaden `needsQuoting` to cover the documented YAML 1.2 failure modes rather than only the flow-indicator case:

  • values starting with a flow indicator (`[`, `{`) or a reserved indicator (`#`, `&`, `*`, `!`, `|`, `>`, `%`, `@`, backtick), leading whitespace, a leading quote, or a leading `-`
  • values containing `: ` or ending in `:` (the issue-reported regression)
  • values containing ` #` (inline comment marker)

Type of change

  • Bug fix
  • Build system / tooling

Verification

```console
$ bun test tests/lib/utils.test.js
64 pass
0 fail
```

New tests cover the colon-space regression, trailing colon, leading reserved indicators, and mid-string ` #` sequence, each paired with a `parseFrontmatter` roundtrip so the quoted output recovers the original scalar.

`bun run build` regenerates all 11 provider copies. The harden SKILL.md front matter is now valid under strict YAML parsers:

```yaml
description: "Make interfaces production-ready: error handling, empty states, onboarding flows, i18n, text overflow, and edge case management. Use when the user asks to harden, make production-ready, handle edge cases, add error states, design empty states, improve onboarding, or fix overflow and i18n issues."
```

Checklist

  • Source files updated in `source/` (no change - already quoted; build-side regression)
  • `bun run build` ran successfully
  • `bun test` passes (64/64 in tests/lib/utils.test.js)
  • Tested with at least one provider (Codex loader path simulated in test via `parseFrontmatter` roundtrip)
  • README / DEVELOP.md updated if needed (not needed - internal build fix)

Note

Low Risk
Low risk: limited to build-time frontmatter stringification plus added unit tests; behavioral change is broader quoting which may slightly alter emitted YAML formatting but should improve parser compatibility.

Overview
Fixes a build-time YAML frontmatter escaping bug. generateYamlFrontmatter now quotes string scalars that would be misparsed by strict YAML parsers (e.g., values containing : , ending with :, containing #, or starting with YAML-reserved indicators/whitespace/quotes).

Regenerates provider skill copies (e.g., harden descriptions) to include quoted descriptions, and adds regression tests covering the new quoting cases with parse round-trips.

Reviewed by Cursor Bugbot for commit c963d8a. Bugbot is set up for automated code reviews on this repo. Configure here.

… reserved indicators

Closes pbakaus#102

generateYamlFrontmatter only quoted strings beginning with '[' or '{', so any
scalar containing a colon-space was written unquoted. Strict YAML parsers
(Codex's skill loader, GitHub's frontmatter preview) then rejected the file
with "mapping values are not allowed in this context" and skipped the skill
entirely. The harden skill's description ("Make interfaces production-ready:
error handling, ...") hit this path.

Broaden needsQuoting to cover the documented YAML 1.2 failure modes:
- values starting with a flow indicator ([, {) or a reserved indicator
  (#, &, *, !, |, >, %, @, `), leading whitespace, or a leading quote/hyphen
- values containing ": " or ending in ":"
- values containing " #" (inline comment marker)

Tests cover the colon-space regression, trailing colon, leading reserved
indicators, and mid-string " #" sequence, plus roundtrip through
parseFrontmatter to confirm the quoted form recovers the original value.

`bun run build` regenerates the 11 provider copies so .codex, .claude,
.cursor, .gemini, .agents, .kiro, .opencode, .pi, .rovodev, .trae-cn, and
.trae all now emit the quoted description for the harden skill.
@mvanhorn mvanhorn requested a review from pbakaus as a code owner April 19, 2026 08:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Invalid YAML in harden SKILL.md description (unquoted colon) — Codex skips loading

1 participant