pr-gfm-validator — Claude Code skill: fixing GFM links in PRs
pr-gfm-validator turns relative markdown links in a pull request body into absolute blob URLs pinned to your feature branch, so reviewers stop landing on 404s.
MIT 123 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a claude-codeWhat pr-gfm-validator does
Hand it a PR description and the skill rewrites repo-relative paths as full blob URLs carrying the branch name. Without that, GitHub resolves a path like [ADR](/docs/adr/file.md) against the base branch. The file sits on your feature branch, the lookup happens on main, and the reader gets a 404.
It pulls owner/repo from gh repo view and the branch from git rev-parse --abbrev-ref HEAD, then matches links starting with /, ./ or ../. Absolute URLs, #anchor jumps and mailto: entries pass through untouched. Run it on main or master and it does nothing, since relative paths already resolve there.
Conversion only helps if the target file reached the remote. Nothing is pushed yet, the new URL is still a 404 — commit and push before gh pr create. Branch names containing slashes need URL encoding when they go into the address.
What it helps with
- catch dead links in a PR description before review starts
- swap
/docs/...paths for full blob URLs on the feature branch - leave external links and anchors alone during a bulk rewrite
- open a pull request through
gh pr createwithout hand-editing the body - skip the rewrite when the work happens on
main
Example prompts for the agent
- Open a PR from this branch and check that every link in the description resolves on GitHub.
- Run the GFM validation over the PR body and replace the relative paths with absolute ones.
- Fix the
[ADR](/docs/adr/file.md)link in the pull request description so it points at my branch, notmain.
How to install pr-gfm-validator
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a claude-code2Manually: put the files in place
~/.claude/skills/pr-gfm-validator/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pr-gfm-validator/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a codex2Manually: put the files in place
.agents/skills/pr-gfm-validator/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a cursor2Manually: put the files in place
.cursor/skills/pr-gfm-validator/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/gh-tools/skills/pr-gfm-validator2Manually: put the files in place
.github/skills/pr-gfm-validator/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/gh-tools/skills/pr-gfm-validatorManually: put the files in place
.devin/skills/pr-gfm-validator/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pr-gfm-validator
How do I install pr-gfm-validator in Claude Code?
Run npx skills add terrylica/cc-skills --skill pr-gfm-validator -a claude-code. The skill file lands at ~/.claude/skills/pr-gfm-validator/SKILL.md.
What does pr-gfm-validator do?
It finds markdown links in a pull request body that begin with /, ./ or ../ and rewrites them as absolute blob URLs on the current branch. Other link types stay as written.
Why does a link to a feature-branch file 404 in the PR description?
GitHub resolves relative paths against the base branch. A file that exists only on your branch gets looked up in main and comes back missing. An absolute blob URL naming the branch avoids that.
Source text
SKILL.md · MIT
---
name: pr-gfm-validator
description: Validate and fix GFM links in PR descriptions. TRIGGERS - PR links, gh pr create, GFM validation, broken PR links.
allowed-tools: Bash, Read, Grep
---
# 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:
```bash
/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
### Step 3: Construct Blob URLs
For each link to convert:
```python
# Pattern
f"https://github.com/{owner}/{repo}/blob/{branch}/{path}"
# Example
owner = "example-org"
repo = "research-repo"
branch = "feat/2025-12-01-eth-block-metrics"
path = "docs/adr/2025-12-01-file.md"
# Result
"https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics/docs/adr/2025-12-01-file.md"
```
### Step 4: Apply Conversions
Replace all identified links in the PR body:
```markdown
# Before
[Plugin Design](/docs/adr/2025-12-01-slug.md)
# After
[Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)
```
### Step 5: Validate Result
After conversion, verify:
1. All repo-relative links are now absolute blob URLs
2. External links remain unchanged
3. Anchor links remain unchanged
---
## Integration with gh pr create
When creating a PR, apply this workflow automatically:
```bash
/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
```
---
## Link Detection Regex
Use this regex pattern to find GFM links:
```regex
\[([^\]]+)\]\((/[^)]+|\.\.?/[^)]+)\)
```
Breakdown:
- `\[([^\]]+)\]` - Capture link text
- `\(` - Opening parenthesis
- `(/[^)]+|\.\.?/[^)]+)` - Capture path starting with `/`, `./`, or `../`
- `\)` - Closing parenthesis
---
## Examples
### Example 1: Simple Repo-Relative Link
**Input:**
```markdown
See the [ADR](/docs/adr/2025-12-01-eth-block-metrics.md) for details.
```
**Context:**
- Owner: `example-org`
- Repo: `research-repo`
- Branch: `feat/2025-12-01-eth-block-metrics-data-plugin`
**Output:**
```markdown
See the [ADR](https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics-data-plugin/docs/adr/2025-12-01-eth-block-metrics.md) for details.
```
### Example 2: Multiple Links
**Input:**
```markdown
## 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:**
```markdown
## References
- [Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)
- [Probe Integration](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)
```
Note: External link unchanged.
### Example 3: Credential File Link
**Input:**
```markdown
**See [`.env.clickhouse`](/.env.clickhouse)** for credentials.
```
**Output:**
```markdown
**See [`.env.clickhouse`](https://github.com/example-org/research-repo/blob/feat/branch/.env.clickhouse)** for credentials.
```
---
## Edge Cases
### Already on main/master
- Skip conversion entirely
- Repo-relative links will work correctly
### Empty PR Body
- Nothing to convert
- Proceed with PR creation
### No GFM Links Found
- Nothing to convert
- Proceed with PR creation
### Mixed Link Types
- Convert only repo-relative links
- Preserve external URLs, anchors, mailto links
---
## Post-Change Checklist
After modifying this skill:
1. [ ] Regex patterns still match intended link formats
2. [ ] Examples reflect current behavior
3. [ ] Edge cases documented
4. [ ] Workflow steps are executable
---
## References
- [GitHub Blob URLs](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)
- [GFM Link Syntax](https://github.github.com/gfm/#links)
- [gh CLI Documentation](https://cli.github.com/manual/gh_pr_create)
---
## Troubleshooting
| 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 |
## Post-Execution Reflection
After this skill completes, reflect before closing the task:
0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.
© terrylica · MIT · terrylica/cc-skills