Skip to main content
skill CX Codex

link-validator — Claude Code skill: markdown link portability check

The link-validator skill detects absolute paths in markdown links that break when a skill is installed elsewhere. Run it before sharing a skill or after adding new links.

MIT 127 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-validator -a claude-code
Open on GitHub

What link-validator does

link-validator scans markdown files for absolute paths like /skills/foo/SKILL.md and suggests relative alternatives (./references/guide.md, ../sibling/SKILL.md). External URLs and anchor links are ignored.

The skill runs via uv run scripts/validate_links.py with a path to your skill or plugin. It returns a report with line numbers and fix suggestions. Exit code 0 means all links are portable, 1 indicates violations, 2 signals an error (invalid path or no markdown files).

The skill itself should be updated immediately if the underlying tool's interface changes or a workaround proves necessary — delays only cause the same friction later.

What it helps with

  • find absolute paths in skill markdown links
  • check if links will break after installation in a different directory
  • get a violation report with line numbers and ready-to-apply fixes
  • validate a multi-skill plugin in one run

Example prompts for the agent

  • Check link portability in the skill at ~/.claude/skills/my-skill/
  • Validate an entire plugin at ~/.claude/plugins/my-plugin/ and list broken links
  • Run a dry-run validation on the current working directory

How to install link-validator

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about link-validator

How do I install link-validator in Claude Code?

Run npx skills add terrylica/cc-skills --skill link-validator -a claude-code, then open ~/.claude/skills/link-validator/SKILL.md.

What does link-validator check?

It finds absolute paths in markdown links (like /skills/foo/SKILL.md) that won't work when a skill moves to another location. External URLs and anchors are skipped.

What exit codes does the skill return?

Exit 0 when all links are portable, exit 1 if violations are found (absolute paths), exit 2 on error (invalid path or no markdown files in the target).

Source text

SKILL.md · MIT
---
name: link-validator
description: Validate markdown link portability in skills. TRIGGERS - check links, validate portability, fix broken links, relative paths.
allowed-tools: Bash, Read, Edit, Glob
---

# Link Validator

Validates markdown links in Claude Code skills for portability across installation locations.

> **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.

## The Problem

Skills with absolute repo paths break when installed elsewhere:

| Path Type       | Example                 | Works When Installed?   |
| --------------- | ----------------------- | ----------------------- |
| Absolute repo   | `/skills/foo/SKILL.md`  | No - path doesn't exist |
| Relative        | `./references/guide.md` | Yes - always resolves   |
| Relative parent | `../sibling/SKILL.md`   | Yes - always resolves   |

## When to Use This Skill

- Before distributing a skill/plugin
- After creating new markdown links in skills
- When CI reports link validation failures
- To audit existing skills for portability issues

---

## TodoWrite Task Templates

### Template A: Validate Single Skill

```
1. Identify skill path to validate
2. Run: uv run scripts/validate_links.py <skill-path>
3. Review violation report (if any)
4. For each violation, apply suggested fix
5. Re-run validator to confirm all fixed
```

### Template B: Validate Plugin (Multiple Skills)

```
1. Identify plugin root directory
2. Run: uv run scripts/validate_links.py <plugin-path>
3. Review grouped violations by skill
4. Fix violations skill-by-skill
5. Re-validate entire plugin
```

### Template C: Fix Violations

```
1. Read violation report output
2. Locate file and line number
3. Review suggested relative path
4. Apply fix using Edit tool
5. Re-run validator on file
```

---

## Post-Change Checklist

After modifying this skill:

1. [ ] Script remains in sync with latest patterns
2. [ ] References updated if new patterns added
3. [ ] Tested on real skill with violations

---

## Quick Start

```bash
# Validate a single skill
uv run scripts/validate_links.py ~/.claude/skills/my-skill/

# Validate a plugin with multiple skills
uv run scripts/validate_links.py ~/.claude/plugins/my-plugin/

# Dry-run in current directory
uv run scripts/validate_links.py .
```

## Exit Codes

| Code | Meaning                                 |
| ---- | --------------------------------------- |
| 0    | All links valid (relative paths)        |
| 1    | Violations found (absolute repo paths)  |
| 2    | Error (invalid path, no markdown files) |

## What Gets Checked

**Flagged as Violations:**

- `/skills/foo/SKILL.md` - Absolute repo path
- `/docs/guide.md` - Absolute repo path

**Allowed (Pass):**

- `./references/guide.md` - Relative same directory
- `../sibling/SKILL.md` - Relative parent
- `https://example.com` - External URL
- `#section` - Anchor link

## Reference Documentation

- [Link Patterns Reference](./references/link-patterns.md) - Detailed pattern explanations and fix strategies

---

## Troubleshooting

| Issue                     | Cause                         | Solution                                          |
| ------------------------- | ----------------------------- | ------------------------------------------------- |
| Script not found          | Path or plugin not installed  | Verify plugin installed with `claude plugin list` |
| Exit code 2               | Invalid path or no .md files  | Check target path exists and contains markdown    |
| False positive on URL     | Regex matched external link   | URLs starting with `http` should be ignored       |
| Anchor link flagged       | Script treating `#` as path   | Anchor links (`#section`) are allowed by design   |
| Relative path still fails | Wrong relative direction      | Use `./` for same dir, `../` for parent           |
| Validation passes locally | CI uses different working dir | Ensure CI runs from correct repo root             |
| Too many violations       | Legacy codebase               | Fix incrementally, prioritize high-impact files   |
| Can't determine fix       | Complex path structure        | Read link-patterns.md for detailed fix strategies |


## 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 Code review and refactoring →

From the same set79

The whole set →
clickhouse-pydantic-config clickhouse-pydantic-config turns Pydantic v2 ClickHouse models and environment variables into a DBeaver connection file. Handy when one repo talks to both a local and a cloud database. CX Codex +1 130installs issue-create issue-create turns a rough description into a formatted GitHub issue: detects the type, picks labels that exist in the repo, and warns about duplicates before you post. CX Codex +1 129installs asciinema-streaming-backup asciinema-streaming-backup streams asciinema terminal recordings to an isolated GitHub orphan branch using zstd and brotli compression. CX Codex +1 128installs multi-agent-e2e-validation The multi-agent-e2e-validation skill for Claude Code and other AI editors spawns multiple validation agents in parallel to test database refactors comprehensively. CX Codex +1 128installs session-info session-info returns the active Claude Code session UUID and session chain cache details. Helpful for debugging and linking transcripts to sessions. CX Codex +1 127installs asciinema-analyzer The asciinema-analyzer skill searches asciinema text recordings for keywords, commands, errors, and patterns. Use it when reviewing terminal session history. CX Codex +1 127installs research-archival research-archival scrapes AI research conversations and web pages, saves them as markdown with YAML frontmatter, and opens cross-referenced GitHub issues once the writing account is confirmed. CX Codex +1 127installs iterm2-layout iterm2-layout configures iTerm2 workspace layouts, panes, and tabs using a TOML file. Helps an AI agent register project directories and auto-discover git worktrees. CX Codex +1 126installs

Project sponsors

Companies that keep this analytics open