link-validator_skill

Overview

This skill validates Markdown link portability inside Claude Code skills and plugins. It scans markdown files for non-portable link patterns (like absolute repo paths) and reports violations with suggested relative replacements. Use it to ensure skills remain installable and link-correct across different installation locations.

How this skill works

The validator parses Markdown files under a given directory and searches link targets against allowed patterns. It flags absolute repository paths (e.g., /skills/foo/SKILL.md or /docs/guide.md) as violations while allowing relative paths (./, ../), external URLs, and anchors. The tool returns a grouped report and exit codes indicating success, violations, or errors, and suggests relative path fixes for each violation.

When to use it

• Before publishing or distributing a skill or plugin to catch portability issues
• After adding or editing markdown links inside a skill
• As part of CI to prevent absolute repo paths from entering builds
• When auditing an older codebase for legacy absolute links
• During pull-request review to validate link changes

Best practices

• Prefer relative links (./ or ../) inside skills to guarantee portability
• Run the validator locally before opening PRs and include it in CI pipelines
• Fix violations incrementally, focusing first on high-traffic docs
• Use the suggested relative path from the report and re-run validator to confirm fixes
• Keep the validator patterns in sync with any new repository layout or link conventions

Example use cases

• Validate a single skill directory prior to release: uv run scripts/validate_links.py ~/.claude/skills/my-skill/
• Scan an entire plugin containing multiple skills and fix grouped violations
• Automate a CI job that fails if any absolute repo paths are committed
• Perform a repo audit to replace legacy absolute links with portable relative links
• Run a dry-run in the current directory to preview violations without changing files