Repository navigation
fix(plugins): a skill links only inside itself - #772
Merged
Merged
Conversation
`architecture.md` has stated the rule since the per-tool distributions landed — a skill never links outside itself, because the tree ships both flat and as a marketplace and no relative path survives both — and nothing enforced it. The one checker that looks at links cannot: `check-markdown-links.js` resolves every path against this repository, where the target does exist. A link reaching out of a skill is green there and dead in every installed copy. Five had accumulated. Three point at `aidd_docs/product/cost-report-contract.md`, which no plugin ships at all, so a reader of an installed `aidd-telemetry` was sent to a file that was never in the package. A fourth pointed at the plugin's own README, which is no more reachable than the repository once a tool has installed the skill somewhere of its own choosing — the boundary is the skill, not the plugin. Each becomes a name in prose: a reader can search for a name, and a name cannot rot into a broken link. The guard reads every markdown under `plugins/<plugin>/skills/<skill>/`, resolves each relative link, and fails on one landing outside that directory. It ships with a second test that puts an escaping link in front of it and requires it to be seen — a boundary check that never trips reads exactly like a clean tree, which is the state the existing checker was already reporting. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
architecture.mdhas stated the rule since the per-tool distributions landed:Nothing enforced it, and the one checker that looks at links cannot:
check-markdown-links.jsresolves every path against this repository, where the target does exist. A link reaching out of a skill is green there and dead in every installed copy.Five had accumulated:
aidd-dev/skills/01-plan/SKILL.md../../../../aidd_docs/runs/README.mdaidd-telemetry/skills/01-cost/actions/03-report.md../../../../../aidd_docs/product/cost-report-contract.md× 3aidd-telemetry/skills/01-cost/actions/03-report.md../../../README.mdThree point at
aidd_docs/product/cost-report-contract.md, which no plugin ships at all — a reader of an installedaidd-telemetrywas sent to a file that was never in the package.The boundary is the skill, not the plugin.
../../../README.mdstays insideplugins/aidd-telemetry/and is still wrong: a tool installs a skill somewhere of its own choosing, and the plugin's README is no more reachable from there than the repository is.Change
Every one of the five becomes a name in prose. A reader can search for a name; a name cannot rot into a broken link.
The guard
scripts/__tests__/a-skill-links-only-inside-itself.test.jsreads every markdown underplugins/<plugin>/skills/<skill>/, resolves each relative link, and fails on one landing outside that skill's own directory.It ships with a second test that puts an escaping link in front of it and requires it to be seen. Without that, a boundary check that never trips reads exactly like a clean tree — which is the state
check-markdown-links.jswas already reporting.plugins/<plugin>— 1Both were killed by the probe test, which is the point of it.
CI runs it:
cli CIfilters onscripts/__tests__/**and executesnode --test "scripts/__tests__/*.test.js", as does lefthook's pre-commit.Gates: 371 repository script tests (369 + the two new), 0 broken links,
check-markdown-links.jsclean.🤖 Generated with Claude Code
https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp