ai-docs-generate

name	ai-docs-generate
description	Generate WDK DDI API reference documentation pages from source code and stubs. Use when: writing API docs, generating reference pages, documenting a header, creating DDI documentation.
argument-hint	Specify a header name (e.g. soundwireclass) and the path to the CSV file.

Generate API Docs

Generate complete API reference documentation pages for WDK DDI entities by combining stub files, OS source code declarations, and supplemental information from published docs.

No local repo clones required. All repo interactions use the Azure DevOps REST API. OS source lookups use the substrate-mcp MCP server.

Parameters

Parameter	Value
ADO Org	https://dev.azure.com/cpubwin
ADO Project	drivers
Docs Repo	wdk-ddi (branches: main, stubs/main)
Published Docs Repo	windows-driver-docs-ddi (branch: staging)
Content Path	wdk-ddi-src/content/{header}/
Stubs Branch	stubs/main (default; user may specify alternate)
Header Name	Provided by the user (without .h extension for path operations)
CSV Path	Provided by the user at any local path (e.g. D:\work\soundwireclass.csv)
Working Directory	Derived from CSV path (parent folder of the CSV file)
Output Path	{working_dir}\output\
Style Guide	Read remotely from wdk-ddi repo: .github/copilot-instructions.md on main

Prerequisites

• The user provides a header name and a path to a CSV file (pre-provided or from the ai-docs-inventory skill). That is the only user requirement.
• The substrate-mcp MCP server must be accessible for source code retrieval
• The microsoft.docs.mcp MCP server should be accessible for supplemental info (non-fatal if unavailable)
• Azure CLI (az) should be available for auth token acquisition. If not, the agent will prompt for an ADO Personal Access Token (PAT) once per session.

Procedure

1. Strip the .h extension from the user-provided header name to get {header} (e.g. soundwireclass.h → soundwireclass).

2. Resolve paths. The user provides a CSV path. Derive the working directory from it:

   $csvPath = "{user-provided CSV path}"
   if (-not (Test-Path $csvPath)) {
       Write-Error "CSV not found at $csvPath. Please provide the CSV file first."
       return
   }
   $workingDir = Split-Path $csvPath -Parent
   $outputDir = Join-Path $workingDir "output"
   Import-Csv $csvPath
   

   If the CSV does not exist, inform the user and stop.

3. Obtain ADO auth token. Try Azure CLI first, then fall back to prompting for a PAT:

   try {
       $token = (az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv 2>$null)
       if (-not $token) { throw "No token" }
       $headers = @{ Authorization = "Bearer $token" }
   } catch {
       $pat = Read-Host "Enter ADO PAT (scope: Code Read)"
       $base64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat"))
       $headers = @{ Authorization = "Basic $base64" }
   }
   $adoBase = "https://dev.azure.com/cpubwin/drivers/_apis/git/repositories"
   

4. Read the style guide remotely from the wdk-ddi repo to ensure all formatting rules are followed:

   $styleGuide = Invoke-RestMethod -Uri "$adoBase/wdk-ddi/items?path=.github/copilot-instructions.md&versionDescriptor.version=main&versionDescriptor.versionType=branch&api-version=7.0" -Headers $headers
   

5. Parse the CSV file to get the list of target filenames. The CSV has a header row and one filename column with paths like wdk-ddi-src/content/{header}/{filename}.md.

6. Create the output directory if it doesn't exist; if it does, clear it:

   if (Test-Path $outputDir) {
       Remove-Item "$outputDir\*" -Force -ErrorAction SilentlyContinue
   } else {
       New-Item -ItemType Directory -Path $outputDir -Force | Out-Null
   }
   

7. For each target file listed in the CSV, skip index.md (the header landing page is handled separately in step 8).

   For each remaining target file:

   a. Get the stub or existing file

   Use the ADO REST API to check if the file already exists on main:

   # List files on main branch
   $mainFiles = Invoke-RestMethod -Uri "$adoBase/wdk-ddi/items?scopePath=wdk-ddi-src/content/{header}/&recursionLevel=OneLevel&versionDescriptor.version=main&versionDescriptor.versionType=branch&api-version=7.0" -Headers $headers
   

• List of all generated/updated files in {outputDir}
• For each file, show the first 20 lines (frontmatter + description) as a sample
• Highlight any metadata fields marked as TODO that the user should fill in manually (e.g. req.lib, req.dll, req.irql if not determinable from source)
• Prompt the user to review the markdown files at: {outputDir}

11. Continue or stop. Ask the user:

    Docs generated and ready for review in {outputDir}. Please review the files before proceeding — once submitted, a PR will be created in the wdk-ddi repo. Press y to submit them as a PR, or type n to stop and review further.

    • If the user types y: automatically invoke the ai-docs-submit skill, passing the same header name. Behave as if the user typed /ai-docs-submit {header}.
    • If the user types n: stop and tell them they can run it later with: /ai-docs-submit {header}

    Tip: To run all three steps (inventory → generate → submit) with no interaction, use the ai-docs-autopilot skill instead.