link-validation

name	link-validation
description	Validate markdown links and cross-references to ensure documentation integrity. Detects broken links, missing anchors, and invalid cross-reference paths in markdown files. Use proactively when auditing documentation, reviewing PRs that touch markdown files, or checking knowledge-copilot for broken links.
version	1.0.0
allowed-tools	["Read","Bash","Glob","Grep"]
tags	["links","documentation","validation","knowledge-copilot","cross-references"]

Link Validation

Validate markdown links and cross-references to ensure documentation integrity.

Purpose

Broken links in knowledge-copilot waste Claude's time and tokens. This skill finds and fixes broken internal links, missing anchors, and incorrect cross-references.

Link Types to Validate

Type	Pattern	Example
Relative file	[text](./path.md)	[Overview](./00-overview.md)
Anchor	[text](#heading)	[Setup](#installation)
File + anchor	[text](./file.md#section)	[Auth](./60-security.md#auth)
Parent path	[text](../other/file.md)	[Index](../00-INDEX.md)
Absolute (external)	https://...	Skip or warn

Procedure

1. Find All Markdown Files

find . -name "*.md" -type f -not -path "./_archive/*"

2. Extract Links from Each File

Use grep to find markdown links:

grep -oE '\[([^\]]+)\]\(([^\)]+)\)' file.md

3. Categorize Links

For each link:

• External (starts with http): Skip or optionally validate
• Anchor only (#heading): Validate heading exists in same file
• Relative file: Resolve path and check file exists
• File + anchor: Check both file and heading exist

4. Validate Internal Links

For relative paths:

# From the file's directory, check if target exists
target_file="resolved/path/to/target.md"
if [ -f "$target_file" ]; then
  echo "OK: $target_file"
else
  echo "BROKEN: $target_file"
fi

5. Validate Anchors

Anchors should match headings (lowercase, hyphens for spaces):

# Extract headings from target file
grep -E '^#{1,6} ' target.md | sed 's/^#* //' | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g'

6. Attempt Auto-Fix

For broken links, search for likely correct targets:

Broken Link	Search Strategy
./old-name.md	Find files with similar names
#old-heading	Find similar headings in file
../wrong/path.md	Search for filename in other directories

Output Format

## Link Validation Report

### Summary
- Files scanned: N
- Total links: N
- Valid: N
- Broken: N
- Warnings: N

### Broken Links

| File | Line | Link | Issue | Suggested Fix |
|------|------|------|-------|---------------|
| docs/setup.md | 45 | `./old-guide.md` | File not found | `./10-guide.md` |
| docs/api.md | 23 | `#authenication` | Anchor not found | `#authentication` |

### Warnings

| File | Link | Warning |
|------|------|---------|
| docs/intro.md | `https://old.example.com` | External link (not validated) |

### Fixes Applied
- docs/setup.md:45 - Changed `./old-guide.md` to `./10-guide.md`

Cross-Reference Patterns

Link Registry Pattern

If 00-links.md exists in a directory, validate all links defined there:

## Internal Links
- ecosystem: ../00-ecosystem-overview.md
- glossary: ../../03-ai-enabling/03-operations/12-shared-glossary.md

Source of Truth Pattern

Frontmatter may reference external docs:

source_of_truth: ../../insights-copilot/docs/04-architecture/system-design.md

Validate these paths exist (may be outside current repo).

Common Issues

Issue	Cause	Fix
File moved	Renamed with number prefix	Update link with new prefix
Heading changed	Wording updated	Update anchor text
Case mismatch	GitHub case-sensitive	Match exact case
Missing extension	.md omitted	Add .md extension