alterlab-link-health
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) and enforces a Tier 3 substitution guardrail that prevents regressions of previously-passing links;
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/core/alterlab-link-health
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Link Health — Repo-wide Markdown Link Audit Methodology
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.
Quick Start
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.
When to Use This Skill
- A weekly
Check Links(or similar lychee / markdown-link-check) workflow has been failing. - The user mentions a large error count (hundreds+) that they suspect is mostly config-driven false positives.
- The user wants to refactor broken intra-repo file references across many skills / docs.
- The user wants a reusable process for link debt maintenance going forward.
Trigger keywords — 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. 繁體中文: 連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計.
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Verify that cited works exist (DOI/author resolution, fabricated or hallucinated references, retractions) | alterlab-citation-verifier — link-health only repairs hyperlinks; it never validates that a cited work exists |
| Fix a single broken link in a single file | A direct edit — no pipeline needed |
| Audit repo structure beyond links (schema, frontmatter, metadata) | A separate schema-drift audit (out of scope here) |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-citation-verifier) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Pipeline Overview (4 Tiers)
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 explicit accept set (it replaces lychee's defaults, so list 200..=299), 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.
The Tier 3 Guardrail
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; revert it before committing.
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.
The Verification-First Rule
Probe-verify before any URL substitution. Unverified substitutions are how phantom URLs land in public skills. Before every [old] → [new] replacement:
- For GitHub repos:
gh api repos/owner/name— status must be 200 (repo exists, not archived). - For HTTP URLs:
curl -sSI -L --max-time 15 '<new>'— final status must be 200 (after redirects). - For PyPI / npm / crates packages: check the registry API or landing page directly.
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".
Playbooks
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.
References
| 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
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 as93a72fe.
Scope Discipline
This skill fixes link health. It does NOT:
- Standardize SKILL.md schemas across the repo. File schema drift as a separate issue.
- Refactor skill content, examples, or prose. Only touches link URLs and the CI config.
- Modify
.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.
Part of the AlterLab Academic Skills suite.
Files (alterlab-academic-skills)
-
evals
-
fixtures
-
docs-mlc
-
docs
-
images
-
diagram.png 16 B · in bundle
-
-
getting-started.md 232 B
Loading… -
installation.md 115 B
Loading…
-
-
markdown-link-check-output.txt 399 B
Loading…
-
-
our-docs
-
.github
-
workflows
-
links.yml 262 B
Loading…
-
-
-
docs
-
references
-
api.md 88 B
Loading…
-
-
guide.md 438 B
Loading… -
installation.md 80 B
Loading…
-
-
.lychee.toml 72 B
Loading… -
contributing.md 52 B
Loading… -
README.md 454 B
Loading…
-
-
lychee-ci-log.txt 1.7 KB
Loading… -
residual-errors.txt 1.3 KB
Loading…
-
-
evals.json 4.1 KB
Loading…
-
-
examples
-
pr-1-retrospective.md 6.6 KB
Loading…
-
-
playbooks
-
followup-pass.md 3.5 KB
Loading… -
full-audit.md 4.5 KB
Loading… -
post-merge.md 4.3 KB
Loading…
-
-
references
-
known-debt-template.md 3.7 KB
Loading… -
tier1-config.md 6.7 KB
Loading… -
tier2-intra-repo.md 4.4 KB
Loading… -
tier3-substitution.md 5.6 KB
Loading… -
tier4-exclusions.md 4.5 KB
Loading…
-
-
SKILL.md 8.9 KB
--- name: alterlab-link-health description: "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) and enforces a Tier 3 substitution guardrail that prevents regressions of previously-passing links; designed for lychee-based GitHub Actions link checkers but generalizes to markdown-link-check and similar tools. Use when the request mentions 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, or 連結健檢, 死鏈, 失效連結, 斷鏈檢查. Part of the AlterLab Academic Skills suite." license: MIT allowed-tools: Read Write Edit Bash WebFetch WebSearch compatibility: No API key required. Targets lychee-based GitHub Actions link checkers (generalizes to markdown-link-check); lychee also runs locally with no token or account metadata: skill-author: AlterLab version: "1.1.2" last_updated: "2026-11-02" credentials: "optional: GITHUB_TOKEN (lets lychee authenticate github.com URLs for a higher rate limit; in GitHub Actions the workflow's built-in secrets.GITHUB_TOKEN is enough, no personal token)" source_audit: "AlterLab-IEU/AlterLab-Academic-Skills PR #1 (merged 2026-04-21 as 93a72fe)" --- # Link Health — Repo-wide Markdown Link Audit Methodology 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. ## Quick Start **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`. --- ## When to Use This Skill - A weekly `Check Links` (or similar lychee / markdown-link-check) workflow has been failing. - The user mentions a large error count (hundreds+) that they suspect is mostly config-driven false positives. - The user wants to refactor broken intra-repo file references across many skills / docs. - The user wants a reusable process for link debt maintenance going forward. **Trigger keywords** — 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. 繁體中文: 連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計. ### Does NOT Trigger | Scenario | Use Instead | |----------|-------------| | Verify that cited works exist (DOI/author resolution, fabricated or hallucinated references, retractions) | `alterlab-citation-verifier` — link-health only repairs hyperlinks; it never validates that a cited work exists | | Fix a single broken link in a single file | A direct edit — no pipeline needed | | Audit repo structure beyond links (schema, frontmatter, metadata) | A separate schema-drift audit (out of scope here) | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-citation-verifier`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. --- ## Pipeline Overview (4 Tiers) 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 explicit accept set (it replaces lychee's defaults, so list `200..=299`), 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. --- ## The Tier 3 Guardrail 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; revert it before committing. **Self-check:** ```bash 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`. --- ## The Verification-First Rule **Probe-verify before any URL substitution.** Unverified substitutions are how phantom URLs land in public skills. Before every `[old] → [new]` replacement: 1. For GitHub repos: `gh api repos/owner/name` — status must be 200 (repo exists, not archived). 2. For HTTP URLs: `curl -sSI -L --max-time 15 '<new>'` — final status must be 200 (after redirects). 3. For PyPI / npm / crates packages: check the registry API or landing page directly. 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". --- ## Playbooks 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**. --- ## References | 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 - `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`. --- ## Scope Discipline This skill fixes *link health*. It does NOT: - Standardize SKILL.md schemas across the repo. File schema drift as a separate issue. - Refactor skill content, examples, or prose. Only touches link URLs and the CI config. - Modify `.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. Part of the AlterLab Academic Skills suite.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.