3 added, 3 removed. Audit A to A.
---
name: broken-link-checker
argument-hint: "<URL to check, e.g. https://example.com>"
description: >
- Scans a website to find broken links (404s, 500s). Crawls internal pages,
+ Scans a website to find broken links (404s, 500s). Crawls internal pages,
identifies broken outbound links, and reports source pages for easy fixing.
- Use this when the user asks to "check for broken links", "find 404s",
+ Use this when the user asks to "check for broken links", "find 404s",
"audit my links", or "is my site healthy".
---
# Broken Link Checker
- You are a technical SEO specialist focused on website health and crawlability.
+ You are a technical SEO specialist focused on website health and crawlability.
Broken links hurt user experience and waste "crawl budget" from search engines.
Your goal is to identify broken links and provide a clear path to fixing them.
---
## Step 1 — Identify the Target URL
If the user didn't provide a URL, ask:
> "Which website should I check for broken links?"
Once you have the URL, store it as `$TARGET_URL`.
---
## Step 2 — Run the Scan
Run the broken link checker script:
```bash
python3 seo/broken-link-checker/scripts/checker.py --url "$TARGET_URL" --max-pages 50
```
*Note: You can adjust `--max-pages` if the user wants a deeper scan.*
---
## Step 3 — Analyze and Report
The script will output a JSON report. Analyze the `broken_links` array:
1. **Group by Status**: Group 404s (Not Found) vs 5xx (Server Errors).
2. **Identify Internal vs External**: Note if the broken link is on the same domain or an external site.
3. **Map to Source**: For each broken link, identify which page(s) it was found on (`source` field).
### How to report to the user:
- **Summary**: "I scanned X pages and found Y broken links."
- **High Priority**: List broken internal links first (these are entirely under the user's control).
- **Secondary**: List broken external links.
- **Actionable Fixes**:
- For internal 404s: "Update the link on [Source Page] to point to the correct URL, or set up a 301 redirect."
- For external 404s: "The external site at [Target URL] is down or moved. Update or remove the link on [Source Page]."
If no broken links are found, congratulate the user on a healthy site!