Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill link-validation -a claude-code
Open on GitHub

What 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-check and tell me what failed.

How to install link-validation

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill link-validation -a claude-code

2Manually: put the files in place

~/.claude/skills/link-validation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/link-validation/

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

Similar skills

All skills for Writing and docs →

From the same set79

The whole set →
skill-architecture skill-architecture guides skill creation and updates, YAML structure checks, and common troubleshooting. Task templates help you choose a workflow before editing files. CX Codex +1 137installs slash-command-factory slash-command-factory generates Claude Code slash command Markdown files with YAML frontmatter through a question workflow or ten presets. CX Codex +1 136installs backtesting-py-oracle backtesting-py-oracle configures backtesting.py to match ClickHouse SQL sweep results on range bars. Fixes trade count mismatches and timing discrepancies in multi-position testing. CX Codex +1 135installs doppler-secret-validation The doppler-secret-validation skill helps store secrets in Doppler, verify retrieval, and test API authentication. Use it to check a token before relying on it in a project. CX Codex +1 135installs session-recovery session-recovery troubleshoots missing Claude Code sessions when claude -r reports no conversations found or files save to incorrect paths. CX Codex +1 135installs session-chronicle session-chronicle connects findings, decisions, and code changes to session UUIDs. Use it when you need to trace where work came from or record session provenance. CX Codex +1 135installs notion-sdk notion-sdk — a skill for managing Notion via the official Python SDK. Creates pages and databases, queries information, adds content blocks — all programmatically. CX Codex +1 133installs hooks-development The hooks-development skill guides you through building and debugging Claude Code hooks, with a focus on output visibility. Use it when a hook runs but its message never reaches the agent. CX Codex +1 133installs

Project sponsors

Companies that keep this analytics open