Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: encourage bot to use links when referencing files (#1161)

worktrunk-bota37ad1be8c87
diff --git a/.claude/skills/running-in-ci/SKILL.md b/.claude/skills/running-in-ci/SKILL.md
index 4b9fdc229..b66f77742 100644
--- a/.claude/skills/running-in-ci/SKILL.md
+++ b/.claude/skills/running-in-ci/SKILL.md
@@ -1,6 +1,6 @@
---
name: running-in-ci
-description: CI environment rules for GitHub Actions workflows. Use when operating in CI — covers security, CI monitoring, and PR comment formatting.
+description: CI environment rules for GitHub Actions workflows. Use when operating in CI — covers security, CI monitoring, and comment formatting.
---
# Running in CI
@@ -51,13 +51,37 @@ After pushing changes to a PR branch, monitor CI until all checks pass:
5. Do not return until CI is green — local tests alone are not sufficient (CI
runs on Linux, Windows, macOS)
-## PR Comment Formatting
+## Comment Formatting
-Keep PR comments concise. Put detailed analysis (file-by-file breakdowns, code
+Keep comments concise. Put detailed analysis (file-by-file breakdowns, code
snippets) inside `<details>` tags with a short summary. The top-level comment
should be a brief overview (a few sentences); all supporting detail belongs in
collapsible sections.
+### Use Links
+
+When referencing files, issues, PRs, or docs, always use markdown links so
+readers can click through — never leave them as plain text.
+
+Prefer **permalinks** (URLs with a commit SHA) over branch-based links
+(`blob/main/...`). Permalinks stay valid even when files move or lines shift.
+This is especially important for line references — a `blob/main/...#L42` link
+breaks as soon as the line numbers change. On GitHub, pressing `y` on any file
+view copies the permalink.
+
+- **Repository files** — link to the file on GitHub:
+ [`docs/content/hook.md`](https://github.com/max-sixty/worktrunk/blob/main/docs/content/hook.md),
+ not just `docs/content/hook.md`
+- **Issues and PRs** — use `#123` shorthand (GitHub auto-links these)
+- **Specific lines** — link with a line fragment:
+ [`src/cli/mod.rs#L42`](https://github.com/max-sixty/worktrunk/blob/main/src/cli/mod.rs#L42)
+- **External resources** — always use `[text](url)` format
+
+For file-level links, `blob/main/...` is acceptable since file paths are stable.
+For **line references**, always use a permalink with a commit SHA
+(`blob/<sha>/...#L42`) — line numbers shift frequently and branch-based line
+links go stale fast.
+
Example:
```