Install scripts register review/annotate/last as BOTH a command and a skill — skill now shadows the command on Claude Code

[backnotprop]

Summary

On Claude Code, /plannotator-review (and /plannotator-annotate, /plannotator-last) stopped auto-running and instead fired as a prose skill that asks the agent to run the command itself. Root cause: our install scripts register the same three names twice in ~/.claude/ — once as an auto-running command, once as a prose skill — and a recent Claude Code update flipped name-collision precedence so the skill shadows the command.

What the install does (the collision)

scripts/install.sh writes, in a single run:

• Commands → ~/.claude/commands/plannotator-{review,annotate,last}.md via heredoc (lines ~656–710). These contain the auto-run form, e.g. !`plannotator review $ARGUMENTS`. (Present since Feat/code review system #57, 2026-01-12.)
• Skills → cp -r apps/skills/* "$CLAUDE_SKILLS_DIR/" at line 815, which blanket-copies everything, including plannotator-{review,annotate,last} (the prose "agent, run the command yourself" skills) into ~/.claude/skills/. (Present since feat: install skills via git sparse-checkout #390, 2026-03-25.)

So Claude Code ends up with two definitions per name:

Name	~/.claude/commands/*.md (auto-run !-shell)	~/.claude/skills/*/SKILL.md (prose)
plannotator-review	yes	yes
plannotator-annotate	yes	yes
plannotator-last	yes	yes

Why it broke now

The colliding files have coexisted for ~2 months. What changed is Claude Code itself updated (to 2.1.156/2.1.157). Old CC resolved /plannotator-review to the command (auto-ran); the new CC resolves it to the skill (prose) → nothing auto-runs. The skill content never changed (SKILL.md had name: plannotator-review from #644 onward); only CC's collision precedence flipped.

We were unknowingly relying on CC's old precedence to paper over a name collision we created. That's fragile, and CC just proved it.

Inconsistency in the script

The script already treats these three as special everywhere except the Claude block:

• Codex (install.sh ~819–823): copies review/annotate/last individually, only when codex present.
• Shared agents (~816–818): copies only compound/setup-goal/visual-explainer.
• Claude (815): cp -r * — everything, undiscriminated. ← the bug.

compound/setup-goal/visual-explainer legitimately belong in ~/.claude/skills/ (no command equivalent). review/annotate/last are commands on Claude Code and should NOT also be installed as skills there.

Proposed fix

In scripts/install.sh, replace the blanket cp -r apps/skills/* (line 815) with selective copies of only the agent skills:

copy_skill_if_present apps/skills/plannotator-compound         "$CLAUDE_SKILLS_DIR"
copy_skill_if_present apps/skills/plannotator-setup-goal       "$CLAUDE_SKILLS_DIR"
copy_skill_if_present apps/skills/plannotator-visual-explainer "$CLAUDE_SKILLS_DIR"

Do NOT copy review/annotate/last into Claude's skills dir — they're already installed as commands. Mirror the same change in scripts/install.ps1 and scripts/install.cmd, and update assertions in scripts/install.test.ts.

The installer should probably also clean up the stale shadowing skill dirs on upgrade (~/.claude/skills/plannotator-{review,annotate,last}) so existing installs self-heal.

Local workaround (verified)

rm -rf ~/.claude/skills/plannotator-{review,annotate,last}

Leaves the agent skills intact; the commands take over again on next Claude Code session.

Evidence

• ~/.claude/skills/plannotator-review/SKILL.md: name: plannotator-review, single commit (Feat: add Codex Plannotator skills #644) — unchanged.
• ~/.claude/commands/plannotator-review.md: auto-run !`plannotator review $ARGUMENTS`.
• CC versions: 2.1.157 installed today; 2.1.153 prior. Behavior flipped across this update.