Validate and auto-fix GitHub Flavored Markdown links in PR descriptions. Use when creating pull requests, mentioning PR links, gh pr create, GFM validation, or fixing broken PR links. Converts repo-relative paths to branch-specific blob URLs.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Validate and auto-convert GFM links in pull request descriptions to prevent 404 errors.
This skill triggers when:
gh pr create or gh pr editRepository-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) |
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
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
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 relativeSKIP these patterns:
https://... - Already absolute URLshttp://... - Already absolute URLs#anchor - In-page anchorsmailto:... - Email linksFor each link to convert:
# Pattern
f"https://github.com/{owner}/{repo}/blob/{branch}/{path}"
# Example
owner = "Eon-Labs"
repo = "alpha-forge"
branch = "feat/2025-12-01-eth-block-metrics"
path = "docs/adr/2025-12-01-file.md"
# Result
"https://github.com/Eon-Labs/alpha-forge/blob/feat/2025-12-01-eth-block-metrics/docs/adr/2025-12-01-file.md"
Replace all identified links in the PR body:
# Before
[Plugin Design](/docs/adr/2025-12-01-slug.md)
# After
[Plugin Design](https://github.com/Eon-Labs/alpha-forge/blob/feat/branch/docs/adr/2025-12-01-slug.md)
After conversion, verify:
When creating a PR, apply this workflow automatically:
/usr/bin/env bash << 'GIT_EOF'
# 1. Get context
REPO_INFO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
OWNER=$(echo "$REPO_INFO" | cut -d'/' -f1)
REPO=$(echo "$REPO_INFO" | cut -d'/' -f2)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
# 2. Process PR body (convert links)
# ... link conversion logic ...
# 3. Create PR with converted body
gh pr create --title "..." --body "$CONVERTED_BODY"
GIT_EOF
Use this regex pattern to find GFM links:
\[([^\]]+)\]\((/[^)]+|\.\.?/[^)]+)\)
Breakdown:
\[([^\]]+)\] - Capture link text\( - Opening parenthesis(/[^)]+|\.\.?/[^)]+) - Capture path starting with /, ./, or ../\) - Closing parenthesisInput:
See the [ADR](/docs/adr/2025-12-01-eth-block-metrics.md) for details.
Context:
Eon-Labsalpha-forgefeat/2025-12-01-eth-block-metrics-data-pluginOutput:
See the [ADR](https://github.com/Eon-Labs/alpha-forge/blob/feat/2025-12-01-eth-block-metrics-data-plugin/docs/adr/2025-12-01-eth-block-metrics.md) for details.
Input:
## References
- [Plugin Design](/docs/adr/2025-12-01-slug.md)
- [Probe Integration](/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)
Output:
## References
- [Plugin Design](https://github.com/Eon-Labs/alpha-forge/blob/feat/branch/docs/adr/2025-12-01-slug.md)
- [Probe Integration](https://github.com/Eon-Labs/alpha-forge/blob/feat/branch/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)
Note: External link unchanged.
Input:
**See [`.env.clickhouse`](/.env.clickhouse)** for credentials.
Output:
**See [`.env.clickhouse`](https://github.com/Eon-Labs/alpha-forge/blob/feat/branch/.env.clickhouse)** for credentials.
After modifying this skill: