pr-gfm-validator

PR GFM Link Validator

Validate and auto-convert GFM links in pull request descriptions to prevent 404 errors.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

This skill triggers when:

• Creating a pull request from a feature branch
• Discussing PR descriptions or body content
• Mentioning GFM links, PR links, or link validation
• Using gh pr create or gh pr edit

The Problem

Repository-relative links in PR descriptions resolve to the base branch (main), not the feature branch:

Link in PR Body	GitHub Resolves To	Result
[ADR](/docs/adr/file.md)	/blob/main/docs/adr/file.md	404 (file only on feature branch)

The Solution

Convert repo-relative links to absolute blob URLs with the correct branch:

/docs/adr/file.md
    ↓
https://github.com/{owner}/{repo}/blob/{branch}/docs/adr/file.md

---

Workflow

Step 1: Detect Context

Before any PR operation, gather repository context:

/usr/bin/env bash << 'PREFLIGHT_EOF'
# Get repo owner and name
gh repo view --json nameWithOwner --jq '.nameWithOwner'

# Get current branch
git rev-parse --abbrev-ref HEAD

# Check if on feature branch (not main/master)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "On default branch - no conversion needed"
  exit 0
fi
PREFLIGHT_EOF

Step 2: Identify Links to Convert

Scan PR body for GFM links matching these patterns:

CONVERT these patterns:

• /path/to/file.md - Repo-root relative
• ./relative/path.md - Current-directory relative
• ../parent/path.md - Parent-directory relative

SKIP these patterns:

• https://... - Already absolute URLs
• http://... - Already absolute URLs
• #anchor - In-page anchors
• mailto:... - Email links