Bug
codev-skeleton/.claude/skills/update-arch-docs/SKILL.md has YAML frontmatter that fails to parse.
The description: value is an unquoted YAML scalar that contains the substring two operating modes: diff-mode. The bare : followed by a space makes the YAML parser try to interpret modes: diff-mode as a nested mapping inside the scalar, which is illegal.
Reproduction
python3 -c "
import yaml
with open('codev-skeleton/.claude/skills/update-arch-docs/SKILL.md') as f:
parts = f.read().split('---', 2)
yaml.safe_load(parts[1])
"
Errors with:
yaml.scanner.ScannerError: mapping values are not allowed here
in \"<unicode string>\", line 3, column 502:
... t) and ships two operating modes: diff-mode (apply a specific ch ...
Impact
The skill ships in codev-skeleton/, which is the install path that codev init / codev adopt / codev update copy into other projects via the four-tier resolver. Any project receiving this skeleton inherits a skill whose frontmatter cannot be parsed by strict YAML loaders. Tools that rely on parsing the frontmatter to discover or describe the skill will skip / misreport it.
The three live working copies in this repo (.claude/, .codex/, .gemini/) are also broken, but per the bugfix request, this issue's scope is the skeleton only.
Fix
Quote the description: value. Wrap the entire description string in double quotes. The string contains backticks, em-dashes, parentheses, and apostrophes but no embedded double quotes, so plain description: \"...\" works without escaping.
Before:
---
name: update-arch-docs
description: Audit, prune, and update the project's architecture documentation — `codev/resources/arch.md` and `codev/resources/lessons-learned.md`. ... ships two operating modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). ...
---
After:
---
name: update-arch-docs
description: \"Audit, prune, and update the project's architecture documentation — \`codev/resources/arch.md\` and \`codev/resources/lessons-learned.md\`. ... ships two operating modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). ...\"
---
Quoting (vs. rephrasing to drop the colon) is preferred because it is robust against future edits — anyone who adds a colon to the description later won't reintroduce this bug.
Scope
- In scope:
codev-skeleton/.claude/skills/update-arch-docs/SKILL.md (the template that ships to other projects).
- Out of scope: the live working copies at
.claude/skills/, .codex/skills/, .gemini/skills/. These have the same bug but are intentionally left for a separate change.
Acceptance criteria
Builder notes
- Builder should push the fix branch to the contributor's fork (
mohidmakhdoomi/codev), not upstream (cluesmith/codev), and open the PR fork → upstream.
Bug
codev-skeleton/.claude/skills/update-arch-docs/SKILL.mdhas YAML frontmatter that fails to parse.The
description:value is an unquoted YAML scalar that contains the substringtwo operating modes: diff-mode. The bare:followed by a space makes the YAML parser try to interpretmodes: diff-modeas a nested mapping inside the scalar, which is illegal.Reproduction
Errors with:
Impact
The skill ships in
codev-skeleton/, which is the install path thatcodev init/codev adopt/codev updatecopy into other projects via the four-tier resolver. Any project receiving this skeleton inherits a skill whose frontmatter cannot be parsed by strict YAML loaders. Tools that rely on parsing the frontmatter to discover or describe the skill will skip / misreport it.The three live working copies in this repo (
.claude/,.codex/,.gemini/) are also broken, but per the bugfix request, this issue's scope is the skeleton only.Fix
Quote the
description:value. Wrap the entire description string in double quotes. The string contains backticks, em-dashes, parentheses, and apostrophes but no embedded double quotes, so plaindescription: \"...\"works without escaping.Before:
After:
Quoting (vs. rephrasing to drop the colon) is preferred because it is robust against future edits — anyone who adds a colon to the description later won't reintroduce this bug.
Scope
codev-skeleton/.claude/skills/update-arch-docs/SKILL.md(the template that ships to other projects)..claude/skills/,.codex/skills/,.gemini/skills/. These have the same bug but are intentionally left for a separate change.Acceptance criteria
codev-skeleton/.claude/skills/update-arch-docs/SKILL.mdparses as valid YAML (verify with the repro snippet above — it should print nothing and exit 0).codev-skeleton/are modified.Builder notes
mohidmakhdoomi/codev), not upstream (cluesmith/codev), and open the PR fork → upstream.