kicad-tools: Command for Claude Code

/repo:links — Link Checker

Validate that internal cross-references across the repo actually resolve. Catches broken links from reorganization, renames, and deletions.

This is the cross-reference layer of [[docs]]. Use it directly when that's all you want to check; use [[docs]] for the full documentation sweep.

Usage

/repo:links                    # Full repo — fix unambiguous links, report as you go
/repo:links CLAUDE.md          # Check one file
/repo:links .claude/           # Check skill/command files
/repo:links --ask              # Review findings and confirm before fixing

What It Checks

1. Markdown Links

Scan all .md files for [text](path) links where path is a relative file path (not a URL). Verify the target exists on disk.

Strip code before scanning. Remove fenced blocks and inline code spans from the text first — a [text](path) inside backticks is a description of a link, not a link:

text = re.sub(r"```.*?```", "", text, flags=re.S)  # fenced blocks
text = re.sub(r"`[^`]*`", "", text)  # inline spans

Without this the checker flags the sentences in this very file, and in [[audit]], that explain what it looks for. A checker that reports its own documentation as broken is not a checker anyone keeps running.

Skip:

• External URLs (http://, https://)
• Anchor-only links (#section)
• Image URLs from external services

Resolve against two bases, and only report a link that fails both. A relative path can legitimately be written against either the file's own directory or the repo root, and both conventions are in active use:

1. the directory of the file containing the link
2. the repo root

Both bases resolve only candidates that stay inside the repo toplevel. Normalize dirname(F)/P (base 1) and P (base 2) lexically — collapse . and .. path components without touching the filesystem, never realpath/readlink -f — and check whether the normalized result still begins with ... A candidate that does is not tried as base 1 or base 2 at all, even when a file happens to exist at that escaping path on disk: it is handed to the sibling-repo base (see Sibling-repo relative links below) instead. An escaping candidate that resolves anyway is a citation into another repo silently reported as if it were in place — undisclosed proof it crossed a repo boundary, exactly the gap this restriction closes. Detection must stay lexical: resolving symlinks (realpath/readlink -f) would deport a symlinked directory that stays inside the repo to the sibling base by mistake, since a symlink target can differ from its lexical path without the link itself ever leaving the repo.