When to Use This Skill

/link-checker

Validate external URLs (HTTP/HTTPS) found in Markdown notes. Uses curl for reliable bulk URL validation and parallel Haiku agents to check batches of 10-15 URLs simultaneously, detecting dead links, redirects, and timeouts.

When to Use This Skill

• Periodic maintenance to find dead external links
• Validating reference notes with URLs
• Checking links before publishing or sharing content
• Post-migration validation of external references
• Quarterly vault health reviews

Usage

/link-checker [--scope path/to/folder] [--timeout 10] [--include-redirects] [--fix] [--update]

Parameters

Instructions

Phase 1: Extract External URLs

1. Scan Markdown files in scope
2. Extract URLs matching patterns:
   • [text](https://...) -- Standard Markdown links
   • url: "https://..." -- Frontmatter URL fields
   • Bare URLs in text (https://...)
3. Deduplicate -- Same URL referenced from multiple files should only be checked once
4. Build URL-to-files map -- Track which files reference each URL
5. Divide into batches of 10-15 URLs per agent

Phase 2: Batch URL Validation -- Agent Team (Parallel Haiku Agents)

Use the Batch Processing pattern. Launch N parallel agents.

Agent 1-N: URL Checker (Haiku) Task: Validate assigned batch of URLs

For each URL, use the curl-based validation script via the Bash tool:

#!/bin/bash
# URL validation script -- run via Bash tool for each URL

URL="$1"
TIMEOUT="${2:-10}"

# Follow redirects, capture final status code
STATUS=$(curl -I -L -s -o /dev/null -w "%{http_code}" --max-time $TIMEOUT "$URL" 2>/dev/null)

if [ -z "$STATUS" ] || [ "$STATUS" = "000" ]; then
  echo "error:timeout"
else
  # Also capture redirect target if applicable
  REDIRECT=$(curl -I -L -s -o /dev/null -w "%{url_effective}" --max-time $TIMEOUT "$URL" 2>/dev/null)
  echo "status:$STATUS|redirect:$REDIRECT"
fi

Classify each result:

For failed URLs (error or dead), attempt one retry after 2 seconds before finalising the classification.

Return: List of { url, status, classification, redirectUrl, error } per URL

Phase 3: Synthesis and Cross-Reference Checking

1. Categorise results:
   • Active (200-299) -- Working fine
   • Redirected (301/302/307/308) -- URL has moved
   • Dead (404, 410, DNS failure) -- Definitely dead
   • Error (timeout, 403, 5xx) -- May be temporary
2. Map broken URLs to source files
3. Cross-reference dead links -- For each dead or errored link, check which other notes reference it:

# Find all notes that reference a dead link's note title
grep -rl "Reference - Old API Guide" *.md Meetings/ Projects/ ADRs/ Tasks/

This identifies notes that depend on the dead reference, so they can be updated or the link removed.

4. Suggest fixes for broken links (e.g., Wayback Machine URL, updated URL from redirect chain)

Phase 4: Update Frontmatter (if --fix)

When the --fix flag is provided, update frontmatter on each checked note with link health metadata:

# Frontmatter fields added/updated by --fix
url: https://example.com/page
linkStatus: active | redirected | dead | error
lastChecked: 2026-01-10
redirectUrl: https://new-location.com/page  # Only if redirected

Field definitions:

Rules for frontmatter updates:

• Only update notes that have a url field in frontmatter
• Set lastChecked to today's date for all checked URLs
• Set linkStatus based on the classification from Phase 2
• Add redirectUrl only when status is redirected; remove it if status changes to active
• Use the Edit tool to modify frontmatter in-place (do not rewrite the entire file)

Phase 5: Update Redirected URLs (if --update)

When the --update flag is provided, offer to replace redirected URLs with their final destination:

1. List all redirected URLs with their original and final URLs
2. For each redirected URL:
   • Show the original URL and the redirect target
   • Update the url field in frontmatter to the redirect target
   • Set linkStatus to active
   • Remove redirectUrl (no longer needed)
3. Confirm each update with the user before applying

Note: --update implies --fix behaviour (frontmatter is updated regardless).

Output Format

# External Link Check Report

**Date:** YYYY-MM-DD | **Scope:** <scope> | **URLs Checked:** X

## Summary

| Status       | Count | Percentage |
|--------------|-------|------------|
| Active       | X     | X%         |
| Redirected   | X     | X%         |
| Dead         | X     | X%         |
| Error        | X     | X%         |
| **Total**    | **X** | **100%**   |

## Dead Links (X found)

| File | URL | Status | Referenced By | Recommendation |
|------|-----|--------|---------------|----------------|
| `Reference - Old API Guide.md` | `https://example.com/old-page` | 404 | None | Archive candidate |
| `Reference - Deprecated Tool.md` | `https://dead-site.com/docs` | 410 | `Concept - Patterns.md`, `ADR - Tool Selection.md` | Review referencing notes |

## Error Links (X found)

| File | URL | Status | Referenced By |
|------|-----|--------|---------------|
| `Reference - Slow API.md` | `https://slow-site.com/api` | Timeout | `System - Gateway.md` |

## Redirected Links (X found)

| File | Original URL | Redirects To | Referenced By |
|------|--------------|--------------|---------------|
| `Reference - Cloud Guide.md` | `https://old.example.com/docs` | `https://new.example.com/docs` | `Concept - Cloud Strategy.md` |

## Recommendations

1. **Archive:** Reference - Old API Guide.md (dead, unreferenced)
2. **Update URL:** Reference - Cloud Guide.md (redirected)
3. **Review:** Reference - Deprecated Tool.md (dead but referenced by 2 notes)
4. **Recheck:** Reference - Slow API.md (timeout, may be temporary)

Frontmatter Update Summary (when --fix is used)

Append to the report:

## Frontmatter Updates Applied

| File | linkStatus | lastChecked | redirectUrl |
|------|------------|-------------|-------------|
| `Reference - Old API Guide.md` | dead | 2026-01-10 | -- |
| `Reference - Cloud Guide.md` | redirected | 2026-01-10 | `https://new.example.com/docs` |
| `Reference - Active Page.md` | active | 2026-01-10 | -- |

Examples

Example 1: Full Vault Check

/link-checker

Example 2: Reference Notes Only

/link-checker --scope Reference*

Example 3: Check and Update Frontmatter

/link-checker --fix

Example 4: Check, Fix, and Update Redirects

/link-checker --fix --update

Example 5: Custom Timeout with Redirect Reporting

/link-checker --include-redirects --timeout 15

Notes

• Uses curl for URL validation (more reliable than HTTP client libraries for bulk checking)
• Uses parallel Haiku agents for batch processing (faster for large numbers of links)
• Respects rate limits -- does not hammer servers
• Some sites block curl HEAD requests -- the agent should retry with GET if HEAD returns 403/405
• Corporate firewalls or VPNs may affect results (run from an appropriate network)
• Cross-reference checking identifies downstream impact of dead links
• Run quarterly as part of vault maintenance, or before major vault reviews

Invoke with: /link-checker to validate all external URLs in your vault