Fix Broken Links

Fix Broken Links

Scans web files for broken hyperlinks and reports them. For each broken URL the skill tries common spelling variations, optionally hands the link to the GitHub Copilot CLI for suggested replacements, and presents an interactive fix menu. Generic anchor text (click here, read more, etc.) is flagged as an SEO issue.

When to Use This Skill

• User asks to "find broken links", "fix broken links", or "check for dead links / 404s"
• User wants to audit or validate the hyperlinks in edited or changed files
• User wants generic anchor text (click here, here, read more) flagged for SEO
• User wants link checking across HTML, Markdown, JS/TS, JSON, CSS, SQL, or templates

Prerequisites

• curl — HTTP status checks (the script exits quietly if absent)
• grep, sed — link extraction (standard on any POSIX system)
• Bash 4+ for scripts/link-fix.sh; on Windows use Git Bash or WSL, or run the PowerShell 7+ port scripts/link-fix.ps1
• jq — optional; lets the bash script parse a JSON payload piped on stdin
• git — optional; used to discover changed files when no paths are passed (falls back to a full repo scan)
• copilot (GitHub Copilot CLI) — optional; powers agent-suggested replacements. Without it, only verified spelling variations are offered.

How It Works

The script has two modes:

• With file paths (passed as command-line arguments): it checks each link, looks up replacement candidates, and presents the interactive fix menu.
• With no file arguments: it discovers changed files via git (or scans the repo) and simply lists the broken links — no replacement lookups and no prompts.

Links are found by scanning each file for http(s):// URLs, so the same logic covers every format that embeds absolute URLs.

Step-by-Step Workflow

1. Choose the script for the platform

2. Run against the target files

Pass one or more web files to get the full repair flow (lookup + interactive menu):

bash scripts/link-fix.sh docs/guide.md index.html

pwsh scripts/link-fix.ps1 docs/guide.md index.html

Run with no arguments to report broken links in changed files only (no prompts):

bash scripts/link-fix.sh

3. Resolve each broken link

For each broken URL the interactive menu offers:

Supported Source Types

The d (remove) action understands HTML `` wrappers and Markdown [text](url) links specifically, keeping the visible text. Other source types support r (replace) and c (custom) via literal URL substitution.

Features

• Self-contained core: bash and PowerShell ports — no runtime to install
• Format-agnostic link scan: extracts every http(s) URL, covering HTML, Markdown, JS/TS, JSON, CSS, SQL, and templates at once
• Automatic URL healing: tries www, https, and trailing-slash variations
• Agent-assisted suggestions: optionally hands the broken link to the Copilot CLI for replacement candidates; if the CLI is missing or errors, it offers none
• SEO audit: flags anchor text that is too generic to benefit search ranking
• Large-file guard: prompts before checking files with more than 50 links
• Interactive fix menu: replace with suggestion, enter custom URL, strip tag keeping text, or skip

Example Output

  Checking 2 link(s) in docs/guide.md ...
    BROKEN (404) https://example.com/old-page

------------------------------------------------------------
  SEO anchor issues (consider descriptive link text)
    docs/guide.md: click here

============================================================
  fix-broken-links report
============================================================

  [1] docs/guide.md
    URL : https://example.com/old-page
    HTTP: 404

    r  Replace -> https://example.com/docs/install
    1  Replace -> https://example.com/docs/getting-started
    d  Remove link, keep text
    c  Custom replacement URL
    s  Skip
  > r
    replaced

  1 file(s) updated:
    docs/guide.md

With no file arguments (or when a file carries no checkable links) the script stops after the broken-link list — the menu above is skipped.

File Structure

fix-broken-links/
├── SKILL.md            This file
└── scripts/
    ├── link-fix.sh     Bash implementation
    └── link-fix.ps1    PowerShell 7+ port

Limitations

• Only checks absolute http:// and https:// URLs; relative paths require a running server
• Dynamic links generated at runtime from database queries are not detectable from source alone
• When copilot suggestions are enabled, broken URLs are sent to the Copilot service as prompt input
• Agent-suggested replacements are model proposals and are not verified live; confirm each before accepting
• The d (remove) action targets HTML and Markdown link syntax; bare URLs in code are best handled with r or c

Troubleshooting