- 
                Notifications
    You must be signed in to change notification settings 
- Fork 216
Add custom instructions to fetch TypeSpec docs #12049
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
| The following pipelines have been queued for testing: | 
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 <[email protected]>
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 <[email protected]>
Co-authored-by: Christopher Radek <[email protected]>
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.