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
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 |