playbooks: repo-sweep skill-version.sh stamps every unprefixed skill @builtin, with no version and no existence check

[kyle-sexton]

Problem

skills/repo-sweep/scripts/skill-version.sh lines 23-25 print <name>@builtin for any argument without a plugin: prefix. It records no version and never checks that the skill exists:

• skill-version.sh no-such-skill-xyz prints no-such-skill-xyz@builtin. SKILL.md line 39 says a skill that is not installed gets @unknown.
• An unprefixed name also resolves to a project or personal skill, and a same-named skill replaces the bundled one (skills docs: "Your skill replaces the bundled command, but not its aliases."). A repo with its own claude-api skill is still recorded as claude-api@builtin.
• history.sh line 76 treats @builtin as not comparable, so a bundled-skill entry is rerun-optional forever, and the Playbook-Step trailer carries no version to compare later.

Root cause in the docs: SKILL.md line 52 says a catalog - skill: line takes plugin:skill names, but catalogs/hygiene.md line 135 uses bare claude-api and catalog.sh does not check the format. SKILL.md line 38's "missing skill" wording for exit 1 means an entry with no skill line, not a skill that is not installed.

Evidence

melodic-software/.github#153, step prompt-audit: checklist line and trailer recorded claude-api@builtin. The bundled skill was loaded from /tmp/claude-1000/bundled-skills/2.1.283/...; claude --version printed 2.1.283 (Claude Code).

Fix

Cheapest first:

1. Correct SKILL.md lines 38, 39 and 52 and the script header: bare names are allowed for bundled skills, and say what exit 1 means.
2. Before stamping @builtin, probe .claude/skills/<name>/ in the repo and ~/.claude/skills/<name>/; a hit is a project or personal skill, not a bundled one.
3. Stamp bundled skills with the Claude Code version, for example claude-api@builtin-2.1.283, and compare it in history.sh line 76. Existing @builtin records then compare unequal, so each bundled-skill entry reports rerun once after the change. Update the tests that assert the current form: skill-version.test.sh lines 51 and 55, history.test.sh lines 37, 41, 68 and 84, render.test.sh line 35.

Unverified: that a bundled skill's version always equals the Claude Code version. It is inferred from the bundled-skills path; no docs page states it.

[kyle-sexton]

This was generated by AI during triage.

Verified. On main (ecbcdc5), the repo-sweep skill-version script prints no-such-skill-xyz@builtin and exits 0 for a nonexistent unprefixed name, contradicting the skill's documented @unknown for a skill that is not installed. The hygiene catalog's prompt-audit entry uses the bare name claude-api while the catalog format section documents plugin:skill only, and the history recommender treats a builtin current version as equal to any prior record, so a bundled-skill entry can only ever be rerun-optional. No duplicate among open repo-sweep issues; no existing implementation of an existence check or bundled-skill version stamp.

Priority set to priority: medium (assessed default; blocks no other work).

Decision defaulted: stamp bundled skills @builtin-<claude-code-version> taken from claude --version — veto before merge. Alternative (maintainer-vetoable, reversible): keep a versionless @builtin and fix only the docs and the existence check. The default rests on an inference (bundled skills load from a path keyed on the Claude Code version) that no docs page states.

Agent Brief

Type: Bug
Summary: The repo-sweep skill-version resolver stamps every unprefixed skill name @builtin without checking it exists or recording a version, and the skill's docs disagree with the catalog about whether bare names are allowed.

Current behavior:

• Any argument without a plugin: prefix prints <name>@builtin, exit 0, even when no such skill exists and even when a project or personal skill of the same name overrides the bundled one.
• The history recommender treats builtin as matching any prior record, so a bundled-skill catalog entry never recommends rerun.
• The repo-sweep skill doc says catalog - skill: lines take plugin:skill names and that a non-installed skill gets @unknown; the hygiene catalog uses a bare bundled name; the catalog parser's "missing skill" exit reason really means an entry with no skill line.

Desired behavior:

• Docs (skill doc Scripts table, Formats section, and the resolver's header comment) state that bare names are allowed for bundled skills, and that the catalog's exit 1 "missing skill" means an entry with no - skill: line.
• For an unprefixed name, the resolver first checks for a project skill (.claude/skills/<name>/ in the repo) and a personal skill (~/.claude/skills/<name>/); a hit is not stamped as bundled (stamp it distinguishably, e.g. @project / @personal, or @unknown; the implementer picks one and documents it).
• An unprefixed name that is neither a project nor a personal skill is stamped with the Claude Code version, e.g. claude-api@builtin-2.1.283 (see the defaulted decision above); when the version cannot be read, @unknown.
• The history recommender compares bundled-skill versions like any other version: an old versionless @builtin record against a new @builtin-<ver> yields rerun once.

Key interfaces:

• skill-version resolver output line <name>@<version> and its header comment
• history recommender's current-vs-last version comparison (builtin special case)
• repo-sweep skill doc: Scripts table rows for the catalog parser and the resolver; catalog Formats - skill: rule

Acceptance criteria:

• A nonexistent bare name no longer prints @builtin.
• A bare name shadowed by a project or personal skill is not stamped as bundled.
• A genuine bundled skill prints @builtin-<claude --version number>.
• The history recommender returns rerun for a bundled entry whose recorded stamp differs from the current one, and rerun-optional when equal.
• The resolver, history, and render test scripts are updated to the new form and pass.
• Skill doc and resolver header describe bare-name handling and the catalog exit-1 meaning accurately.

Out of scope:

• Changing which skills the hygiene catalog runs.
• Plugin-prefixed version resolution.
• Other open repo-sweep issues (e.g. playbooks: repo-sweep review has no route for bundled-skill or repo-sweep defects #4604, review routing for bundled-skill defects).