Relationships
#565 Managed skills ship with dangling reference-doc links
Opened by jentz · 6/5/2026· Shipped 6/5/2026
Description
swamp repo upgrade (version 20260605.000321.0) installs managed skills whose SKILL.md files link to reference docs that are not bundled in the release. The links resolve to nonexistent files, so any agent (or human) that follows them hits a dead end. This is self-evident in the swamp-issue skill itself, whose documented sanitize/version-check states point at missing files.
Affects both the .claude/ and .agents/ skill trees identically.
Missing files
swamp-issue/references/ (present: formatting.md, output_shapes.md):
sanitization.md— linked fromSKILL.mdlines 85, 170, 226 andreferences/formatting.mdline 6version_check.md— linked fromSKILL.mdline 186 (the version_check state of the bug-report workflow)
swamp-report/references/ (present: report-types.md, testing.md):
control-model.md— linked fromSKILL.mdlines 72, 180filtering.md— linked fromSKILL.mdlines 73, 182
Steps to reproduce
- In a swamp-managed repo, run
swamp repo upgradeto version20260605.000321.0. - Open
.claude/skills/swamp-issue/SKILL.mdand follow the link toreferences/sanitization.md. - The target file does not exist under
references/(onlyformatting.mdandoutput_shapes.mdare shipped). - Same for
version_check.md, and forcontrol-model.md/filtering.mdin the swamp-report skill.
Expected
Either the four reference docs are bundled with the skills, or the SKILL.md files do not link to them.
Actual
The docs are referenced but absent, breaking the documented workflows (notably the swamp-issue bug-report state machine, which instructs the agent to read sanitization.md and version_check.md).
Environment
- swamp
20260605.000321.0 - Detected via GitHub Copilot review on a routine upgrade PR; confirmed by filesystem check in both
.claude/and.agents/trees.
Shipped
Click a lifecycle step above to view its details.