Add custom instructions to fetch TypeSpec docs#12049
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds custom instructions for GitHub Copilot to fetch up-to-date TypeSpec documentation using llms.txt files. The instructions provide direct links to AI-friendly documentation that helps Copilot give more accurate TypeSpec guidance.
- Adds structured instructions referencing TypeSpec Azure and core TypeSpec documentation via llms.txt endpoints
- Provides specific guidance for when to fetch different types of TypeSpec documentation
- Enables more accurate AI responses for TypeSpec-related questions with fewer tokens
Collaborator
|
The following pipelines have been queued for testing: |
maririos
approved these changes
Sep 11, 2025
This was referenced Sep 11, 2025
azure-sdk
added a commit
to Azure/azure-sdk-for-js
that referenced
this pull request
Sep 11, 2025
Sync eng/common directory with azure-sdk-tools for PR Azure/azure-sdk-tools#12049 See [eng/common workflow](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/README.md#workflow) Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
azure-sdk
added a commit
to Azure/azure-sdk-for-rust
that referenced
this pull request
Sep 11, 2025
Sync eng/common directory with azure-sdk-tools for PR Azure/azure-sdk-tools#12049 See [eng/common workflow](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/README.md#workflow) Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
samvaity
pushed a commit
that referenced
this pull request
Sep 11, 2025
Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We're now generating llms.txt files for TypeSpec/TypeSpec Azure doc sites which gives more "AI-friendly" versions of our docs in markdown format vs the HTML pages for the rest of us 😄
I originally planned to add MCP tools to surface these docs (#12007), but found that using these instructions - and referencing them from copilot-instructions, will follow up in azure-rest-api-specs - worked at least as well as the MCP tools for getting the correct docs into the LLM context. Since
llms.txtis more granular than the llms-full.txt files, in testing I saw copilot be much more surgical in which docs it fetched - resulting in fewer tokens required to get relevant typespec docs. You also get the benefit of seeing exactly which doc pages the agent fetches.I'll also add the following markdown to the azure-rest-api-specs copilot-instructions.md to make sure these instructions are pulled in - this has worked well in testing:
Some of the sample prompts I tested with and verified:
Opened an existing TypeSpec file that wasn't using the
@previewVersiondecoratorhighlighting a data-plane operation
Have an existing TypeSpec file open_
Highlighting a data plane operation_
Interesting findings
I tested all my prompts in both a copy of the specs repo with these instructions, and one without. For most of the prompts, the AI-generated TypeSpec code ended up being nearly the same. However the explanations for the version using these instructions (and pulling down llms.txt) were much more accurate. In all the explanations of what an HTTP request/response would actually look like from the version without these instructions, the AI was confident, but verifiably wrong. These errors were subtle because they sounded reasonable: names of LRO headers, 202 vs 201 status codes, action paths that were off by a character - all wrong if you looked at the emitted swagger files. The llms.txt-backed AI got them right.
The llms.txt-backed agent also did better for newer, less-frequently used features. For example, it was able to look up documentation on the
@previewVersiondecorator whereas the non-llms.txt-backed agent did not know about it.