wahidyankf Validating Markdown Links
This Skill provides comprehensive guidance for validating markdown links across the repository, including internal link validation, external link verification, and checker implementation strategies.
Purpose
Use this Skill when:
- Implementing link validation in checker agents
- Validating internal documentation links
- Verifying external URL accessibility
- Checking site link formatting
- Implementing link caching strategies
- Understanding link validation patterns
Link Validation Principles
Lifecycle Delegation
Quality-gate invocations may pass delegated-gate-ids from
Lifecycle Validation Ownership.
Match exact IDs only. If md-links is present, do not resolve, re-check, fix, or AI-rederive
internal paths and fragments. Continue external HTTP reachability and cache maintenance. If the
parameter is omitted, preserve standalone full validation.
Also accept lifecycle-evidence: checkers preserve it unchanged; fixers scope-intersect changed
files and return updated-lifecycle-evidence, invalidating only affected entries.
Why Link Validation Matters
Broken links:
- Break user navigation experience
- Reduce documentation credibility
- Create maintenance burden (hard to find broken links manually)
- Indicate structural issues (moved/deleted files)
Link validation:
- Prevents broken links from reaching production
- Catches file renames and moves
- Validates external resources still exist
- Ensures consistent link formatting
Validation Scope
What to validate:
- Internal markdown links (docs/, repo-governance/, plans/)
- Content links (apps/ayokoding-www/, apps/ose-www/)
- External URLs (HTTP/HTTPS)
- Image links (relative paths)
- Anchor links (same-page headings)
What NOT to validate:
- Links in code blocks (examples, not actual links)
- Links in quoted text (preserved formatting)
- Commented-out links (intentionally disabled)
Internal Link Validation
See Internal Link Validation for the required link format, three-step validation methodology, and the four common internal-link errors with criticality/detection.
External Link Validation
See External Link Validation for verification strategy, HTTP request pattern/status-code handling, link caching strategy (TTLs), and common external-link errors.
Checker Implementation Patterns
See Checker Implementation Patterns for the 5-step checker workflow, progressive-writing requirement, required tools, criticality categorization, and the dual-label (verification + criticality) pattern.
docs-link-checker Agent Contract
docs-link-checker diverges from this Skill's generic cache sketch. See
docs-link-checker Cache and Workflow for its specific
6-month per-link expiry cache contract, required outputs, discovery/extraction patterns, and
fixing workflow.
Related Conventions
Linking Standards:
- Linking Convention - Complete linking standards
- Linking Convention - Standard linking patterns for docs/ and app content
Validation Standards:
- Repository Validation Methodology - Standard validation patterns
- Criticality Levels Convention - Criticality classification
Quality Standards:
- Content Quality Principles - Link text quality requirements
Related Skills
Validation Skills:
- repo-assessing-criticality-confidence - Criticality and confidence levels
- repo-applying-maker-checker-fixer - Checker workflow patterns
- repo-generating-validation-reports - Report format and progressive writing
Domain Skills:
- apps-ayokoding-www-developing-content - ayokoding-web content linking patterns (Next.js)
Related Agents
Link Validation Agents:
- docs-link-checker - Validates links in docs/, repo-governance/, plans/
- apps-ayokoding-www-link-checker - Validates links in ayokoding-web content