From 2dc4c132b79cf02dfe6b607f2bad4cc48818e17c Mon Sep 17 00:00:00 2001
From: Bo Zhang <187063395+Tethys0@users.noreply.github.com>
Date: Fri, 14 Aug 2026 10:20:18 -0500
Subject: [PATCH] docs(github): guide agents on autolinks

Add shared context instructions and coverage for GitHub's native reference syntax.\n\nCloses #3042
---
 pkg/github/toolset_instructions.go      |  6 +++++-
 pkg/github/toolset_instructions_test.go | 23 +++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 pkg/github/toolset_instructions_test.go

diff --git a/pkg/github/toolset_instructions.go b/pkg/github/toolset_instructions.go
index 3b3a54eadd..2a89e011c9 100644
--- a/pkg/github/toolset_instructions.go
+++ b/pkg/github/toolset_instructions.go
@@ -6,7 +6,11 @@ import "github.com/github/github-mcp-server/pkg/inventory"
 // They are called during inventory build to generate server instructions.
 
 func generateContextToolsetInstructions(_ *inventory.Inventory) string {
-	return "Always call 'get_me' first to understand current user permissions and context."
+	return `Always call 'get_me' first to understand current user permissions and context.
+
+## GitHub Autolinked References
+
+When creating issues, pull requests, comments, or discussions, use GitHub's autolinked reference syntax: issue numbers (#123), user mentions (@example-username), and cross-repository references (example-owner/example-repo#123). GitHub renders these references as links automatically. See the official documentation for complete details: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls`
 }
 
 func generateIssuesToolsetInstructions(_ *inventory.Inventory) string {
diff --git a/pkg/github/toolset_instructions_test.go b/pkg/github/toolset_instructions_test.go
new file mode 100644
index 0000000000..8b618e13d4
--- /dev/null
+++ b/pkg/github/toolset_instructions_test.go
@@ -0,0 +1,23 @@
+package github
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+)
+
+func TestGenerateContextToolsetInstructionsIncludesAutolinkGuidance(t *testing.T) {
+	instructions := generateContextToolsetInstructions(&inventory.Inventory{})
+
+	for _, expected := range []string{
+		"#123",
+		"@example-username",
+		"example-owner/example-repo#123",
+		"https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls",
+	} {
+		if !strings.Contains(instructions, expected) {
+			t.Fatalf("expected context instructions to include %q, got %q", expected, instructions)
+		}
+	}
+}