link-validation — Claude Code skill: offline markdown link check
link-validation runs an offline lychee pass over a project's markdown and reports broken relative links, root-relative paths and anchors. Handy right before you commit docs.
MIT 135 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill link-validation -a claude-codeWhat link-validation does
The skill is a wrapper around tasks/link-check.sh. That script jumps to the work-tree root with git rev-parse --show-toplevel, then calls bunx lychee over './**/*.md' with --offline --no-progress --root-dir, prints lychee's summary plus a pass or fail line, and hands back lychee's exit code so CI can read it. Inside cc-skills the same run is moon run repo:link-check; moon run repo:check folds it into the wider gate.
Relative targets, root-relative ones such as /docs/adr/x.md resolved against --root-dir, and #anchor fragments all get checked. External URLs stay out of scope: their liveness depends on the network and on other sites staying up. Only lychee's .lycheecache touches the disk.
You need lychee. The script pulls it through bunx, so Bun alone covers that path; otherwise brew install lychee. A repo-root lychee.toml carries the exclusions and include_fragments = "anchor-only", since lychee 0.24 refuses the old boolean true. Drop --root-dir and every /docs/... link fails, so keep it pointing at the absolute repo root. A path that exists on one machine (~/...) will never resolve — write it as inline code instead of a link.
What it helps with
- catch broken relative links before a docs commit
- confirm a README edit left no dangling anchors
- run the check in CI and read lychee's exit code
- trace root-relative
/docs/...links that fail without--root-dir - keep deliberately broken test fixtures out of the run
Example prompts for the agent
- Run link-validation over the markdown and list the broken internal links.
- Check the docs for dangling anchors before I commit.
- Run
moon run repo:link-checkand tell me what failed.
How to install link-validation
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a claude-code2Manually: put the files in place
~/.claude/skills/link-validation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/link-validation/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a codex2Manually: put the files in place
.agents/skills/link-validation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a cursor2Manually: put the files in place
.cursor/skills/link-validation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/link-tools/skills/link-validation2Manually: put the files in place
.github/skills/link-validation/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/link-tools/skills/link-validationManually: put the files in place
.devin/skills/link-validation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about link-validation
How do I install link-validation in Claude Code?
Run npx skills add terrylica/cc-skills --skill link-validation -a claude-code; the skill file then sits at ~/.claude/skills/link-validation/SKILL.md.
What does link-validation do?
It drives lychee offline across your markdown and reports broken relative links, root-relative paths and anchors, exiting with lychee's own status code.
Why are external links skipped?
The check is offline by design. Whether another site answers depends on the network and on that site's uptime, which makes the result unreliable.
Source text
SKILL.md · MIT
--- name: link-validation description: Offline markdown link validation with lychee (tasks/link-check.sh, moon run repo:link-check). Detect broken internal links and anchors on demand. allowed-tools: Bash, Read, Glob triggers: - link validation - broken links - lychee - check links - markdown links --- # Link Validation Skill Validates markdown links in your workspace using [lychee](https://github.com/lycheeverse/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 - Proving a doc change left no dangling internal link ## How to Run It The working path is the offline lychee check in `tasks/link-check.sh`. Inside the cc-skills repository it is part of the quality gate: ```bash moon run repo:link-check # this check alone moon run repo:check # the whole gate, link-check included bash tasks/link-check.sh # the same script without moon ``` In any other workspace, run the same lychee command from the repository root: ```bash lychee --offline --no-progress --root-dir "$(git rev-parse --show-toplevel)" './**/*.md' ``` Add `--config lychee.toml` when the repository has one; lychee also loads `./lychee.toml` by itself. ## What the Check Does `tasks/link-check.sh`: 1. `cd`s to the working-tree root (`git rev-parse --show-toplevel`, so it is correct inside a worktree too) 2. Runs `bunx lychee --config lychee.toml --offline --no-progress --root-dir <repo root> './**/*.md'` 3. Excludes `plugins/statusline-tools/tests/fixtures`, whose links are broken on purpose 4. Prints lychee's summary line, then `✓ every internal link resolves` or `✗ broken internal links found (lychee exit N)`, and exits with lychee's exit code It checks relative links, root-relative links (`/docs/adr/x.md`, resolved through `--root-dir`) and `#anchor` fragments. It is offline by design: external URL liveness depends on the network and on other sites' uptime, so it is not checked. Nothing is written to disk except lychee's own `.lycheecache`; the result is the terminal output and the exit code. A path that exists on one machine only (`~/...`, another repository) cannot pass. Write it as inline code instead of a link. ## Requirements - [lychee](https://github.com/lycheeverse/lychee): `tasks/link-check.sh` runs it through `bunx`, so Bun is enough there; elsewhere install it (`brew install lychee`) ## Configuration cc-skills keeps one lychee config, `lychee.toml` at the repository root. It holds the path and URL exclusions and `include_fragments = "anchor-only"` (lychee 0.24 rejects the old boolean `true`). The statusline-tools Stop hook reads the same file when it exists. ## Related Checks - Link portability in skills (absolute repo paths that break once installed): the [link-validator](../link-validator/SKILL.md) skill - Path policy at session end: the statusline-tools Stop hook runs `lint-relative-paths` and lychee, and writes `.lychee-results.json` for the status line ## History This skill used to describe a Stop hook, `hooks/stop-link-check.py`, that wrote `.link-check-results.md`. link-tools never had a `hooks.json`, so the hook never ran; it was deleted in issue #33. ## References - [ADR: Link Checker Plugin Extraction](../../../../docs/adr/2025-12-11-link-checker-plugin-extraction.md) - [lychee Documentation](https://github.com/lycheeverse/lychee) --- ## Troubleshooting | Issue | Cause | Solution | | ----------------------------- | ------------------------------- | --------------------------------------------------------------- | | lychee not found | Not installed | `brew install lychee`, or run through `bunx lychee` | | Config fails to load | `include_fragments = true` | Use `include_fragments = "anchor-only"` (lychee 0.24 and later) | | Every `/docs/...` link fails | No `--root-dir` | Pass `--root-dir` with the absolute repository root | | A link to `~/...` fails | Path exists on one machine only | Write it as inline code, not a link | | A fixture's broken link fails | Fixture not excluded | Add it to `--exclude-path` or the config's `exclude_path` | ## Post-Execution Reflection After this skill completes, check before closing: 1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure. 2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. **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.
© terrylica · MIT · terrylica/cc-skills