Skip to content

fix(skills): remove unquoted ": " from 10 SKILL.md descriptions - #88

Merged
5uck1ess merged 1 commit into
mainfrom
fix/skill-description-yaml-colons-87
Apr 11, 2026
Merged

fix(skills): remove unquoted ": " from 10 SKILL.md descriptions#88
5uck1ess merged 1 commit into
mainfrom
fix/skill-description-yaml-colons-87

Conversation

@5uck1ess

Copy link
Copy Markdown
Owner

Summary

  • Fixes the YAML-parse bug in 10 skills/*/SKILL.md files where unquoted : sequences inside plain-scalar description: values violated YAML 1.2 §7.3.3, causing strict parsers to drop the description and Claude Code to fall back to the plugin-prefixed slash name + H1 heading.
  • 8 files rephrased (when:when —, flag:flag —), 2 files (mega-pr, pr-ready) converted to folded block scalar (>-) because they contain inline slash paths like /devkit:tri-review and /commit-commands:commit-push-pr that are natural to keep.
  • Verified with Ruby Psych strict YAML parser — all 10 files now load cleanly and return non-empty description strings.

Rationale for strategy split

  • Rephrase is minimal-touch and preserves the 5-part description rubric. Used for the 8 files where the only offender was a conversational when: / flag:.
  • Block scalar (>-) for mega-pr and pr-ready avoids contorting natural slash-path references. Folded style (>) collapses line breaks back to spaces so the runtime-observable description is unchanged, and strip chomping (-) avoids a trailing newline.

Affected files

File Strategy Offender(s) removed
skills/audit/SKILL.md rephrase flag: outdated
skills/bugfix/SKILL.md rephrase when: the
skills/deep-research/SKILL.md rephrase when: the
skills/feature/SKILL.md rephrase feature: ..., when: the
skills/refactor/SKILL.md rephrase when: the
skills/tri-debug/SKILL.md rephrase when: the
skills/tri-dispatch/SKILL.md rephrase when: the
skills/tri-security/SKILL.md rephrase when: touching
skills/mega-pr/SKILL.md block scalar >- when: the
skills/pr-ready/SKILL.md block scalar >- when: lint

Test plan

  • ruby -ryaml -e 'YAML.safe_load(frontmatter)' for all 10 files → passes
  • No leftover \w+: \S patterns in any rephrased file (confirmed via grep)
  • On Windows Claude Code: /reload-plugins, confirm slash picker shows all 10 skills unprefixed with full descriptions instead of /devkit:<name> + H1 fallback
  • On Mac Claude Code: /reload-plugins, confirm no regression (rendering stays identical)

Notes

Closes #87.

Issue #87's per-file token list included a few phantom offenders (research: c, enforce: s, docs: u, pipeline: v, Skill: d) that don't actually appear in the v2.1.20 files — they were artifacts of the scanning regex. The real count is 11 offending tokens across 10 files, all fixed by this PR.

10 SKILL.md files had unquoted `: ` sequences inside plain-scalar
`description:` values, violating YAML 1.2 §7.3.3. Strict YAML parsers
dropped the description and Claude Code fell back to the plugin-prefixed
slash name + H1 heading, causing the asymmetric Mac/Windows rendering
reported in #87.

Fix strategy:
- 8 files rephrased (`when:` → `when —`, `flag:` → `flag —`, etc.)
- 2 files (mega-pr, pr-ready) converted to folded block scalar (`>-`)
  to preserve inline slash paths like `/devkit:tri-review`

Verified with Ruby Psych strict YAML parser — all 10 files parse
cleanly and return non-empty description strings.

Closes #87
@5uck1ess
5uck1ess merged commit 3acb513 into main Apr 11, 2026
6 checks passed
@5uck1ess
5uck1ess deleted the fix/skill-description-yaml-colons-87 branch April 11, 2026 19:45
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.

Skill frontmatter: unquoted : in 10 descriptions breaks YAML parse → slash picker falls back to plugin-prefixed name + H1 heading

1 participant