| name | gh-links |
| description | How to reference commits, issues, PRs, files and lines in GitHub-posted prose:
every reference MUST be a fully clickable Markdown link, never bare text.
Use when (ALWAYS, before posting):
- Writing a `gh issue comment` or `gh pr comment` body
- Writing a `gh issue create` or `gh pr create` body/description
- Writing PR review comments
- Any prose that will be posted to GitHub and mentions a commit hash,
another issue/PR, a file path, or a code line
Applies to sub-agents too — any agent posting to GitHub follows this.
|
| allowed-tools | Bash, Read |
GitHub references must be clickable links
The rule (standing)
In any text posted to GitHub — issue comments, PR comments, issue/PR
bodies, review comments — every reference to a related thing is a full,
clickable Markdown link, never bare text. That covers:
- commit hashes
- other issues and PRs (same repo or another repo)
- files and directories
- specific code lines
Bare abc1234, #123, or src/Foo.php in a comment is not acceptable, even
though GitHub sometimes auto-links same-repo issue numbers and full SHAs — it is
unreliable (short SHAs, file paths, and cross-repo refs do not auto-link) and
the reader must be able to click straight through in every case.
How to build the URLs
First get the repo slug once (owner/name):
gh repo view --json nameWithOwner -q .nameWithOwner
Then, with OWNER/REPO (and the branch/sha for file links):
| Reference | Markdown to write |
|---|
| Commit | [`abc1234`](https://github.com/OWNER/REPO/commit/abc1234) |
| Issue (same or other repo) | [#123](https://github.com/OWNER/REPO/issues/123) |
| Pull request | [#123](https://github.com/OWNER/REPO/pull/123) |
| File | [path/to/File.ext](https://github.com/OWNER/REPO/blob/main/path/to/File.ext) |
| File at a line | [File.ext:42](https://github.com/OWNER/REPO/blob/main/path/to/File.ext#L42) |
| Line range | append #L42-L58 to the blob URL |
| Thing in a different repo | full https://github.com/OTHER_OWNER/OTHER_REPO/... URL |
Notes:
- For files, use a stable ref in the URL — a commit SHA or the default
branch — that already exists on the remote. Never link a local
feature branch (or unpushed commits) that a reader cannot reach; if the
target is not yet pushed, push it first or omit the link.
- Link the label to what it says: show the short SHA /
#num / file name as the
link text, not a naked long URL.
Workflow
Compose the body in a temp file, put the links in, then post with --body-file
(avoids shell-escaping and keeps the links intact):
BODY="$(mktemp)"
gh issue comment 123 --repo OWNER/REPO --body-file "$BODY"
gh pr comment 123 --repo OWNER/REPO --body-file "$BODY"
Before posting, re-scan the body: any bare hash, bare #num, or bare path that
names a real thing must become a link.
