OpenParable
Skip to content
← Back to skills

Ingesting Spec

Development
ingesting-spec

Ingesting Spec is an Agent Skill for development published in the openai/openai-dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for ingesting the latest OpenAI TypeSpec specification into the openai-dotnet SDK. Use this when asked to update or ingest OpenAI API specs, copy base TypeSpec files from upstream, fix client TSP compile errors, or run code generation for new API areas.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/openai/openai-dotnet/blob/HEAD/.github/skills/ingesting-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ingesting-spec, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

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

Skill Documents

This skill is split across multiple files for easier navigation:

DocumentDescription
steps.mdStep-by-step process — the full 9-step workflow from copying spec to post-generation verification
file-locations.mdKey file locations — quick reference for all upstream and local paths, area mappings
patterns-and-gotchas.mdCommon patterns & gotchas — lessons learned, pitfalls, and conventions to follow
checklist.mdChecklist — a task-by-task checklist for tracking progress during an ingestion
references.mdReference PRs — detailed notes on past ingestion PRs with lessons learned

Quick Start

  1. Review references.md for examples of past ingestions in your area
  2. Read file-locations.md to understand the repo layout
  3. Follow steps.md for the full ingestion workflow
  4. Use checklist.md to track your progress
  5. 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

  1. Always add @@clientLocation for every operation in the client TSP (the latest spec no longer uses interface blocks)
  2. NEVER modify the base spec — it must be an exact copy of upstream. Handle all issues (type unions, suppressions, etc.) in specification/client/ instead
  3. Update [CodeGenType] stubs in src/Custom/{Area}/Internal/GeneratorStubs.cs for any renamed types
  4. Defer complex features — suggest them as follow-up items rather than implementing in the same ingestion
  5. 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)
  6. Work locally only — do NOT create PRs or file issues. Instead, suggest a list of issues that may need to be filed upstream