update-otel-genai-conventions

Update OTel Gen-AI Conventions

Analyze OpenTelemetry GenAI semantic-conventions changes — PRs, changelog snapshots, date ranges, or releases — primarily from open-telemetry/semantic-conventions-genai, and produce compensating updates in dotnet/extensions. See the Migration Note below for context, including where these conventions were previously managed.

Migration Note

The OpenTelemetry GenAI semantic conventions are maintained in a dedicated repo: open-telemetry/semantic-conventions-genai, which also hosts mcp, openai, anthropic, aws-bedrock, and azure-ai-inference conventions. They were previously managed in the consolidated open-telemetry/semantic-conventions repo under the area:gen-ai label.

Implications for this skill:

• Primary input source is semantic-conventions-genai. The consolidated semantic-conventions repo remains a fallback for catch-up audits, historical context, and any in-flight PR that started there previously.
• Every PR is in scope for consideration, because semantic-conventions-genai is specific to GenAI conventions. (In the consolidated semantic-conventions repo the area:gen-ai label scoped this work, and it still applies there for catch-up.) The repo does use more granular area:* labels (for example area:mcp, area:inference, area:tools, area:embeddings), which can help triage but are not required for scoping.
• No releases yet in semantic-conventions-genai. <!-- TODO: remove the "no releases yet" framing once semantic-conventions-genai ships its first release --> The repo manages its changelog with Towncrier: the CHANGELOG.md Unreleased section is intentionally empty (fragments are compiled into it only at release time), so the live "what's new" view is the set of news fragments under changelog.d/, each named <upstream-PR>.<type>.md (types include enhancement, bugfix, breaking, clarification). Pin a snapshot via commit SHA / ref for reproducible audits.
• GenAI version is now independent of core semconv: it tracks its own version line. The schema URL https://opentelemetry.io/schemas/gen-ai/X.Y.Z is intended to carry the gen-ai version, but is not published yet (the repo's README.md ## Schema URL section is TODO). The repo's versions.env holds only the core semconv dependency (SEMCONV_VERSION, currently v1.42.0) and the Weaver toolchain version — it does not carry the GenAI convention version, so do not treat SEMCONV_VERSION as the GenAI version. Until a GenAI release or schema URL exists, there is no published GenAI version number; identify the update by its changelog.d/ fragment snapshot, pinned to a commit SHA / ref / date.
• Spec URL https://opentelemetry.io/docs/specs/semconv/gen-ai/ currently resolves to a "Moved" stub that states the GenAI conventions have moved to semantic-conventions-genai and is no longer maintained; it no longer renders the spec content. The <see href> in dotnet/extensions source files still points at this URL, so leave it for now but revisit retargeting it once OpenTelemetry publishes a canonical URL for the conventions (the repo's README.md ## Schema URL section is currently TODO). <!-- TODO: once open-telemetry/semantic-conventions-genai publishes its canonical spec/schema URL, retarget the OpenTelemetry* doc-comment `<see href>` from the /docs/specs/semconv/gen-ai/ stub to that URL. -->
• PR numbering is not interchangeable across repos. Always disambiguate with open-telemetry/semantic-conventions#NNN or open-telemetry/semantic-conventions-genai#NNN when there is any risk of collision.
• Doc-comment wording in dotnet/extensions source still reads "Semantic Conventions for Generative AI systems v1.XX". The next convention-update PR should migrate this to "GenAI Semantic Conventions vX.Y.Z" — see references/file-inventory.md §Version References.

When a referenced PR number doesn't resolve in semantic-conventions-genai, check the consolidated semantic-conventions repo before assuming the input is invalid.

Cross-repo applicability

This skill lives in dotnet/extensions and its file paths, build commands, and PR-description conventions are tuned for that repo. The semantic-conventions-genai repo also hosts provider-specific areas (anthropic, aws-bedrock) whose dotnet instrumentation lives in other SDK repositories that we contribute to:

Upstream area	Repository	Notes
anthropic	anthropics/anthropic-sdk-csharp	Anthropic's official .NET SDK.
aws-bedrock	aws/aws-sdk-net	AWS Bedrock instrumentation lives in the BedrockRuntime service library (AWSSDK.BedrockRuntime) inside the AWS SDK monorepo.

