Link Auditor Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before auditing
• Non-Destructive: Never modify content files without explicit user request
• Complete Output: Show all findings; never summarize or abbreviate issue lists
• Issue Classification: Clearly distinguish critical issues (orphans, broken links) from suggestions (under-linked)
• Hugo Path Awareness: Try multiple path resolutions before reporting a link as broken

Default Behaviors (ON unless disabled)

• Full Scan: Analyze all markdown files in content/
• Graph Analysis: Build and analyze internal link adjacency graph
• Image Validation: Check all image paths exist in static/
• Skip External Validation: Do not HTTP-check external URLs (enable with --check-external)
• Issues-Only Output: Show only problems, not all valid links

Optional Behaviors (OFF unless enabled)

• External Link Validation: HTTP HEAD check on external URLs (--check-external)
• Verbose Mode: Show all links including valid ones (--verbose)
• Custom Inbound Threshold: Flag pages with fewer than N inbound links (--min-inbound N)

What This Skill CAN Do

• Extract internal, external, and image links from Hugo markdown content
• Build adjacency matrix of internal link relationships
• Identify orphan pages (0 inbound internal links) and under-linked pages
• Detect link sinks (receive links, no outbound) and hub pages (many outbound)
• Validate internal link paths resolve to real content files
• Validate image files exist in static/
• Optionally validate external URLs via HTTP HEAD requests
• Handle known false positives (LinkedIn, Twitter block bot requests)
• Generate audit reports with actionable fix suggestions

What This Skill CANNOT Do

• Validate external URLs by default (network latency, rate limiting concerns)
• Guarantee external link accuracy (social media sites block bots)
• Automatically fix broken links or add missing links
• Analyze JavaScript-rendered content or Hugo shortcodes beyond standard patterns
• Replace pre-publish-checker for single-post validation

Instructions

Phase 1: SCAN

# TODO: scripts/link_scanner.py not yet implemented
# Manual alternative: extract links from markdown files
grep -rn '\[.*\](.*' ~/your-blog/content/ --include="*.md"

• [text](/posts/slug/)

  -- absolute internal path

• [text](../other-post/)

  -- relative path

• [text](/categories/tech/)

  -- taxonomy pages

• {{< ref "posts/slug.md" >}}

  -- Hugo ref shortcode

• [text](https://example.com/path)

• [text](http://example.com/path)

• ![alt](/images/filename.png)

  -- static path

• ![alt](images/filename.png)

  -- relative path

• {{< figure src="/images/file.png" >}}

  -- Hugo shortcode

Phase 2: ANALYZE

Page A -> Page B (A links to B)
Page A -> Page C
Page B -> Page D
Page C -> (no outbound)
Page E -> (no outbound, no inbound = orphan)

• Critical: Orphan pages, broken internal links, missing images
• Warning: Under-linked pages, link sinks
• Info: Hub pages, external link stats

Phase 3: VALIDATE

1. Parse the link target path
2. Try Hugo path resolutions:

   content/posts/slug.md

   ,

   content/posts/slug/index.md

   ,

   content/posts/slug/_index.md

3. Mark as broken only if ALL resolutions fail
4. Record source file and line number for broken links

1. Parse image source path (absolute or relative)
2. Map to static/ directory
3. Check file exists
4. Record source file and line number for missing images

--check-external

1. HTTP HEAD request to URL
2. Follow redirects (up to 3)
3. Check response status code
4. Mark known false positives as "blocked (expected)" not broken

Phase 4: REPORT

===============================================================
 LINK AUDIT: ~/your-blog/content/
===============================================================

 SCAN SUMMARY:
   Posts scanned: 15
   Internal links: 42
   External links: 28
   Image references: 12

• File path
• Line number (for broken links and missing images)
• Specific suggestion for resolution

===============================================================
 RECOMMENDATIONS:
   1. Add internal links to 2 orphan pages
   2. Fix 1 broken internal link in /posts/example.md line 45
   3. Update or remove 1 dead external link
   4. Add missing image or fix path in /posts/images.md line 12
===============================================================

Error Handling

Error: "No markdown files found"

1. Verify the content/ directory exists at the given path
2. Check that .md files exist (not just subdirectories)
3. Confirm the path is the Hugo content root, not the project root

Error: "External validation timeout"

1. Check if the site is in the known false-positives list (LinkedIn, Twitter)
2. Add persistently failing sites to the false-positives list
3. Use shorter timeout with

   --timeout 5

   for slow sites

Error: "Image path ambiguous"

1. The scanner checks both interpretations automatically
2. Report shows which interpretation was attempted
3. Verify the Hugo site's static directory structure matches expectations

Anti-Patterns

Anti-Pattern 1: Treating Bot-Blocked Sites as Broken

Anti-Pattern 2: Skipping Graph Analysis

Anti-Pattern 3: Literal Path Matching Without Hugo Resolution

/posts/slug/

Anti-Pattern 4: Modifying Content Without User Consent

References

• Anti-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks

Domain-Specific Anti-Rationalization

Reference Files

• ${CLAUDE_SKILL_DIR}/references/link-graph-metrics.md

  : Graph metrics definitions and SEO impact

• ${CLAUDE_SKILL_DIR}/references/false-positives.md

  : Sites known to block validation requests

• ${CLAUDE_SKILL_DIR}/references/fix-strategies.md

  : Resolution strategies for each issue type