Link Validation Skill

Validates markdown links in your workspace using lychee.

When to Use This Skill

Use this skill when:

• Checking for broken links in markdown files

• Validating link paths before committing documentation

• Detecting path policy violations (absolute paths, excessive traversal)

What It Does

When invoked, this skill:

• Discovers all markdown files in your workspace

• Runs lychee to check for broken links

• Lints paths for policy violations (absolute paths, excessive traversal)

• Outputs JSON results for programmatic consumption

Requirements

• lychee installed (brew install lychee )

• Python 3.11+ and uv

Output

Results are written to .link-check-results.md in your workspace:

Link Check Results

Correlation ID: 01JEGQXV8KHTNF3YD8G7ZC9XYK

Lychee Link Validation

No broken links found.

Path Policy Violations

No path violations found.

Path Policy Rules

Rule Severity Description

NO_ABSOLUTE_PATHS Error Filesystem absolute paths not allowed

NO_PARENT_ESCAPES Warning Excessive ../ may escape repository

MARKETPLACE_RELATIVE Warning Plugins should use ./ relative paths

Configuration

Override the default lychee config by placing .lycheerc.toml in your workspace root.

See config/lychee.toml for the default configuration.

References

• ADR: Link Checker Plugin Extraction

• Design Spec

• lychee Documentation

Troubleshooting

Issue Cause Solution

lychee not found Not installed Run mise install lychee

Too many 403 errors Rate limiting Add rate limit to .lycheerc.toml

Relative path errors Wrong base directory Run from repository root

False positives Dynamic content Add URL pattern to exclude list

Timeout on links Slow external sites Increase timeout in config

Cache issues Stale cached results Clear cache with --no-cache flag