Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill pr-gfm-validator -a claude-code
Open on GitHub

What 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 create without 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, not main.

How to install pr-gfm-validator

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill pr-gfm-validator -a claude-code

2Manually: put the files in place

~/.claude/skills/pr-gfm-validator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pr-gfm-validator/

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

Similar skills

All skills for Git and GitHub →

From the same set79

The whole set →
booking-notify booking-notify sends notifications for new bookings, cancellations and reschedules via Telegram and Pushover. 6-hour polling sync, real-time webhook for urgent events. CX Codex +1 125installs implement-plan-preflight implement-plan-preflight runs the ITP workflow preflight phase to generate MADR 4.0 architecture records, design specs, and linked diagrams. CX Codex +1 125installs issues-workflow issues-workflow puts plan, hierarchy and status into GitHub Issues: sub-issues under a parent, an issue linked to its branch and pull request, and a close on merge. CX Codex +1 124installs ml-failfast-validation ml-failfast-validation is a Claude Code skill that runs preflight checks for machine learning experiments, catching tensor, schema, and gradient errors before long training jobs. CX Codex +1 124installs pypi-doppler pypi-doppler — a skill for Claude Code and five other platforms that publishes Python packages to PyPI using a token stored in Doppler — local machine only. The bundled script detects CI environments and exits immediately if one is found. CX Codex +1 123installs schema-e2e-validation The schema-e2e-validation skill runs YAML schema generation and Earthly E2E checks. Use it before committing schema changes or to compare a contract with ClickHouse Cloud. CX Codex +1 123installs plugin-validator plugin-validator — a skill that validates plugin structure before release and catches silent failures in hooks—error-handling gaps in shell commands and unhandled Python exceptions. Essential before publishing to the marketplace. CX Codex +1 122installs evolutionary-metric-ranking evolutionary-metric-ranking is a Claude Code skill that ranks and filters model and strategy configurations across multiple metrics using percentile cutoffs, intersection rules, and evolutionary search. CX Codex +1 121installs

Project sponsors

Companies that keep this analytics open