alterlab-link-health

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-link-health

Audits and repairs Markdown link health across a skills repo via a four-tier pipeline.

  • Fixes broken links in Markdown repos to pass CI link checks.
  • Works with lychee, markdown-link-check, and GitHub Actions.
  • Uses a four-tier pipeline: config, intra-repo fixes, URL substitutions, exclusions.
  • Outputs a clean link checker run with zero errors and a regression guardrail.

SKILL.md

.github/skills/alterlab-link-healthView on GitHub ↗
---
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: Targets lychee-based GitHub Actions link checkers (generalizes to markdown-link-check); no external API key or account required
metadata:
  skill-author: AlterLab
  version: "1.0"
  last_updated: "2026-04-21"
  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`.

---

## Trigger Conditions

### 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

**繁體中文**: 連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計

### When This Skill Applies

- 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.

### Non-Trigger Scenarios

| 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 |
| Verify a bibliography actually exists (DOI/author resolution, fabricated/hallucinated citations) | `alterlab-citation-verifier` — it cross-checks Crossref/OpenAlex/Semantic Scholar/arXiv. Link-health only repairs broken hyperlinks in docs; it never validates that a cited work exists. |
| Audit repo structure beyond links (schema, metadata) | Separate `schema-drift` audit (out of scope) |

---

## 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 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.

---

## 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 and MUST be reverted before commit.

**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

**DEFAULT to probe-verification 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.

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.