Broken Link Auditor

Broken Link Auditor

Purpose

Broken or stale links make SharePoint sites feel unreliable, especially after migrations, re-orgs, and content cleanups. This skill audits link health across SharePoint pages, news posts, libraries, lists, or selected items and saves a self-contained HTML report that teams can act on. It is strictly read-only for content: it never edits pages, files, metadata, or links. The only thing it writes is the final HTML report file.

Trigger Phrases

Activate this skill when the user says any of the following (or close variations):

• "broken link audit" / "dead link audit"
• "find broken links" / "check broken links"
• "check dead links on this site"
• "audit links in this library"
• "scan pages for broken links"
• "which SharePoint links are broken"

Inputs & Scope

Determine the reporting scope from the user's request and the current context, in this order:

1. Selected items — if the user has pages, files, or folders selected or says "these/this", audit those items first.
2. Named library, list, or Site Pages — if the user names one, resolve it on the current site.
3. Current library or current Site Pages context — if the user is already in one, use it.
4. Whole current site — if no narrower scope is clear, scan accessible Site Pages plus hyperlink-bearing items in accessible user-created lists and libraries.
5. If no scope can be resolved, ask the user which library, page set, or site scope to audit. Do not guess.

Only inspect content the current user can already read. Never invent pages, items, targets, or HTTP outcomes.

What counts as a link

Audit the following when present:

• Links embedded in SharePoint page and news post content
• Hyperlink / URL columns on list items or library items
• Obvious SharePoint links stored in plain text fields when the user explicitly asks for a broader scan

Ignore the following unless the user explicitly asks:

• Mailto links
• Telephone links
• JavaScript pseudo-links
• Anchors that only jump within the same page and do not reference another resource

Steps

Step 1 — Resolve the scan targets

• Resolve the site, list/library, folder, page set, or selected items from the user's request and current SharePoint context.
• For whole-site audits, enumerate accessible user-created lists/libraries plus the Site Pages library.
• Record the resolved scope exactly as it exists. If resolution is partial, keep going with the resolvable part and note the limitation in the report.

Step 2 — Discover candidate fields and content

• For each list or library in scope, inspect the schema first and identify:
  • hyperlink / URL columns,
  • page or rich-text fields that can contain embedded links,
  • label fields to identify each item in the report.
• For Site Pages and news posts, include the page title, URL/path, last modified date, editor, and the rich page content fields needed to extract links.
• Exclude system-only columns from the report unless they are needed to identify the source item.

Step 3 — Read items and extract links

• Page through every item in scope. Do not stop at the first page.
• For each source item, extract links and retain:
  • source item title/name,
  • source item URL/path,
  • source type (page, news post, file, list item),
  • field or content region where the link was found,
  • the raw target URL.
• Normalize URLs before checking them:
  • trim whitespace,
  • decode obvious HTML-escaped forms,
  • resolve relative SharePoint URLs against the current site,
  • preserve the original value for reporting.
• Deduplicate exact duplicate checks so the same target is not revalidated unnecessarily, but still report every source occurrence.

Step 4 — Validate internal SharePoint links

For links that point to the current tenant or to relative SharePoint URLs:

• Try to resolve the target as a page, file, folder, list, or item using SharePoint discovery, path-based lookup, or item retrieval tools.
• Classify the result:
  • Valid — target exists and is reachable in the available data.
  • Broken — target is clearly missing, deleted, malformed, or resolves to a not-found outcome.
  • Inconclusive — target may exist but cannot be confirmed because of permission limits or unavailable tooling.
• Do not label a permission-denied target as broken. Mark it Inconclusive (permission-limited) instead.

Step 5 — Validate external links carefully

For links outside SharePoint:

• Use safe read-only URL checks where available, preferring a lightweight HEAD request and falling back to a minimal GET only when needed.
• Follow normal redirects up to a small limit and record the final outcome.
• Use a short timeout and never let one slow domain block the whole scan.
• Classify the result:
  • Valid — reachable 2xx response
  • Redirected — target resolves after redirect
  • Broken — 4xx/5xx, DNS failure, malformed URL, or unreachable after retry
  • Inconclusive — timeout, bot protection, authentication wall, or network restriction
• Treat transient failures carefully. Retry once before calling an external link broken.