Ingesting Spec Skill for Codex

Spec Ingestion

Overview

This skill describes how to ingest the latest OpenAI TypeSpec specification (from the upstream microsoft/openai-openapi-pr repository) into the openai-dotnet SDK, area by area.

The process involves:

• Copying updated base specs from upstream (exact copy, no modifications)
• Reporting any compile errors in the base TSP (do NOT fix — base spec must stay unmodified)
• Fixing compile errors in the client TSP layer
• Preserving custom C# code (renames, stubs)
• Running code generation
• Verifying the output

Skill Documents

This skill is split across multiple files for easier navigation:

| Document | Description |

|----------|-------------|

| steps.md | Step-by-step process — the full 9-step workflow from copying spec to post-generation verification |

| file-locations.md | Key file locations — quick reference for all upstream and local paths, area mappings |

| patterns-and-gotchas.md | Common patterns & gotchas — lessons learned, pitfalls, and conventions to follow |

| checklist.md | Checklist — a task-by-task checklist for tracking progress during an ingestion |

| references.md | Reference PRs — detailed notes on past ingestion PRs with lessons learned |

Quick Start

• Review references.md for examples of past ingestions in your area
• Read file-locations.md to understand the repo layout
• Follow steps.md for the full ingestion workflow
• Use checklist.md to track your progress
• Consult patterns-and-gotchas.md when you hit issues

Available Areas

Areas that can be ingested independently:

administration · assistants · audio · batch · chat · containers · conversations · embeddings · evals · files · fine-tuning · graders · images · models · moderations · realtime · responses · runs · threads · vector-stores · videos

Key Rules

• Always add @@clientLocation for every operation in the client TSP (the latest spec no longer uses interface blocks)
• NEVER modify the base spec — it must be an exact copy of upstream. Handle all issues (type unions, suppressions, etc.) in specification/client/ instead
• Update [CodeGenType] stubs in src/Custom/{Area}/Internal/GeneratorStubs.cs for any renamed types
• Defer complex features — suggest them as follow-up items rather than implementing in the same ingestion
• Run ./scripts/Invoke-CodeGen.ps1 to generate code (warnings are OK. Errors are not), then dotnet build to verify (Should be no warnings or errors)
• Work locally only — do NOT create PRs or file issues. Instead, suggest a list of issues that may need to be filed upstream