SKILL.md
Link Validator
Validates markdown links in Claude Code skills for portability across installation locations.
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.
The Problem
Skills with absolute repo paths break when installed elsewhere:
| Path Type | Example | Works When Installed? |
|---|---|---|
| Absolute repo | /skills/foo/SKILL.md |
No - path doesn't exist |
| Relative | ./references/guide.md |
Yes - always resolves |
| Relative parent | ../sibling/SKILL.md |
Yes - always resolves |
When to Use This Skill
- Before distributing a skill/plugin
- After creating new markdown links in skills
- When CI reports link validation failures
- To audit existing skills for portability issues
TodoWrite Task Templates
Template A: Validate Single Skill
1. Identify skill path to validate
2. Run: uv run scripts/validate_links.py <skill-path>
3. Review violation report (if any)
4. For each violation, apply suggested fix
5. Re-run validator to confirm all fixedTemplate B: Validate Plugin (Multiple Skills)
1. Identify plugin root directory
2. Run: uv run scripts/validate_links.py <plugin-path>
3. Review grouped violations by skill
4. Fix violations skill-by-skill
5. Re-validate entire pluginTemplate C: Fix Violations
1. Read violation report output
2. Locate file and line number
3. Review suggested relative path
4. Apply fix using Edit tool
5. Re-run validator on filePost-Change Checklist
After modifying this skill:
- [ ] Script remains in sync with latest patterns
- [ ] References updated if new patterns added
- [ ] Tested on real skill with violations
Quick Start
# Validate a single skill
uv run scripts/validate_links.py ~/.claude/skills/my-skill/
# Validate a plugin with multiple skills
uv run scripts/validate_links.py ~/.claude/plugins/my-plugin/
# Dry-run in current directory
uv run scripts/validate_links.py .Exit Codes
| Code | Meaning |
|---|---|
| 0 | All links valid (relative paths) |
| 1 | Violations found (absolute repo paths) |
| 2 | Error (invalid path, no markdown files) |
What Gets Checked
Flagged as Violations:
/skills/foo/SKILL.md- Absolute repo path/docs/guide.md- Absolute repo path
Allowed (Pass):
./references/guide.md- Relative same directory../sibling/SKILL.md- Relative parenthttps://example.com- External URL#section- Anchor link
Reference Documentation
- [Link Patterns Reference](./references/link-patterns.md) - Detailed pattern explanations and fix strategies
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Script not found | Path or plugin not installed | Verify plugin installed with claude plugin list |
| Exit code 2 | Invalid path or no .md files | Check target path exists and contains markdown |
| False positive on URL | Regex matched external link | URLs starting with http should be ignored |
| Anchor link flagged | Script treating # as path |
Anchor links (#section) are allowed by design |
| Relative path still fails | Wrong relative direction | Use ./ for same dir, ../ for parent |
| Validation passes locally | CI uses different working dir | Ensure CI runs from correct repo root |
| Too many violations | Legacy codebase | Fix incrementally, prioritize high-impact files |
| Can't determine fix | Complex path structure | Read link-patterns.md for detailed fix strategies |
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.