Agent-Skills.md

Agent Skills: Link Validator

Validate markdown link portability in skills. TRIGGERS - check links, validate portability, fix broken links, relative paths.

UncategorizedID: terrylica/cc-skills/link-validator

Repository

terrylica/cc-skills
terrylicaLicense: MIT
264

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terrylica/cc-skills/tree/HEAD/plugins/link-tools/skills/link-validator

Skill Files

Browse the full folder contents for link-validator.

Download Skill

Loading file tree…

plugins/link-tools/skills/link-validator/SKILL.md

Skill Metadata

Name
link-validator
Description
Validate markdown link portability in skills. TRIGGERS - check links, validate portability, fix broken links, relative paths.

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

# 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

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.