Skip to content

Conversation

@chrisradek
Copy link
Member

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.txt is 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:

## Up-to-date TypeSpec documentation

Follow [typespec docs](../eng/common/instructions/azsdk-tools/typespec-docs.instructions.md) to get the most up-to-date documentation for TypeSpec, including best practices for writing TypeSpec for Azure.

Some of the sample prompts I tested with and verified:

Opened an existing TypeSpec file that wasn't using the @previewVersion decorator

Does this follow the guidelines for defining a preview version?

highlighting a data-plane operation

Explain what the highlighted template is doing

Have an existing TypeSpec file open_

How do I add a custom action for Trinkets - I want to have a "buy" action that will place an order for some quantity of trinkets

Highlighting a data plane operation_

I need to add a custom header to that operation - "X-Foo"

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 @previewVersion decorator whereas the non-llms.txt-backed agent did not know about it.

@chrisradek chrisradek requested a review from a team as a code owner September 11, 2025 19:28
Copilot AI review requested due to automatic review settings September 11, 2025 19:28
Copy link
Contributor

Copilot AI left a 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

@azure-sdk
Copy link
Collaborator

The following pipelines have been queued for testing:
java - template
java - template - tests
js - template
net - template
net - template - tests
python - template
python - template - tests
You can sign off on the approval gate to test the release stage of each pipeline.
See eng/common workflow

azure-sdk added a commit to Azure/azure-sdk-for-js that referenced this pull request Sep 11, 2025
azure-sdk added a commit to Azure/azure-sdk-for-rust that referenced this pull request Sep 11, 2025
@chrisradek chrisradek merged commit 3279670 into Azure:main Sep 11, 2025
9 checks passed
samvaity pushed a commit that referenced this pull request Sep 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants