Link Validator

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:

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

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 - Detailed pattern explanations and fix strategies

---

Troubleshooting

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.

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Link Patterns Reference

Comprehensive guide to markdown link patterns and portability validation for marketplace plugins.

Parent: Link Validator Skill

---

Link Convention Summary

Key Insight: ADRs and design specs are NOT bundled with installed plugins, so /docs/ paths serve as source repo references rather than functional links.

---

Violation Patterns

The validator detects paths that should use relative format but don't.

Examples of Violations

Allowed Repo-Root Paths

These / paths are valid because they reference repo-level documentation not bundled with skills:

---

Valid Patterns

Relative Same Directory (./)

[Reference Guide](./references/guide.md)
[Helper Script](./scripts/helper.py)

Use when: Linking to files within the same skill directory.

Relative Parent (../)

[Sibling Skill](../other-skill/SKILL.md)
[Plugin README](../../README.md)

Use when: Linking to sibling skills or parent directories.

Implicit Relative (No Prefix)

[Same Dir File](guide.md)

Use when: Linking to files in the exact same directory. Less explicit than ./.

External URLs

[GitHub](https://github.com/user/repo)
[Documentation](https://docs.example.com)

Always valid: External URLs are not subject to portability checks.

Anchor Links

[Section](#installation)
[Quick Start](#quick-start)

Always valid: In-page anchors work regardless of file location.

---

Common Scenarios

Scenario 1: SKILL.md to Own References

Location: skill-name/SKILL.md Target: skill-name/references/guide.md

# Correct

[Guide](./references/guide.md)

# Wrong

[Guide](/skills/skill-name/references/guide.md)

Scenario 2: References Back to SKILL.md

Location: skill-name/references/guide.md Target: skill-name/SKILL.md

# Correct

[Back to Skill](../SKILL.md)

# Wrong

[Back to Skill](/skills/skill-name/SKILL.md)

Scenario 3: Cross-Skill Reference

Location: skill-a/SKILL.md Target: skill-b/SKILL.md

# Correct

[Related Skill](../skill-b/SKILL.md)

# Wrong

[Related Skill](/skills/skill-b/SKILL.md)

Scenario 4: Deep Reference to Other Skill

Location: skill-a/references/deep/file.md Target: skill-b/SKILL.md

# Correct (3 levels up, then into skill-b)

[Other Skill](../../../skill-b/SKILL.md)

# Wrong

[Other Skill](/skills/skill-b/SKILL.md)

---

Fix Calculation Logic

The validator suggests fixes based on file depth:

Depth Calculation

skill-root/SKILL.md           → depth 0
skill-root/references/foo.md  → depth 1
skill-root/references/a/b.md  → depth 2

Fix Formula

Same skill, different directory:

../  × depth  +  target-path

Different skill:

../  × (depth + 1)  +  skill-name/target-path

---

Testing Fixes

Local Verification

1. Apply the suggested fix 2. Run validator again: uv run scripts/validate_links.py <skill-path> 3. Verify exit code 0

Installation Test

1. Copy skill to different location:

   cp -r ~/.claude/skills/my-skill /tmp/test-skill

2. Run validator on new location 3. Manually verify links resolve in new context

---

Edge Cases

Code Blocks (Skipped)

Links inside fenced code blocks are NOT validated:

    This [link](/absolute/path.md) is in a code block - ignored

(The above indented block shows a code fence that would be skipped)

Inline Code (Skipped)

Links in inline code are NOT validated:

Use the pattern `[text](/path)` for documentation - ignored

Empty Links (Allowed)

[Empty link]() # Passes - no path to validate

---

Integration Notes

With skill-architecture

The skill-architecture plugin references link-validator for:

• TodoWrite template step 9 (Create New Skill)
• Skill Quality Checklist item

With CI/CD

Exit codes enable CI integration:

- name: Validate Links
  run: |
    uv run plugins/link-tools/scripts/validate_links.py ./skills/
    # Fails build if violations found (exit 1)