Skip to content

BUGFIX: update-arch-docs skill has invalid YAML frontmatter (skeleton) #922

@mohidmakhdoomi

Description

@mohidmakhdoomi

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

  • codev-skeleton/.claude/skills/update-arch-docs/SKILL.md parses as valid YAML (verify with the repro snippet above — it should print nothing and exit 0).
  • The semantic content of the description is unchanged.
  • No other files in codev-skeleton/ are modified.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions