Agent skill
link-validation
Validate markdown links and cross-references in documentation
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/link-validation
SKILL.md
Link Validation
Validate markdown links and cross-references to ensure documentation integrity.
Purpose
Broken links in shared-docs 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 |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?