lychee-redirect-triage
Skill15 starsChanged 6 months agoMITView on GitHub
Triage and resolve a lychee redirect / link-rot finding in ClaudeSec — classify 3xx redirects vs 4xx/5xx rot, resolve to canonical URLs or register an intentional-redirect exclude in BOTH lychee.toml and its guard, then verify. Use when the monthly redirect-sweep opens an issue, lychee prints a redirect/404 WARN, or a link needs triaging before a docs PR.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- scanner/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/claude-agents-and-practices.mdcCursor rule
- .cursor/rules/claudesec-project.mdcCursor rule
- .cursor/rules/markdown-quality.mdcCursor rule
- .cursor/rules/no-sensitive-paths.mdcCursor rule
- .cursor/rules/security-citations.mdcCursor rule
- ci-config-guard-claudesecSkill
- kcov-debugSkill
- omc-referenceSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Use it to turn a redirect / dead-link finding into the *right* fix — not a reflexive exclude that hides real rot.
- Very specific: line 120
All excludes live in lychee.toml (undotted, auto-discovered), consumed via lychee --config lychee.toml.
- Distinctive: line 167
Every real redirect rewritten to its canonical URL (verified 200).
- Distinctive: line 168
Every real 404/5xx fixed or replaced.
- Distinctive: line 169
Every intentional redirect registered in BOTH files.
- Very specific: line 170
No inline --exclude in lint.yml.
- Very specific: line 181
The lychee binary pin is load-bearing: keep lycheeVersion: v0.23.0.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Lychee Redirect / Link-Rot Triage Playbook
Actionable consolidation of ClaudeSec's link-hygiene knowledge (PRs #290–#296).
Use it to turn a redirect / dead-link finding into the right fix — not a
reflexive exclude that hides real rot. Source of truth is always the live
lychee.toml + .github/workflows/lint.yml; re-read them before quoting a flag.
The one thing to internalize first
CI cannot catch link rot for you. The PR-time link-check job runs lychee
with --accept '100..=599', so every 3xx/4xx/5xx response passes CI by design
(this stops flaky external sites from blocking docs merges). So a green
link-check does not mean links are healthy. Two backstops exist instead:
- The monthly redirect-sweep (
lychee-redirect-sweep.yml) re-runs lychee with--max-redirects 0 --accept '200..=299'and files a self-healing issue. - This manual playbook, when you hit a WARN locally or triage a sweep issue.
Corollary: when you inspect a link, capture its FINAL status code, not just the effective URL. A URL that "resolves" in a browser can still be a 404 or an unwanted redirect that CI silently accepted.
Triage decision tree
For each flagged URL, curl it and read the first status (don't let curl follow redirects — you want to see the 3xx itself):
curl -sS -o /dev/null -w '%{http_code} -> %{redirect_url}\n' --max-redirs 0 "<URL>"Then classify:
- 200 (clean) — not a finding; it slipped in via the broad PR accept range or a transient. No action.
- 3xx redirect → a working canonical target — rewrite the Markdown link to the final canonical URL. This is the default for redirects. Do NOT add an exclude; excludes are for redirects that must stay as-written.
- 3xx redirect BY DESIGN (the written URL is the correct entry point and its
target is an auth gate / a versioned file you must not hardcode) — add a
path-specific exclude (see "Registering an intentional redirect"). Known
members of this class in this repo:
github.com/Twodragon0/claudesec/security/advisories/new→ 302 to login when unauthenticated; the/security/advisories/newURL is canonical.developers.kakao.com/tool/debugger/sharing→ 302/303 to a Kakao login.nist.gov/document/...-owasp-samm→ 302 to a versioned PDF; the/document/landing page is the stable citation (the deep PDF path rots faster, not slower).
4xx / 5xx dead link — fix or replace the URL. Only add a
lychee.tomlexclude if the host merely bot-blocks CI but is fine in a browser — then it goes in the "blocks bots / times out" section, NOT the intentional-redirect section.Do not decide this from the status code. The codes that mean bot-block are not a fixed set: measured 2026-09-18,
www.kisa.or.kr/2060305/form?postSeq=12returns 400, which an earlier version of this list did not include (it named 403/429/RST/timeout), so following the list would have classified a live page as rot. Run the differential instead — it is two commands and it answers "fine in a browser" without a browser:curl -sSL -o /dev/null -w '%{http_code}\n' "$URL" curl -sSL -o /dev/null -w '%{http_code}\n' \ -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 \ (KHTML, like Gecko) Chrome/140.0 Safari/537.36' "$URL"Plain non-2xx and browser-UA 2xx ⇒ bot-block, exclude it. Non-2xx in BOTH ⇒ rot, fix the URL. Also probe the site root: a host that 2xx's at
/and non-2xx on the path is more likely rot than a bot policy.The direction matters for which error you would rather make. Excluding a genuinely dead link hides rot silently; treating a bot-block as rot sends someone to "fix" a working URL and, worse, teaches the next reader that this list's status codes are authoritative when they are a sample.
- Release-time 404 (by design) — CHANGELOG version-compare links
(
github.com/Twodragon0/claudesec/compare/...) 404 until the tag publishes. Already excluded; keep it.
What lychee does NOT check — measured 2026-09-18
Both jobs scan '**/*.md' only. Nothing else in the tree is link-checked,
and the most consequential omission is _finding_ref_url in
scanner/lib/output.sh: 15 reference URLs the scanner PRINTS to operators
as "go read this". That is how #559's dead OWASP CI/CD Top 10 link survived in
the runtime path — its seven copies in docs/ were scanned and passed only
because the PR job accepts 100..=599, while the copy the scanner actually
emits was never looked at by either job.
Do not "fix" this by globbing the shell sources. Measured over
scanner/lib/*.sh with the sweep's strict settings: 23 of 23 unique URLs
error, and every one is an API ENDPOINT (api.datadoghq.com 307,
api.datadoghq.eu 403, api.ddog-gov.com 307 …) that the scanner calls rather
than a reference anyone should open. A 307 on an API root means nothing. That
change would add 23 permanent false alarms to a notification-only sweep, and a
sweep that cries wolf is how link rot lost its only detector.
Scoped to scanner/lib/output.sh alone it is tractable — 15 URLs, all
human-facing references, 0 endpoints — but under --max-redirects 0 it still
surfaces 10 redirect items to triage, so it is a real decision with a real
cost, not a free win. Recorded here with its numbers rather than left to be
re-derived; whoever takes it should extract _finding_ref_url's URLs
specifically, not the file.
Until then, the reference URLs are covered only by a hand probe. #559 ran one:
13 of 15 returned 200, one was rot (fixed) and one was the KISA bot-block above.
Where excludes live (single source of truth)
All excludes live in lychee.toml (undotted, auto-discovered), consumed via
lychee --config lychee.toml. NEVER add an inline --exclude to lint.yml —
test_ci_lychee_config.py fails if one reappears (it would split-brain the
allowlist). A dotted .lychee.toml is also forbidden (never auto-discovered →
goes stale).
lychee.toml sections (match by substring of the URL, so a host suppresses
everything under it — prefer a path-specific entry to keep siblings checked):
- Korean gov / public-sector (SSL / bot-block)
- "blocks bots / times out / resets" hosts
- upstream URL-structure churn
- GitHub features not enabled on this repo
- CHANGELOG
compare/release-time 404s # --- Intentional redirects← this section is guarded by an EXACT-COUNT check- localhost / file://
Registering an intentional redirect (case 3) — BOTH files
test_ci_lychee_config.py pins the intentional-redirect section to an exact
count, so adding an entry to lychee.toml alone breaks the guard on purpose
(that's the point — it forces a reviewer to confirm the entry is a real
intentional redirect, not rot disguised as one). Update both:
lychee.toml— add a path-specific entry under# --- Intentional redirects, with a comment explaining why it redirects and why the written URL is canonical.scanner/tests/test_ci_lychee_config.py— add the same URL string to theINTENTIONAL_REDIRECT_EXCLUDEStuple, with a matching comment.
The guard's test_toml_intentional_redirect_excludes_are_exactly_registered
asserts the section and the tuple match exactly (membership + count), and a
mutate-then-verify self-test proves it catches a smuggled 4th entry.
Verify (before opening the docs PR)
# Reproduce the sweep locally (strict): should list only your intended targets.
lychee --config lychee.toml --max-redirects 0 --accept '200..=299' '**/*.md'
# Standard PR-time link check (broad accept — should be clean of hard errors).
lychee "**/*.md" # or: markdownlint "**/*.md" && lychee "**/*.md"
# If you touched lychee.toml or the guard, run the guard:
python3 -m pytest scanner/tests/test_ci_lychee_config.py -qSuccess criteria:
- Every real redirect rewritten to its canonical URL (verified 200).
- Every real 404/5xx fixed or replaced.
- Every intentional redirect registered in BOTH files; guard passes.
- No inline
--excludeinlint.yml; no dotted.lychee.toml.
Pitfalls
- Don't "resolve" an intentional-redirect URL into its target. Rewriting
/security/advisories/newto its login-page redirect target, or the NIST/document/page to a deep versioned PDF path, makes the link more fragile. That's exactly why those are excluded, not rewritten. - Prefer path-specific excludes. A bare host exclude silences every link on
that host, including ones you do want checked (e.g. Kakao's non-redirecting
developers.kakao.com/docs/...links stay checked). - The lychee binary pin is load-bearing: keep
lycheeVersion: v0.23.0. v0.24.x nests the binary in alychee-<triple>/subdir the pinned lychee-action installer can't find (install: cannot stat). #204 bumped it and broke CI; reverted in #209/#210. codecov badge SVG stays on apex— moot since 2026-09-03: the badge was removed fromcodecov.ioREADME.mdalong with the upload step, so no codecov URL is left for lychee to follow. Kept as a struck-through note rather than deleted, because the underlying rule still applies to any badge host — an apex that redirects to anapp.subdomain is canonical, not rot.- A green PR
link-checkis not proof of link health — see the top section.
Related
scanner/tests/test_ci_lychee_config.py— the exclude single-source + exact-count guard.scanner/tests/test_ci_lychee_redirect_sweep.py— guards the monthly sweep workflow..github/workflows/lychee-redirect-sweep.yml— the automated monthly backstop.ci-config-guard-claudesecskill — for authoring a new guard around any of this.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

