Link Validation Skill
Validates markdown links in your workspace using lychee.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
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 |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
