Validate and fix GFM links in PR descriptions. TRIGGERS - PR links, gh pr create, GFM validation, broken PR links.
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.
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:
| Issue | Cause | Solution |
| ------------------------ | ------------------------------ | ------------------------------------------------- |
| Links still 404 after PR | File not pushed to branch yet | Push commits before creating PR |
| Regex not matching links | Escaped parentheses in content | Use raw string regex pattern |
| Branch name has slashes | URL encoding needed | Encode branch name for URL construction |
| External links converted | Pattern too broad | Check link starts with /, ./, or ../ only |
| gh repo view fails | Not in a git repository | Run from repository root directory |
| Anchor links broken | Incorrectly included in scan | Skip links starting with # |
| Wrong repo detected | Remote not set correctly | Check git remote -v output |
| Conversion duplicated | Running validator twice | Check if links already absolute before converting |
After this skill completes, reflect before closing the task:
Do NOT defer. The next invocation inherits whatever you leave behind.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer