home / skills / terrylica / cc-skills / link-validation

link-validation skill

safe

/plugins/link-tools/skills/link-validation

This skill validates markdown links in your workspace using lychee, detecting broken links and path policy violations at session end.

npx playbooks add skill terrylica/cc-skills --skill link-validation

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: link-validation
description: Universal link validation using lychee for Claude Code sessions. Runs at session end to detect broken links and path policy violations.
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).

## When to Use This Skill

Use this skill when:

- Checking for broken links in markdown files
- Validating link paths before committing documentation
- Running automated link checks at session end
- Detecting path policy violations (absolute paths, excessive traversal)

## What It Does

At session end (Stop hook), this skill:

1. **Discovers** all markdown files in your workspace
2. **Runs lychee** to check for broken links
3. **Lints paths** for policy violations (absolute paths, excessive traversal)
4. **Outputs JSON** results for programmatic consumption

## Requirements

- [lychee](https://github.com/lycheeverse/lychee) installed (`brew install lychee`)
- Python 3.11+ and uv

## Output

Results are written to `.link-check-results.md` in your workspace:

```markdown
# Link Check Results

**Correlation ID**: `01JEGQXV8KHTNF3YD8G7ZC9XYK`

## Lychee Link Validation

No broken links found.

## Path Policy Violations

No path violations found.
```

## Path Policy Rules

| Rule                 | Severity | Description                            |
| -------------------- | -------- | -------------------------------------- |
| NO_ABSOLUTE_PATHS    | Error    | Filesystem absolute paths not allowed  |
| NO_PARENT_ESCAPES    | Warning  | Excessive `../` may escape repository  |
| MARKETPLACE_RELATIVE | Warning  | Plugins should use `./` relative paths |

## Configuration

Override the default lychee config by placing `.lycheerc.toml` in your workspace root.

See [config/lychee.toml](../../config/lychee.toml) for the default configuration.

## References

- [ADR: Link Checker Plugin Extraction](../../../../docs/adr/2025-12-11-link-checker-plugin-extraction.md)
- [Design Spec](../../../../docs/design/2025-12-11-link-checker-plugin-extraction/spec.md)
- [lychee Documentation](https://github.com/lycheeverse/lychee)

---

## Troubleshooting

| Issue                | Cause                | Solution                           |
| -------------------- | -------------------- | ---------------------------------- |
| lychee not found     | Not installed        | Run `mise install lychee`          |
| Too many 403 errors  | Rate limiting        | Add rate limit to .lycheerc.toml   |
| Relative path errors | Wrong base directory | Run from repository root           |
| False positives      | Dynamic content      | Add URL pattern to exclude list    |
| Timeout on links     | Slow external sites  | Increase timeout in config         |
| Cache issues         | Stale cached results | Clear cache with `--no-cache` flag |

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.

FAQ

What does the skill require to run?

It requires lychee installed and accessible, plus Python 3.11+ if running any included helpers; lychee is the primary link-check engine.

Where are results stored and how can I consume them?

Results are written to a .link-check-results.md in the workspace root and include structured sections suitable for programmatic parsing or display in PR checks.