Before you begin
- Install the GDK. The examples use the October 2026 GDK (edition
261000). Replace261000with 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
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 athttps://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:
.vscode/mcp.json
https://docs.xbox.com/llms.txtlists every page with a short description.https://docs.xbox.com/llms-full.txtcontains the full text of the docs in one file.- Add
.mdto 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 inGDKDocumentationMarkdown.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.
-
Extract the archive to a folder outside your source repository. In PowerShell, run the following commands.
-
If your AI tool isn’t approved for confidential content, keep only the public pages. The following command deletes every Markdown file whose
permissioned-typeisn’tpublic, including files that don’t have the field. - Give the agent access to the folder. For example, add it to your editor’s workspace, or name it in your project instruction file.
Point the agent at the installed headers and tools
The GDK installer sets environment variables that give the agent the installed GDK’s location:GameDKis the GDK root folder. It contains thebinfolder of command-line tools and a folder for each installed edition, such as%GameDK%261000\.GameDKCoreLatestandGameDKXboxLatestpoint to the most recent installed edition.
%GameDK%261000\, instead of these variables.
For the folders under each edition, see GDK header and library directory structure. 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:
Give the agent version-matched sample code
Use the XBOX GDK sample list 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. 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. RunGamingDesktopVars.cmd with the arguments that the Start menu shortcut uses, and then run the build in the same cmd process:
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 asAGENTS.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.
AGENTS.md
