Clickable File Anchors

Clickable File Anchors

Overview

When quoting source code in a response, the file reference that introduces the quoted block must be a single absolute path with a line anchor that iTerm2 + VSCode/Cursor recognize as cmd-clickable.

Relative paths (packages/iris/src/foo.ts:42) are not clickable in iTerm2's Semantic History. Markdown links to file:// URIs are not clickable either — iTerm2 ignores the markdown wrapper. Only bare absolute paths with :line trigger the open-in-editor handoff.

Required Format

`/Users/toale/Developer/<repo>/<path-from-repo-root>:<start-line>`:

• Wrap in single backticks so the path renders as inline code.
• Path must be absolute and must start with /Users/toale/Developer/ (or another absolute root the user has on disk).
• Line anchor is a single integer = the first line of the quoted span. Do not use range syntax (:172-176) — iTerm2 + VSCode parse :line, not :line-line.
• Follow the inline-code anchor with a colon, then the fenced code block on the next line. No prose between anchor and block.
• The fenced block itself shows the full range, so range info is preserved visually without breaking clickability.

Canonical example

`/Users/toale/Developer/personnel/service/personnel.go:150`:

```go
func (s *PersonnelSvc) GetPersonnel(
  ctx context.Context, req *pb.GetPersonnelRequest,
) (*pb.GetPersonnelResponse, error) {
  funcName := "GetPersonnel"
  // ...
}
```

When to Use

Apply only to the inline anchor that introduces a fenced code block quoted from a real on-disk file. Specifically:

• Code-walk responses (file → function → callee, quote-and-narrate style).
• Debugging traces that quote the offending line.
• Code reviews that quote the diff context.
• "Show me where X is defined" answers.

When NOT to Use

Keep these references in whatever short form reads naturally — they are not clickable anchors:

• Inline prose mentions ("…handled by personnel.go's GetPersonnel handler…").
• Markdown table cells listing files.
• Function/symbol references without an attached quoted block.
• Bulleted file lists in summaries or punch lists.
• Generated/virtual paths (~/go/pkg/mod/... is fine if it resolves on disk; pure placeholder paths are not).

The rule is scoped to anchors that immediately precede a fenced code block. Anything else stays terse.

Quick Reference

Common Mistakes

Red Flags — STOP and Fix Before Sending

• A fenced code block is preceded by a path that does not start with /.
• An anchor uses :NNN-MMM range syntax.
• An anchor is wrapped in a markdown link [label](file://...).
• A file reference and its code block are separated by a sentence of prose.

All four mean: rewrite the anchor as a bare absolute path with a single-line suffix in backticks, placed directly above the block.

Rationalizations to Reject

Real-World Impact

Before this skill, a code-walk response anchors blocks with packages/iris/src/.../foo.ts:42-58. User has to read the path, mentally prepend the workspace root, open VSCode, Cmd+P the file, then jump to line 42. ~10 seconds of friction per anchor, dozens of times per walkthrough.

After this skill, every block is preceded by a bare absolute path ending in :N. Cmd-click in iTerm2 hands the path to VSCode/Cursor's URL handler, which opens the file scrolled to the exact line. Zero friction.