Add guidance on GitHub autolinked reference formatting for AI agents
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 88/100
Research direction
Start in pkg/github/toolset_instructions.go at generateContextToolsetInstructions(), and compare the existing github_support_docs_search guidance. Verify that the generated base context includes a concise link to GitHub's autolinked references documentation before content-creation tools are used. Done means the guidance covers issue, pull request, comment, and discussion references without adding a new tool or duplicating it in other toolsets.
Written by the indexing model from the issue text.
Description
Describe the feature or problem you'd like to solve
AI agents using the MCP server create manual markdown links when they could use GitHub's built-in autolinked references instead. GitHub automatically renders patterns like #123, @username, and owner/repo#123 as clickable links across issues, pull requests, comments, and discussions—but agents lack this knowledge in their system instructions.
For complete reference and examples, see:
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
Proposed solution
Add guidance to the base context instructions (via generateContextToolsetInstructions()) so all agents learn about autolinked references before using any content-creation tools. This ensures consistent formatting across all GitHub interactions without duplicating guidance in multiple toolsets.
Benefits:
- Universal coverage: Applies to all content-creation tools (issues, PRs, comments, discussions)
- Single source of truth: One place to maintain, not scattered across toolsets
- Early discovery: Agents see this guidance at initialization, before using any specific tool
- No duplication: Leverage official docs instead of repeating content
Implementation:
Add a section to pkg/github/toolset_instructions.go in generateContextToolsetInstructions():
func generateContextToolsetInstructions(_ *inventory.Inventory) string {
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-repo references (example-owner/example-repo#123)—so GitHub renders them as links automatically.
See the official docs for complete details: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls.md`
}
This approach follows the existing pattern of github_support_docs_search, which references official documentation rather than duplicating content.
Additional context
This is a lightweight enhancement that integrates seamlessly into the existing base context instructions. No new tools or infrastructure required—just a brief instruction pointing agents to official GitHub docs.
Future enhancement:
If agents need to proactively request formatting guidance (e.g., "How should I format this reference?"), consider creating a dedicated resource or skill in the MCP server. This would allow agents to ask for formatting help on-demand while still having the baseline guidance available at initialization. This can be explored as a follow-up if needed.
- Dominant language
- Go
- Stars
- 33.1k
- Forks
- 5k
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 25
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/github-mcp-server
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
github/github-mcp-server#3235 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
github/github-mcp-server#3032 · 1 reaction ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
github/github-mcp-server#2803 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
github/github-mcp-server#2740 ·
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
github/github-mcp-server#2661 · 1 comment ·
All issues in github/github-mcp-server
Similar issues
-
feature-request helm
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
gravitational/teleport#69785 ·
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
crossplane/crossplane#7859 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100