Help us improve
Share bugs, ideas, or general feedback.
From superpowers
Audits and repairs Markdown link health across a repo using a four-tier pipeline (config hardening, intra-repo fixes, URL substitutions, residual exclusions). Designed for lychee-based CI link checkers.
npx claudepluginhub lunartech-x/superpowers --plugin superpowersHow this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers:link-healthThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A reusable methodology for bringing a broken docs-heavy repo's link checker to green. Codified from a real audit that took `AlterLab-IEU/AlterLab-Academic-Skills` from **1208 errors out of 1966 links** to **0 errors out of 1912 links** across 8 commits, with an auto-detected Tier 3 regression that validated the guardrail rule.
Audits and repairs Markdown link health across a skills repo via a four-tier pipeline (config hardening, intra-repo file-ref fixes, external URL substitutions, residual exclusions) with a regression guardrail.
Finds broken links in local repos (HTML/MD/MDX), single live pages, or full sites via Ahrefs MCP. Use for dead link checks, 404 fixes, and redirect chain audits.
Validates Markdown documentation links, detecting broken relative links, missing anchor targets, malformed URLs, and orphaned documentation files. Use before releases or doc updates.
Share bugs, ideas, or general feedback.
A reusable methodology for bringing a broken docs-heavy repo's link checker to green. Codified from a real audit that took AlterLab-IEU/AlterLab-Academic-Skills from 1208 errors out of 1966 links to 0 errors out of 1912 links across 8 commits, with an auto-detected Tier 3 regression that validated the guardrail rule.
Full audit (fresh repo, failing link checker):
Audit and repair the link health of <owner/repo>. Run the full four-tier pipeline.
→ Dispatch the 10-agent audit from playbooks/full-audit.md, then the tiered APPLY phase.
Targeted residual pass (first dispatch reduced errors but some remain):
The link checker is down from 1208 to 67 errors. Close the residuals.
→ Dispatch the 3-agent followup pass from playbooks/followup-pass.md.
Post-merge cleanup (PR is green, need to finalize human-decision items):
Finalize the post-merge cleanup: resolve pending human-decision items, file follow-up issues, document link debt.
→ Dispatch the 4-agent post-merge pass from playbooks/post-merge.md.
English: link audit, dead links, link health, lychee, broken links, link checker, markdown link audit, link-health audit, 404 audit, check-links failing, CI link-check
繁體中文: 連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計
Check Links (or similar lychee / markdown-link-check) workflow has been failing.| Scenario | Skill / Tool to Use Instead |
|---|---|
| Fix a single broken link in a single file | Direct Edit — no pipeline needed |
| Add a new URL to skill docs | alterlab-scientific-writing or the relevant domain skill |
| Audit citations (DOI resolution, author verification) | alterlab-paper-reviewer integrity-check mode |
| Audit repo structure beyond links (schema, metadata) | Separate schema-drift audit (out of scope) |
Each tier is a single reviewable commit. Run them in order — each unlocks the next by making the error signal cleaner.
| Tier | Scope | Typical Delta |
|---|---|---|
| 1 — Config | Introduce .lychee.toml with an additive accept set, a .lycheeignore for permanent noise hosts, and a hardened CI workflow. | Biggest single win — often -70% to -90% of errors. Fixes the "--accept 403 replaces the default set" gotcha. |
| 2 — Intra-repo refs | Repair [ERROR] file:// entries: singular/plural directory typos, missing path prefixes, YAML frontmatter bugs. Wrap pedagogical placeholder paths as inline code. | Eliminates the bulk of real breakage — usually 200-400 entries collapse to zero. |
| 3 — URL substitutions | Replace MOVED external URLs with verified-live substitutes; replace DEAD_INFRA URLs with replacement resources. Never substitute without verification. | Reduces residuals to the low dozens. |
| 4 — Exclusions | Everything left that cannot be fixed: bot-hostile hosts, pedagogical placeholders, expired upstream infrastructure, chronically flaky academic sites. | Gets to 0 errors or stable single-digit residuals. |
See references/tier1-config.md through references/tier4-exclusions.md for the decision rules in each tier.
After any URL substitution pass, re-run the link checker and diff against the baseline success set. Any URL that returned 200 OK in baseline and is non-200 after substitution is a regression and MUST be reverted before commit.
Self-check:
diff <(grep "^\[200\]" baseline.log | sort -u) \
<(grep "^\[200\]" post.log | sort -u)
Output should show no deletions, only additions. Deletions mean a substitution regressed a previously-working URL.
This rule exists because during the source audit, broad sed prefix substitutions silently concatenated onto more-specific paths (e.g. /v3/ → /v3/docs turned an already-correct /v3/docs into /v3/docsdocs). The guardrail caught it on the second CI dispatch, not the commit itself. Assume your Tier 3 pass will have regressions. Verify.
Full detail: references/tier3-substitution.md.
DEFAULT to probe-verification before any URL substitution. Unverified substitutions are how phantom URLs land in public skills. Before every [old] → [new] replacement:
gh api repos/owner/name — status must be 200 (repo exists, not archived).curl -sSI -L --max-time 15 '<new>' — final status must be 200 (after redirects).If verification fails, exclude the dead target via .lycheeignore with a commented reason rather than guessing a replacement. An excluded dead link is honest; a substituted wrong link is a time bomb.
Full detail: references/tier3-substitution.md § "Verification rules".
Three ready-to-dispatch prompt bundles that call this skill's tiers in the right order.
| Playbook | When to Use | Agents |
|---|---|---|
playbooks/full-audit.md | Fresh audit, failing CI, no prior work. | 10 parallel subagents + synthesis |
playbooks/followup-pass.md | Errors significantly reduced but residuals remain. | 3 targeted subagents |
playbooks/post-merge.md | PR green, time to resolve pending human-decision items. | 4 parallel subagents |
All three follow the same shape: pre-flight → parallel dispatch → synthesize → commit/PR/merge → verify.
| File | Content |
|---|---|
references/tier1-config.md | .lychee.toml schema, workflow YAML, accept-code gotchas |
references/tier2-intra-repo.md | Intra-repo path audit, singular/plural directory patterns, frontmatter fixes |
references/tier3-substitution.md | URL substitution rules, the guardrail, sed-safety patterns |
references/tier4-exclusions.md | When to exclude vs substitute, .lycheeignore category rubric |
references/known-debt-template.md | The 5-category KNOWN_LINK_DEBT.md layout for maintainers |
examples/pr-1-retrospective.md — the source audit that generated this skill. 1208 → 0 errors, 8 commits, auto-detected Tier 3 regression in commit 5 (9cbd801), merged as 93a72fe.This skill fixes link health. It does NOT:
.lychee.toml's accept list to mask real breakage. Flaky upstream 5xx / timeouts get excluded per-host with rationale, not blanket-accepted.Scope discipline keeps the PR reviewable and the link-check signal honest.