Add spec-ingestion agent skill for TypeSpec ingestion workflow

[ShivangiReja]

Summary

[Local work only]

Adds a new agent skill at spec-ingestion that documents the full process for ingesting the latest OpenAI TypeSpec specification from upstream (microsoft/openai-openapi-pr) into the openai-dotnet SDK.

This skill is best suited for ingesting simple areas such as containers, images, embeddings, models, moderations..etc. It may still need some manual work but it will do most of the heavy lifting. More complex areas (e.g., responses, assistants, realtime) require manual work beyond what this skill covers.

This is intended as a living document — it should be updated as new areas are ingested, refining steps, adding new patterns, and capturing lessons learned to make the process smoother over time.

What's included

The skill is composed of 6 files:

File	Purpose
SKILL.md	Entry point with YAML frontmatter, overview, and key rules
steps.md	8-step workflow from copying the base spec to post-generation verification
file-locations.md	Quick reference for upstream and local paths, area mappings
patterns-and-gotchas.md	lessons learned from past ingestion PRs (#856, #888, #894, #913, #935)
checklist.md	Task checklist for tracking progress during an ingestion
references.md	Detailed notes on reference PRs with lessons learned

Key principles encoded

• Base spec immutability — base spec must be an exact copy of upstream, never modified
• Client TSP first, compile second — fix client TSP references before running npx tsp compile
• Clean dependencies — always delete node_modules and run npm install before compiling or generating
• @@clientLocation required — latest spec no longer uses interface blocks
• Local work only — the skill instructs Copilot to work locally and suggest issues rather than creating PRs or filing issues
• Discriminators over type unions — handle type unions in client models TSP, not by modifying the base spec

[christothes]

Should we define what area(s) mean in this context? For example, a specific API capability or client specific capability such as "Responses" or "Realtime".

[ShivangiReja]

The process starts from SKILL.md, which is the entry point that Copilot loads first. It already contains an Available Areas section listing all the areas (e.g., audio, containers, etc.), and file-locations.md has a full mapping table showing how each area maps to its base spec folder, client TSP file, and C# custom code folder.

By the time the agent reaches the checklist, it already has all that context from SKILL.md and the linked documents. The checklist is intentionally lightweight, it's a tracking tool, not meant to be read standalone. I kept the definitions in SKILL.md and file-locations.md to avoid duplicating info across files.

[christothes]

Can we add some more context about what this means? For example, do we mean errors with generation and then subsequent dot net bill after the generation generation is finished?

What does it mean to keep the clone?

[ShivangiReja]

"Keep the clone" means the temporary sparse checkout of microsoft/openai-openapi-pr that we create in Step 2. We keep it around because if TypeSpec compilation (via Invoke-CodeGen.ps1) shows missing types from common/, we need to look them up in the clone's src/common/ folder. Once compile succeeds and we don't need any more upstream files, we delete it. I'll clarify the wording.

[christothes]

We should define "compile" here.

[ShivangiReja]

"compile" here means running Invoke-CodeGen.ps1, which internally does npm ci → builds the codegen plugin → runs npx tsp compile .. I'll make that explicit.

[christothes]

Does the agent know what "as needed" means here?

[ShivangiReja]

Yes, the agent determines "as needed" from compile errors, if a decorator references a type/property that was renamed or removed upstream, the compile will fail with an error pointing to the broken reference. I'll reword to make the trigger explicit.

[christothes]

Should we define the criteria for "if applicable"?

[ShivangiReja]

A client models file exists only for areas that need discriminated union wrappers or .NET-specific model overrides. The criteria is: check if specification/client/models/{area}.models.tsp exists. If it does, update it if needed. If it doesn't, skip this step.

[christothes]

Where should these be listed or noted?

[ShivangiReja]

These should be listed in the final summary that the agent presents to the user at the end (the "Final Summary" section at the bottom of the checklist). The agent compiles these lists as it works through the steps and includes them in its output.

At the end it will give the summary about "What was done":

and "What changed":