link-validation — скилл для Claude Code: проверка ссылок в markdown
Скилл link-validation проверяет ссылки в markdown-файлах проекта офлайн через lychee: относительные пути, корневые пути и якоря. Пригодится перед коммитом документации.
MIT 135 установок ★ 3 обновлён 2026-10-25
npx skills add terrylica/cc-skills --skill link-validation -a claude-codeЧто делает link-validation
Скилл запускает tasks/link-check.sh. Скрипт переходит в корень рабочего дерева через git rev-parse --show-toplevel, вызывает bunx lychee с --offline --no-progress --root-dir по маске './**/*.md', печатает сводку lychee и вердикт — всё сошлось или нашлись битые внутренние ссылки. Код возврата берётся у lychee, поэтому проверку легко вставить в CI или в pre-commit. В репозитории cc-skills тот же прогон доступен как moon run repo:link-check, а moon run repo:check гоняет его вместе с остальными проверками.
Ловит относительные ссылки, корневые вроде /docs/adr/x.md и фрагменты #anchor. Внешние URL не проверяются: их доступность зависит от сети и чужих сайтов. На диск ничего не пишется, кроме кеша .lycheecache.
Нужен lychee. В скрипте он вызывается через bunx, так что достаточно Bun; в остальных случаях brew install lychee. Конфиг lychee.toml в корне репозитория задаёт исключения и include_fragments = "anchor-only" — lychee 0.24 отвергает старый булев true. Ссылка на путь, который есть только на вашей машине (~/...), не пройдёт никогда: такой путь пишите инлайн-кодом, а не ссылкой.
Какие задачи решает
- поймать битые относительные ссылки до коммита документации
- проверить, что после правки README не осталось висячих якорей
- прогнать проверку ссылок в CI и получить код возврата lychee
- найти корневые ссылки
/docs/..., которые ломаются без--root-dir - убрать из проверки фикстуры с намеренно битыми ссылками
Примеры запросов агенту
- Прогони link-validation по markdown-файлам и покажи, какие внутренние ссылки сломаны.
- Перед коммитом проверь документацию на висячие якоря.
- Запусти
moon run repo:link-checkи скажи, что именно упало.
Как установить link-validation
1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a claude-code2Вручную: положить файлы
~/.claude/skills/link-validation/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/link-validation/
1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a codex2Вручную: положить файлы
.agents/skills/link-validation/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a cursor2Вручную: положить файлы
.cursor/skills/link-validation/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/link-tools/skills/link-validation2Вручную: положить файлы
.github/skills/link-validation/SKILL.md1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a gemini-cli2Командой платформы
gemini skills install https://github.com/terrylica/cc-skills --path plugins/link-tools/skills/link-validationВручную: положить файлы
.devin/skills/link-validation/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill link-validation -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о link-validation
Как установить link-validation в Claude Code?
Выполните npx skills add terrylica/cc-skills --skill link-validation -a claude-code, после чего файл скилла окажется по пути ~/.claude/skills/link-validation/SKILL.md.
Что делает link-validation?
Гоняет lychee в офлайн-режиме по markdown-файлам и сообщает о битых относительных ссылках, корневых путях и якорях. Возвращает код выхода lychee, так что подходит для автоматической проверки.
Почему внешние ссылки не проверяются?
Проверка офлайн по замыслу: доступность чужих сайтов зависит от сети и их аптайма, на результат такого прогона нельзя опереться.
Исходный текст
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