Template-version HTML comment at file top breaks skill-list description for commands-format installs #36

What happens

The template's header (introduced by #22) places two HTML comments at the very top of the generated skill file:

<!-- template-version: {{TEMPLATE_VERSION}} -->
<!-- generated-at: {{GENERATED_AT}} -->

# <slug>-dev-loop
...

Skills installed via the path in Step 5 — symlinked to ~/.claude/commands/<slug>-dev-loop.md — are loaded in the older slash-command format, which has no metadata layer. The harness displays the file's first non-empty line as the skill's description in the skill list. So with the new header, every retrofitted/regenerated skill now shows up like:

- example-l-dev-loop: <!-- template-version: 5a4ad26 (retrofit) -->
- example-q-dev-loop: <!-- template-version: 5a4ad26 (retrofit) -->
- example-h-dev-loop: <!-- template-version: 5a4ad26 (retrofit) -->
- ...

instead of a useful description.

How it was noticed

While retrofitting #22 across the six pre-#22 skills (PRs: dpm#20, herald#4, acsf#41, cdl#9, dansplugins#5, kfe#9), the skill list flipped from showing the slug-only fallback (- example-l-dev-loop: example-l-dev-loop) to showing the HTML comment. example-a-dev-loop is the only skill in the constellation whose display didn't regress, because it has a parallel ~/.claude/skills/example-a-dev-loop/SKILL.md file with YAML frontmatter (name: + description:) and the harness prefers that over the commands-format file.

Two ways to fix

Option A — Reorder: comments below the heading (quick fix)

# <slug>-dev-loop

<!-- template-version: {{TEMPLATE_VERSION}} -->
<!-- generated-at: {{GENERATED_AT}} -->

Autonomous iterative development loop for {{PROJECT_NAME}}.

The drift-detection use case still works (a future cycle can grep for <!-- template-version:). The heading becomes the first content line, so the skill list shows - <slug>: <slug> again. Smallest change: one edit to the Step 3 template + a one-line note in Step 4 explaining the placement.

Option B — Migrate Step 5 to the SKILL.md format with frontmatter (proper fix)

Change Step 5 to install at ~/.claude/skills/<slug>-dev-loop/SKILL.md (not ~/.claude/commands/<slug>-dev-loop.md) and emit YAML frontmatter:

---
name: <slug>-dev-loop
description: Autonomous iterative development loop for {{PROJECT_NAME}}. {{IDENTITY_AS_TRIGGER}}
---

<!-- template-version: ... -->
<!-- generated-at: ... -->

# <slug>-dev-loop
...

This is the format the harness actually supports for descriptions. The description: field becomes the real, user-visible trigger string (see how example-a-dev-loop reads in the skill list — it has a full sentence that tells the harness when to invoke). Side effects:

• ~/example-skills-catalog/CONVENTIONS.md "How a skill is placed" table needs a column update.
• The install-instructions block in example-skills-catalog/README.md needs updating.
• Existing skills should be re-installed at the new path (or symlinked from both during transition).
• A new description: row in the Step 4 substitution table — copy IDENTITY framing or compose from the existing first paragraph.

Recommendation

A first, B as a separate follow-up. A unblocks the cosmetic regression immediately (one-line template edit) and the drift-detection comments still work where they are. B is the right strategic move but is a real migration — it touches Step 5, the install convention, CONVENTIONS.md, and every existing skill's location on disk. Worth doing deliberately rather than bundled into a header-placement fix.

Suggested label

template-rule — per the Phase 9 taxonomy (#24), this is a generated-template fix that affects every downstream skill. (Note: this repo doesn't have the Phase-9 labels created yet; that may itself be worth a separate process issue.)

drafted by Claude on behalf of Daniel Stephenson