ncklrs/skills/link-checker

Link Checker Skill

Find and validate links on web pages. Reports broken links, redirects, and other issues.

When to Use

• Before releases to catch broken links
• After content updates
• During user testing (with --check-links flag)
• Regular site maintenance

Link Extraction

Using Browser Snapshot

Use browser_snapshot to get page accessibility tree, then extract links:

// Links to extract
const linkSelectors = [
  'a[href]',           // Standard links
  'area[href]',        // Image map links
  'link[href]',        // Stylesheet/resource links (optional)
];

Link Types to Identify

| Type | Pattern | Action | |------|---------|--------| | Internal | Same domain | Check via HEAD | | External | Different domain | Check via HEAD (unless excluded) | | Anchor | #section | Verify element exists | | mailto: | mailto:* | Validate format | | tel: | tel:* | Validate format | | javascript: | javascript:* | Flag as warning | | data: | data:* | Skip |

Extracting via browser_evaluate

async (page) => {
  const links = await page.evaluate(() => {
    const anchors = document.querySelectorAll('a[href]');
    return Array.from(anchors).map(a => ({
      href: a.href,
      text: a.textContent.trim().slice(0, 50),
      location: a.closest('[id]')?.id || 'page'
    }));
  });
  return links;
}

Link Validation

HEAD Request Method

For each link, make a HEAD request to check status:

async (page) => {
  const response = await page.request.head(url, {
    timeout: 10000,
    ignoreHTTPSErrors: false
  });
  return {
    status: response.status(),
    headers: response.headers()
  };
}

Status Interpretation

| Status Code | Category | Action | |-------------|----------|--------| | 200 | Success | Mark as working | | 201-299 | Success | Mark as working | | 301 | Permanent Redirect | Warn - update link | | 302 | Temporary Redirect | Note redirect | | 303, 307, 308 | Redirects | Note redirect | | 400 | Bad Request | Error | | 401, 403 | Auth Required | Warning | | 404 | Not Found | Error - broken link | | 405 | Method Not Allowed | Retry with GET | | 429 | Rate Limited | Wait and retry | | 500-599 | Server Error | Error | | Timeout | No Response | Error |

Handling Redirects

Track redirect chains:

const checkLink = async (url) => {
  const redirects = [];
  let currentUrl = url;
  let maxRedirects = 5;

  while (maxRedirects > 0) {
    const response = await fetch(currentUrl, {
      method: 'HEAD',
      redirect: 'manual'
    });

    if (response.status >= 300 && response.status < 400) {
      const location = response.headers.get('location');
      redirects.push({ from: currentUrl, to: location, status: response.status });
      currentUrl = new URL(location, currentUrl).href;
      maxRedirects--;
    } else {
      return { finalStatus: response.status, redirects };
    }
  }

  return { error: 'Too many redirects', redirects };
};

Depth Crawling

Algorithm

function crawl(startUrl, maxDepth):
  visited = Set()
  toVisit = [(startUrl, 0)]  // (url, depth)
  results = []

  while toVisit not empty:
    (url, depth) = toVisit.pop()

    if url in visited or depth > maxDepth:
      continue

    visited.add(url)
    pageLinks = extractLinks(url)
    results.extend(validateLinks(pageLinks))

    if depth < maxDepth:
      for link in pageLinks:
        if isInternal(link) and link not in visited:
          toVisit.append((link, depth + 1))

  return results

Performance Considerations

| Depth | Typical Links | Time | |-------|---------------|------| | 1 | 20-100 | 10-30s | | 2 | 100-500 | 1-5 min | | 3 | 500-2000+ | 5-20 min |

Tips:

• Default to depth 1
• Use --internal-only to reduce scope
• Parallelize requests where possible

Report Generation

Data Structure

const linkReport = {
  url: 'https://example.com',
  checkedAt: '2025-01-06T14:30:00Z',
  summary: {
    total: 47,
    working: 44,
    broken: 2,
    redirects: 3,
    skipped: 1
  },
  broken: [
    { url: '/old-page', foundOn: '/', status: 404 },
  ],
  redirects: [
    { url: '/blog', redirectsTo: '/news', status: 301 },
  ],
  warnings: [
    { type: 'javascript-link', url: 'javascript:void(0)', foundOn: '/nav' },
  ],
  byPage: {
    '/': { checked: 15, broken: 1 },
    '/about': { checked: 8, broken: 1 },
  }
};

Report Sections

1. Summary: Quick overview of link health
2. Broken Links: 404s and errors (highest priority)
3. Redirects: Links that should be updated
4. Warnings: javascript: links, slow responses, etc.
5. By Page: Where issues were found

Integration with User Testing

When --check-links is added to /user-test:

During Test

1. As persona navigates, collect all unique links seen
2. Don't interrupt persona flow for link checking
3. Store links for post-test validation

After Test

1. Validate all collected links
2. Add "Link Health" section to report
3. Note any broken links encountered during tasks

Report Section

## Link Health

### Summary
- **Links Encountered**: 32
- **Working**: 30 (94%)
- **Broken**: 2 (6%)

### Broken Links Found During Testing

| Link | Encountered During | Status |
|------|-------------------|--------|
| /products/sale | Browsing products | 404 |
| /help/faq | Looking for help | 404 |

### Impact on User Experience
The persona encountered 2 broken links during their journey,
which could cause confusion and frustration.

Best Practices

1. Check internal links first: External sites may block or rate limit
2. Respect robots.txt: For external sites
3. Handle timeouts gracefully: Some servers are slow
4. Track over time: Links break gradually
5. Fix redirects: Replace with final destination
6. Don't hammer servers: Add delays between requests