The skill can optionally be applied in those repos with the following adaptations:

• Apply the convention analysis, classification framework (references/change-classification.md), audit-table shape, area routing, doc-comment wording target ("GenAI Semantic Conventions vX.Y.Z"), version-reference grep recipes, and PR-description shape (references/pr-description.md).
• Do not assume dotnet/extensions-specific paths (src/Libraries/Microsoft.Extensions.AI*/), the OpenTelemetryConsts.cs constants layout, the API-baseline workflow, or the build/test commands in references/build-commands.md. Use the target repo's own conventions for code structure, constants organization, and validation.
• Scope by repo: when running in another repo, the in-scope upstream area is the one that repo instruments (e.g. anthropic in anthropics/anthropic-sdk-csharp, aws-bedrock in the BedrockRuntime library of aws/aws-sdk-net). Other areas are out of scope from that repo's perspective even though they remain in scope for dotnet/extensions.
• Pre-flight still applies — search open PRs in the target repo for prior coverage before producing a plan.

Mode Detection

Determine the operating mode from the user's request:

Signal	Mode
User asks to "audit" current implementation or "check alignment" with conventions	Mode 1: Audit
User asks to "update for vX.Y" or "apply vX.Y changes" in autopilot / one-shot	Mode 2: Autopilot
User asks to "generate a prompt" or "delegate to Copilot" or "CCA prompt"	Mode 3: CCA Prompt
Running inside Copilot Coding Agent with a prompt referencing this skill	Mode 4: CCA Implementation
User is in /plan mode, asks to "plan" changes, or asks to "implement" / "apply" changes	Mode 5: Plan-then-Implement
User asks to /review or "review" convention changes	Mode 6: Review

If unclear, default to Mode 5 (Plan-then-Implement) and offer Mode 3 as an alternative.

Input Handling

semantic-conventions-genai does not yet publish releases. Until it does, the user typically provides one of:

• PR references in semantic-conventions-genai — full URL, #NNN, or open-telemetry/semantic-conventions-genai#NNN form. (No area: label filter is needed: the repo is gen-ai-focused by definition.)
• A changelog.d/ snapshot — a commit SHA, branch ref, or a https://github.com/open-telemetry/semantic-conventions-genai/tree/{ref}/changelog.d URL pinning the Towncrier news fragments at a point in time. (The CHANGELOG.md Unreleased section stays empty until release, so use the fragments — not CHANGELOG.md — for unreleased work.)
• A date range or "since last update" — list of PRs merged to semantic-conventions-genai's main between two refs / dates.
• A release version or release URL — once releases exist (https://github.com/open-telemetry/semantic-conventions-genai/releases/tag/{version}).

For catch-up or historical work, the consolidated semantic-conventions repo is still valid input:

• A semantic-conventions release version (e.g. v1.40.0) → fetch from https://github.com/open-telemetry/semantic-conventions/releases/tag/{version} (filter to area:gen-ai PRs).
• A release URL from semantic-conventions → fetch the release notes directly.
• PR references from semantic-conventions — only the ones with area:gen-ai. Use the open-telemetry/semantic-conventions#NNN form to disambiguate from semantic-conventions-genai PR numbers.

When PR numbers are given without a full URL, default to semantic-conventions-genai and fall back to the consolidated semantic-conventions repo only if the PR doesn't exist in semantic-conventions-genai or the user explicitly references it.

In-scope areas

The semantic-conventions-genai repo hosts conventions for several areas, all of which this skill covers (with placement guidance in references/implementation-patterns.md):

Upstream area	Maps to in dotnet/extensions
gen-ai, gen-ai/agent	Microsoft.Extensions.AI core (e.g. OpenTelemetryChatClient)
mcp	Currently no instrumentation; forward-looking — flag as a watch-list item if changes appear
openai	Microsoft.Extensions.AI.OpenAI
anthropic	Out of scope for dotnet/extensions today (no provider package). Implications land in anthropics/anthropic-sdk-csharp — apply this skill there per Cross-repo applicability.
aws-bedrock	Out of scope for `do

---

Content truncated.