docs(skills): add docsite-link-sweep maintainer skill - #4071
Draft
twishabansal wants to merge 2 commits into
Draft
twishabansal wants to merge 2 commits into
twishabansal wants to merge 2 commits into
Conversation
Sweeps the docs for broken and non-canonical links, reports each finding with the reason it breaks, and applies the safe class of internal link fixes to the working tree. The skill exists because the two checkers guarding these docs disagree: lychee resolves links as filesystem paths and knows nothing about Hugo, while Hugo resolves .md links to pretty URLs and generates whole classes of links from shortcodes but never checks an external URL. A link can pass one and break the other. Covers four failure modes neither checker reports on its own: directory style links that lychee cannot resolve, site-absolute links that leak out of /dev/ and versioned builds to the latest-release docs, shortcode generated links that appear only in built HTML, and links into ignoreFiles paths that resolve on disk but 404 on the site. Every command in the skill was run against this repo before being written down.
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a new AI agent skill, docsite-link-sweep, along with supporting reference documentation (link-forms.md and a reference to DEVELOPER.md) to help maintainers sweep the mcp-toolbox documentation for broken and non-canonical links. The review feedback suggests replacing absolute GitHub URLs pointing to repository configuration files (such as .lycheeignore, workflow files, and hugo.toml) with workspace-relative paths, ensuring the local AI agent can read the current state of the workspace files directly without making unnecessary network requests.
…ychee Every lychee workflow in the repo is currently disabled_manually, so the skill no longer claims CI checks links. Step 1 now queries workflow state and tells the sweep to report when it is the only link checking happening.
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.
Description
Adds a
docsite-link-sweepmaintainer skill: it sweeps the docs for broken and non-canonical links, reports each finding with the reason it breaks, and applies the safe class of internal link fixes. It exists because the repo's two checkers disagree. lychee resolves links as filesystem paths and knows nothing about Hugo; Hugo resolves.mdlinks to pretty URLs and generates whole classes of links from shortcodes, but never checks an external URL. The skill targets that gap: directory-style links lychee cannot resolve, site-absolute links that leak out of/dev/and versioned builds, shortcode-generated links that exist only in built HTML, and links intoignoreFilespaths that resolve on disk but 404 live. Fixes are limited to five mechanical rewrite classes, each verified against both checkers; everything else is reported, not applied. Tracked intoolbox-skills/ideas.md.PR Checklist
!if this involves a breaking change