Back to Details

link-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Link Validator

链接验证工具

Validates markdown links in Claude Code skills for portability across installation locations.
验证Claude Code技能中的Markdown链接在不同安装位置的可移植性。

The Problem

问题背景

Skills with absolute repo paths break when installed elsewhere:
Path TypeExampleWorks 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
使用绝对仓库路径的技能在其他位置安装时会失效：
路径类型示例安装后是否可用？
绝对仓库路径
/skills/foo/SKILL.md
否 - 路径不存在
相对路径
./references/guide.md
是 - 始终可解析
相对父路径
../sibling/SKILL.md
是 - 始终可解析

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
  • 分发技能/插件之前
  • 在技能中创建新的Markdown链接之后
  • CI报告链接验证失败时
  • 审计现有技能的可移植性问题时

TodoWrite Task Templates

TodoWrite任务模板

Template A: Validate Single Skill

模板A：验证单个技能

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
1. 确定要验证的技能路径
2. 运行：uv run scripts/validate_links.py <skill-path>
3. 查看违规报告（如有）
4. 针对每个违规项，应用建议的修复方案
5. 重新运行验证工具确认全部修复

Template B: Validate Plugin (Multiple Skills)

模板B：验证插件（多技能）

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
1. 确定插件根目录
2. 运行：uv run scripts/validate_links.py <plugin-path>
3. 查看按技能分组的违规项
4. 逐个技能修复违规问题
5. 重新验证整个插件

Template C: Fix Violations

模板C：修复违规项

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
1. 阅读违规报告输出
2. 定位到对应的文件和行号
3. 查看建议的相对路径
4. 使用编辑工具应用修复
5. 重新对该文件运行验证工具

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
修改该技能后：
  1. 脚本与最新模式保持同步
  2. 若添加新模式，更新相关引用
  3. 在存在违规项的真实技能上进行测试

Quick Start

快速开始

bash
undefined
bash
undefined

Validate a single skill

验证单个技能

uv run scripts/validate_links.py ~/.claude/skills/my-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/
uv run scripts/validate_links.py ~/.claude/plugins/my-plugin/

Dry-run in current directory

在当前目录进行试运行

uv run scripts/validate_links.py .
undefined
uv run scripts/validate_links.py .
undefined

Exit Codes

退出码说明

CodeMeaning
0All links valid (relative paths)
1Violations found (absolute repo paths)
2Error (invalid path, no markdown files)
代码含义
0所有链接有效（均为相对路径）
1发现违规项（存在绝对仓库路径）
2错误（路径无效，无Markdown文件）

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
标记为违规的情况：
  • /skills/foo/SKILL.md
    - 绝对仓库路径
  • /docs/guide.md
    - 绝对仓库路径
允许通过的情况：
  • ./references/guide.md
    - 同目录相对路径
  • ../sibling/SKILL.md
    - 父目录相对路径
  • https://example.com
    - 外部URL
  • #section
    - 锚点链接

Reference Documentation

参考文档

  • Link Patterns Reference - Detailed pattern explanations and fix strategies
  • 链接模式参考 - 详细的模式说明和修复策略

Troubleshooting

故障排除

IssueCauseSolution
Script not foundPath or plugin not installedVerify plugin installed with 
claude plugin list
Exit code 2Invalid path or no .md filesCheck target path exists and contains markdown
False positive on URLRegex matched external linkURLs starting with 
http
should be ignored
Anchor link flaggedScript treating 
#
as path		Anchor links (
#section
) are allowed by design
Relative path still failsWrong relative directionUse 
./
for same dir, 
../
for parent
Validation passes locallyCI uses different working dirEnsure CI runs from correct repo root
Too many violationsLegacy codebaseFix incrementally, prioritize high-impact files
Can't determine fixComplex path structureRead link-patterns.md for detailed fix strategies
问题原因解决方案
脚本未找到路径错误或插件未安装使用
claude plugin list
验证插件是否已安装
退出码2路径无效或无.md文件检查目标路径是否存在且包含Markdown文件
URL被误判为违规正则表达式匹配到外部链接以
http
开头的URL应被忽略
锚点链接被标记为违规脚本将
#
视为路径		锚点链接（
#section
）在设计上是允许的
相对路径仍验证失败相对方向错误同目录使用
./
，父目录使用
../
本地验证通过但CI失败CI使用不同的工作目录确保CI从正确的仓库根目录运行
违规项过多遗留代码库逐步修复，优先处理高影响文件
无法确定修复方案路径结构复杂阅读link-patterns.md获取详细修复策略