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.
Inherits all available tools
Additional assets for this skill
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:
# 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
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:
# 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"
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: