link-validation_skill

Overview

This skill validates markdown links across a workspace using lychee at the end of a Claude Code session. It detects broken links and flags path policy violations like absolute paths or excessive parent traversal. Results are written as a machine-friendly report in the repository root for easy consumption by workflows or developers.

How this skill works

On session Stop, the skill scans the workspace for markdown files, then runs lychee to check each link target. It additionally enforces path policies (no absolute filesystem paths, limited ../ traversal, and marketplace-relative rules). The skill aggregates lychee output and path-violation findings into a single markdown/JSON-style results file for downstream automation.

When to use it

• Run automatically at the end of a coding or documentation session to catch regressions.
• Validate links before committing documentation or publishing a package.
• Enforce repository path policies during CI or local pre-commit checks.
• Audit a repository after large refactors that move files and update links.

Best practices

• Install lychee and ensure it is on PATH (brew install lychee or equivalent).
• Place a .lycheerc.toml in the workspace root to customize link checks and timeouts.
• Run from the repository root to avoid relative-path false positives.
• Treat path policy warnings as review items and errors as blocking issues in CI.
• Use the generated results file for programmatic gating or to attach to pull request summaries.

Example use cases

• CI pipeline step that fails builds on broken links or policy errors.
• End-of-session hygiene in Claude Code to produce a link-check report for reviewers.
• Pre-publish documentation validation to prevent broken external references.
• Repository health dashboard that consumes the JSON results file to show link status over time.