Menu
Comprehensive link validation methodology for markdown links including format requirements, path validation, broken link detection, external link verification, and checker implementation patterns
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
AI agent development standards including frontmatter structure, naming conventions, tool access patterns, model selection, and reference documentation structure
UI development skill covering design token usage, shadcn/ui + Radix composition patterns, accessibility requirements, anti-patterns catalog, and brand context for OrganicLever and OSE Platform. Auto-loads when working on TSX components, CSS, or UI design tasks.
Comprehensive project planning standards for plans/ directory including folder structure (ideas/, backlog/, in-progress/, done/), stage-aware naming convention (done uses YYYY-MM-DD__identifier/; backlog and in-progress use identifier/ with no date prefix), five-document file organization (README.md, brd.md, prd.md, tech-docs.md, delivery.md for multi-file default; single README.md for trivially-small single-file exception), BRD/PRD content-placement rules, Gherkin acceptance criteria, and the mandatory structured multiple-choice grilling gates (pre-write and post-write) for resolving design decisions with the user. Essential for creating structured, executable project plans.
Workflow pattern standards for creating multi-agent orchestrations including YAML frontmatter (name, goal, termination, inputs, outputs), execution phases (sequential/parallel/conditional), agent coordination patterns, and Gherkin success criteria. Essential for defining reusable, validated workflow processes.
Trunk Based Development workflow - all development on main branch with small frequent commits, minimal branching, and continuous integration. Covers when branches are justified (exceptional cases only), commit patterns, feature flag usage for incomplete work, environment branch rules (deployment only), and AI agent default behavior (the repo-wide default delivery mode is `worktree-to-pr` -- a short-lived plan branch in a disposable worktree pushed to a draft PR; direct push to main remains available as an explicit selection). Essential for understanding repository git workflow and keeping branches short-lived
Common software development workflow patterns shared across all language developer agents
| name | docs-validating-links |
| description | Comprehensive link validation methodology for markdown links including format requirements, path validation, broken link detection, external link verification, and checker implementation patterns |
| created | "2025-01-22T00:00:00.000Z" |
This Skill provides comprehensive guidance for validating markdown links across the repository, including internal link validation, external link verification, and checker implementation strategies.
Use this Skill when:
Broken links:
Link validation:
What to validate:
What NOT to validate:
Documentation files (docs/, repo-governance/, plans/, root .md files):
✅ PASS: File Naming Convention ✅ PASS: AI Agents Convention
❌ FAIL: File Naming Convention ← Missing .md extension ❌ FAIL: [[file-naming]] ← Wiki-link syntax (GitHub does not render these) ❌ FAIL: file-naming.md ← Using filename as link text
Note: Both apps/ayokoding-www/ and apps/ose-www/ have migrated to Next.js 16. Their content links are validated by their respective CLI tools (ayokoding-cli links check, ose-cli links check), not by this Skill's link validation rules.
Step 1: Extract Links from Markdown
Use regex or markdown parser to extract all links
Step 2: Categorize Links
Separate into categories:
Step 3: Validate Internal Links
For each internal link:
Error 1: Missing .md extension
❌ FAIL: File Naming ✅ PASS: File Naming
Criticality: HIGH - Breaks GitHub web navigation Detection: Check link ends with .md (docs/ files only)
Error 2: Wrong relative path depth
From: repo-governance/conventions/formatting/linking.md (3 levels deep) ❌ FAIL: Documentation Home ← Only 1 ../, need 3 ✅ PASS: Documentation Home
Criticality: CRITICAL - Link points to wrong file or 404 Detection: Resolve path and check file exists
Error 3: Wiki-link syntax
❌ FAIL: [[file-naming-convention]] ❌ FAIL: [[file-naming-convention|File Naming]] ✅ PASS: File Naming Convention
Criticality: HIGH - GitHub does not render wiki-style links Detection: Regex match for wiki-style links
Error 4: Filename as link text
❌ FAIL: file-naming.md ✅ PASS: File Naming Convention
Criticality: MEDIUM - Poor accessibility and readability Detection: Check if link text matches filename pattern or contains file extension
Challenge: External links can be slow to verify (network requests)
Recommended approach:
Verification steps:
Cache file format (JSON):
{ "https://diataxis.fr/": { "status": "OK", "http_code": 200, "last_checked": "2026-01-25T13:30:00+07:00", "ttl": 604800 } }
Cache TTL recommendations:
Error 1: Link returns 404
Criticality: HIGH - Link is dead, user gets 404 Action: Update or remove link
Error 2: Link redirects (301/302)
Criticality: LOW - Link works but could be updated to final URL Action: Consider updating to final destination (optional)
Error 3: Link times out
Criticality: MEDIUM - May be temporary network issue Action: Re-verify after TTL expires, flag if persistent
Standard 5-step checker workflow:
Step 0: Initialize Report Step 1: Discover Files (glob for *.md) Step 2: Extract Links (parse markdown, categorize) Step 3: Validate Internal Links (file exists, format correct) Step 4: Validate External Links (HTTP request, cache results) Step 5: Finalize Report (summary, grouped by criticality)
CRITICAL: Write findings to report file immediately after discovery (don't buffer in memory)
Why: Context compaction can lose buffered findings during long validation runs
Required tools:
CRITICAL (Must fix before publication):
[[...]] links)HIGH (Should fix before publication):
MEDIUM (Fix when convenient):
LOW (Optional improvements):
Link checkers use both verification status AND criticality:
Finding: [BROKEN] - Internal Link to Non-Existent File
Verification: [BROKEN] - Target file does not exist Criticality: CRITICAL - Breaks user navigation
Verification labels:
Why dual labels?
Linking Standards:
Validation Standards:
Quality Standards:
Validation Skills:
Domain Skills:
Link Validation Agents: