> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use AI coding agents with the GDK

> Give AI coding agents accurate, version-matched Microsoft Game Development Kit (GDK) context: the docs MCP server, offline Markdown documentation, installed headers, command-line tools, and a project instruction file.

AI coding agents, such as GitHub Copilot, Claude Code, Codex, and Cursor, write better GDK code when they work from the APIs and documentation of the GDK you build with, instead of from what their model remembers. This article describes the GDK context you can give an agent and how to set up each source.

This guidance applies to the Microsoft Game Development Kit (GDK) and the Microsoft GDK with XBOX Extensions (GDKX) on a Windows PC development computer.

## Before you begin

* Install the GDK. The examples use the October 2026 GDK (edition `261000`). Replace `261000` with the edition your game builds with.
* Use an agent that can connect to a Model Context Protocol (MCP) server, read files on your computer, or run commands. Most coding agents can do all three.
* Find out which AI tools your organization approves for confidential content. GDKX documentation, headers, and tools are confidential.

## Choose the GDK context to give the agent

| Source | What the agent gets | Version | Access |
| - | - | - | - |
| XBOX docs MCP server | Search and retrieval over the published XBOX docs | Current online docs | Public |
| `llms.txt`, `llms-full.txt`, and Markdown pages | An index of every page, the full text of the docs, or one page as Markdown | Current online docs | Public |
| Offline Markdown documentation | The GDK documentation as Markdown files | Matches the installed GDK | Public and confidential pages |
| Installed headers | Exact declarations, and doc comments in some headers | Matches the installed GDK | Matches the GDK you installed |
| Command-line tools | Usage text and error descriptions from the tools themselves | Matches the installed GDK | Matches the GDK you installed |
| [XBOX GDK samples](https://github.com/microsoft/Xbox-GDK-Samples) | Complete, buildable examples | Tagged by GDK release | Public |

The online sources describe the current GDK. When you build with an earlier GDK, give the agent the installed headers and the offline documentation too, so it doesn't use APIs that your GDK doesn't have.

## Connect the XBOX docs MCP server

The XBOX docs MCP server at `https://docs.xbox.com/mcp` lets an agent search and cite the published docs. It doesn't need an API key or sign-in. For example, in Visual Studio Code, add the server to a `.vscode/mcp.json` file in your project:

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "xbox-docs": {
      "type": "http",
      "url": "https://docs.xbox.com/mcp"
    }
  }
}
```

For the setup steps for Claude Code, GitHub Copilot CLI, Cursor, Codex, and Claude, see [Use these docs with AI tools](https://docs.xbox.com/index.md#xbox-home-ai-title) on the home page.

Agents that can't use MCP can read the docs in other formats:

* `https://docs.xbox.com/llms.txt` lists every page with a short description.
* `https://docs.xbox.com/llms-full.txt` contains the full text of the docs in one file.
* Add `.md` to the end of any page URL to get that page as Markdown.

## Give the agent the offline documentation

The GDKX installs the GDK documentation as Markdown files in `GDKDocumentationMarkdown.zip`, in the `xbox\documentation` folder of the GDK edition. Because the files match the GDK you installed, they're the most accurate documentation source for that version.

Each page starts with YAML frontmatter. The `permissioned-type` value gives the page's access classification: `public`, `private`, or `secret`. The `site-map.md` file at the root of the archive lists the pages.

> [!WARNING]
>
> The archive contains confidential pages. Use the full archive only with AI tools that your organization approves for confidential GDKX content. Don't add the extracted files to a public repository or to any location that people outside your organization can read.

1. Extract the archive to a folder outside your source repository. In PowerShell, run the following commands.

   ```powershell theme={null}
   $edition = '261000'
   $zip  = Join-Path $env:GameDK "$edition\xbox\documentation\GDKDocumentationMarkdown.zip"
   $dest = "$env:USERPROFILE\gdk-docs\$edition"
   Expand-Archive -Path $zip -DestinationPath $dest
   ```

2. If your AI tool isn't approved for confidential content, keep only the public pages. The following command deletes every Markdown file whose `permissioned-type` isn't `public`, including files that don't have the field.

   ```powershell theme={null}
   Get-ChildItem $dest -Recurse -Filter *.md |
     Where-Object { -not (Get-Content $_.FullName -TotalCount 25 |
       Select-String -Quiet '^permissioned-type:\s*public\s*$') } |
     Remove-Item
   ```

3. Give the agent access to the folder. For example, add it to your editor's workspace, or name it in your project instruction file.

Extract the archive again for each GDK edition you install, into a folder named for that edition.

## Point the agent at the installed headers and tools

The GDK installer sets environment variables that give the agent the installed GDK's location:

* `GameDK` is the GDK root folder. It contains the `bin` folder of command-line tools and a folder for each installed edition, such as `%GameDK%261000\`.
* `GameDKCoreLatest` and `GameDKXboxLatest` point to the most recent installed edition.

When more than one edition is installed side by side, the most recent edition might not be the one your game builds with. Give the agent the edition folder your game uses, such as `%GameDK%261000\`, instead of these variables.

For the folders under each edition, see [GDK header and library directory structure](https://docs.xbox.com/build/gdk-and-engines/guides/gdk-directory-structure.md). Tell the agent to check declarations in the headers under the edition's `windows\include` folder for PC, or its `xbox\include` folder for XBOX consoles, before it uses an API. Some headers, such as the XBOX services API (XSAPI), libHttpClient, and PlayFab headers, also include doc comments that describe each API.

The command-line tools in `%GameDK%bin` print their usage when you run them with `/?`. An agent can run a tool's `/?` before it uses the tool, instead of guessing its options. To translate an `HRESULT` into a description, use `xberror.exe`:

```cmd theme={null}
"%GameDK%bin\xberror.exe" 0x8015DC12
```

## Give the agent version-matched sample code

Use the [XBOX GDK sample list](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/gdk-samples-list.md) to find examples of the feature you're implementing. Check the repository and sample READMEs for GDK version, directory layout, and platform requirements. If the main branch doesn't match your project, choose a compatible [sample release](https://github.com/microsoft/Xbox-GDK-Samples/releases).

Clone or download the compatible release and give the agent the local paths to the relevant sample's source and README. Ask it to follow the sample's initialization, error handling, asynchronous lifetime, and cleanup patterns. Have the agent verify APIs against your installed headers rather than copying project settings from a different GDK layout.

## Let the agent build from the command line

To build, an agent needs the same environment as a Gaming Command Prompt. Run `GamingDesktopVars.cmd` with the arguments that the Start menu shortcut uses, and then run the build in the same `cmd` process:

```cmd theme={null}
cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 261000 && msbuild MyGame.sln /p:Configuration=Debug /p:Platform=Gaming.Desktop.x64"
```

Use `GamingDesktopVS2022` for Visual Studio 2022. The environment doesn't carry over between separate commands, so the agent must run the script and the build together.

## Add a project instruction file

Most coding agents read a project instruction file, such as `AGENTS.md` or `.github/copilot-instructions.md`, at the root of your repository. Use it to give every agent session the same GDK context. Start from the following example, and replace the values in angle brackets.

```markdown AGENTS.md theme={null}
# GDK project instructions

- This game uses the Microsoft Game Development Kit (GDK) <edition, for example 261000 (October 2026)>.
  Target platforms: <Gaming.Desktop.x64, Gaming.Xbox.Scarlett.x64>.
- Before you use a GDK API, check its declaration in the headers of this edition:
  %GameDK%<edition>\windows\include for PC and %GameDK%<edition>\xbox\include for XBOX consoles.
  Don't use an API that the headers for the target platform don't declare.
- Search the XBOX docs with the xbox-docs MCP server. For the documentation of this GDK
  edition, read the Markdown files in <%USERPROFILE%\gdk-docs\261000>.
- Use the sample source and README in <local path to a compatible XBOX GDK sample>.
  Check its GDK version, directory layout, and platform requirements before adapting code.
- Build: cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 <edition> && msbuild <solution> /p:Platform=Gaming.Desktop.x64"
- Run a GDK tool with /? before you use it. Translate HRESULT values with xberror.
- Before handing back a change, review the diff for correctness and unintended changes.
  Run the build and relevant tests. Report the commands, results, and anything you couldn't verify.
- Don't copy confidential GDKX content into public files or into tools that aren't approved for it.
```

## Review the agent's work

Before you review a change, ask the agent to self-review its work. For example, give it this prompt:

```text theme={null}
Review your diff against the task and project instructions before handing it back.
Check HRESULT handling, asynchronous completion or cancellation, resource cleanup,
and API availability in the installed GDK edition for each target platform.
Look for unintended behavior changes and missing tests for the changed behavior.
Fix the issues you find, then run the build and relevant tests for the affected targets.
Report remaining concerns, the exact commands and results, and anything you couldn't verify.
Don't claim a build, test, or platform check passed unless you ran it successfully.
```

Self-review doesn't replace your review. Review and test agent-written code as you would any other code. Verify claims about platform support, policies, and certification requirements in the docs, not in the agent's answer.

## See also

* [GDK header and library directory structure](https://docs.xbox.com/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [Starting development of a new title using GDK project templates](https://docs.xbox.com/build/gdk-and-engines/guides/gdk-project-templates.md)
* [XBOX GDK samples on GitHub](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [What's new in the Microsoft Game Development Kit (GDK)](https://docs.xbox.com/announcements/gdk/whats-new.md)
- [Build and run your first console title with GDKX](https://docs.xbox.com/home/build-first-title/first-console-title-walkthrough.md)
- [XBOX Game Development](https://docs.xbox.com/index.md)
- [Initializing the GDK](https://docs.xbox.com/build/steam-porting-guide/initializing-the-gdk.md)
- [Use the GDK with Unity, Unreal, and other engines](https://docs.xbox.com/build/gdk-and-engines/gdk-and-engines.md)
