chore: add agent skills for product usage and maintenance [no-ci] (#401)

* chore: add agent skills for product usage and maintenance

Add 8 agent-agnostic skills under .agents/skills/ following the
skills.sh convention (discoverable by OpenCode, Claude Code, Codex,
Cursor, and 40+ other agent tools via `npx skills`).

Product usage skills (7):
- using-speech-to-text        — /v1/listen REST + WSS
- using-text-to-speech        — /v1/speak REST + WSS
- using-text-intelligence     — /v1/read REST
- using-audio-intelligence    — /v1/listen analytics overlays
- using-voice-agent           — agent.deepgram.com/v1/agent/converse WSS
- using-conversational-stt    — /v2/listen Flux WSS
- using-management-api        — manage.v1.* + voice_agent.configurations

Maintainer skill (1):
- maintaining-dotnet-sdk      — C#/.NET SDK maintenance workflow

Each skill includes authentication, quick-start with real C#/.NET code
from examples/, key parameters, layered API references (in-repo,
OpenAPI, AsyncAPI, Context7, product docs), gotchas, and sibling-skill
routing.

* docs: cross-reference deepgram/skills for central product knowledge

Each product skill now points back to the `deepgram/skills` repo for the
consolidated API reference, documentation finder, runnable recipes,
third-party integration examples, and MCP setup. This SDK's skills
stay language-idiomatic; the central skills stay cross-language.

* chore: namespace skill names with deepgram-dotnet- prefix

Rename all 8 skill folders (and frontmatter `name` fields and
sibling-skill cross-references) to avoid collisions when a user
installs skills from multiple Deepgram SDK repos.

Old → new:
  using-speech-to-text     → deepgram-dotnet-speech-to-text
  using-text-to-speech     → deepgram-dotnet-text-to-speech
  using-text-intelligence  → deepgram-dotnet-text-intelligence
  using-audio-intelligence → deepgram-dotnet-audio-intelligence
  using-voice-agent        → deepgram-dotnet-voice-agent
  using-conversational-stt → deepgram-dotnet-conversational-stt
  using-management-api     → deepgram-dotnet-management-api
  maintaining-dotnet-sdk       → deepgram-dotnet-maintaining-sdk

Previously each SDK published identically-named product skills
(e.g. every SDK had `using-speech-to-text`), so installing skills
from two SDKs would overwrite the first. The `deepgram-` prefix
makes the vendor+language explicit and the names globally unique.

* docs: write streaming audio to .raw not .wav (Copilot feedback)

WebSocket audio frames from Voice Agent and streaming Speak are raw
linear16 PCM with no WAV container. Appending them to a .wav file
produces an invalid WAV (header missing, sample-rate/channel metadata
absent). Switched both examples to write .raw files, matching the
pattern used in examples/agent/websocket/no_mic/Program.cs and
examples/text-to-speech/websocket/simple/Program.cs. Added an inline
comment documenting the two valid options (save raw, or prepend a
WAV header).

* docs: document ClientFactory credential sources (Copilot feedback)

All 5 Dotnet auth snippets now explain that ClientFactory reads credentials
from the DEEPGRAM_API_KEY / DEEPGRAM_ACCESS_TOKEN env vars by default, and
show how to pass them explicitly via the apiKey:/accessToken: parameter.
DeepgramHttpClientOptions / DeepgramWsClientOptions throw if neither source
is available, so users pasting the snippet needed to know where credentials
come from.

Affected skills: audio-intelligence, conversational-stt, voice-agent,
text-intelligence, management-api.

Author: lukeocodes

.agents/skills/deepgram-dotnet-audio-intelligence/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: deepgram-dotnet-audio-intelligence
+description: Use when writing or reviewing C# code in this repo that enables Deepgram intelligence overlays on Speech-to-Text requests. Covers `PreRecordedSchema` analytics flags such as `Summarize`, `Topics`, `Intents`, `Sentiment`, `DetectLanguage`, `DetectEntities`, `Diarize`, and `Redact`, plus the smaller live-streaming subset on `LiveSchema`. Use `deepgram-dotnet-speech-to-text` for plain transcription and `deepgram-dotnet-text-intelligence` for analytics on already-transcribed text.
+---
+
+# Using Deepgram Audio Intelligence (.NET SDK)
+
+Audio analytics live on top of the same STT clients. Turn features on through schema properties.
+
+## When to use this product
+
+- You have audio and want transcript + analytics in one request.
+- REST is the main path for summaries, topics, intents, sentiment, and language detection.
+
+**Use a different skill when:**
+- You only need transcript text → `deepgram-dotnet-speech-to-text`.
+- You already have text and want `/read` → `deepgram-dotnet-text-intelligence`.
+
+## Authentication
+
+```bash
+dotnet add package Deepgram
+```
+
+```csharp
+using Deepgram;
+
+Library.Initialize();
+var client = ClientFactory.CreateListenRESTClient();
+```
+
+`ClientFactory` reads credentials from the `DEEPGRAM_API_KEY` (or `DEEPGRAM_ACCESS_TOKEN`) environment variable by default. To pass them explicitly, use `ClientFactory.CreateListenRESTClient(apiKey: "...", options: ...)` / `CreateListenWebSocketClient(apiKey: "...", options: ...)`. `DeepgramHttpClientOptions` / `DeepgramWsClientOptions` throw if neither the env var nor an explicit credential is provided.
+
+## Feature availability: REST vs WebSocket
+
+| Feature | REST (`PreRecordedSchema`) | WebSocket (`LiveSchema`) |
+|---|---|---|
+| `Diarize` | yes | yes |
+| `Redact` | yes | yes |
+| `DetectEntities` | yes | not surfaced in `LiveSchema` |
+| `Summarize` | yes (`string`) | no |
+| `Topics` / `Intents` / `Sentiment` | yes | no |
+| `DetectLanguage` | yes | no |
+| `CustomTopic` / `CustomIntent` | yes | no |
+
+## Quick start — REST
+
+```csharp
+using Deepgram.Models.Listen.v1.REST;
+
+var client = ClientFactory.CreateListenRESTClient();
+
+var response = await client.TranscribeUrl(
+    new UrlSource("https://dpgr.am/spacewalk.wav"),
+    new PreRecordedSchema()
+    {
+        Model = "nova-3",
+        Punctuate = true,
+        SmartFormat = true,
+        Diarize = true,
+        Summarize = "v2",
+        Topics = true,
+        Intents = true,
+        Sentiment = true,
+        DetectLanguage = true,
+        DetectEntities = true,
+        Redact = new List<string> { "pii", "numbers" },
+        Language = "en",
+    });
+
+Console.WriteLine(response.Results.Channels[0].Alternatives[0].Transcript);
+Console.WriteLine(response.Results.Summary);
+```
+
+## Quick start — live subset
+
+```csharp
+using Deepgram.Models.Listen.v2.WebSocket;
+
+var liveClient = ClientFactory.CreateListenWebSocketClient();
+
+await liveClient.Subscribe(new EventHandler<ResultResponse>((sender, e) =>
+{
+    Console.WriteLine(e.Channel.Alternatives[0].Transcript);
+}));
+
+await liveClient.Connect(new LiveSchema()
+{
+    Model = "nova-3",
+    Diarize = true,
+    Redact = new List<string> { "pii" },
+    Encoding = "linear16",
+    SampleRate = 16000,
+});
+```
+
+## Key params
+
+REST (`PreRecordedSchema`): `Summarize`, `Topics`, `Intents`, `Sentiment`, `DetectLanguage`, `DetectEntities`, `CustomTopic`, `CustomTopicMode`, `CustomIntent`, `CustomIntentMode`, `Diarize`, `DiarizeVersion`, `Redact`, `Utterances`, plus the regular STT knobs.
+
+Live (`LiveSchema`): `Diarize`, `Redact`, `UtteranceEnd`, `VadEvents`, `Punctuate`, `SmartFormat`, plus normal streaming STT settings.
+
+## API reference (layered)
+
+1. **In-repo source of truth**:
+   - `Deepgram/Models/Listen/v1/REST/PreRecordedSchema.cs`
+   - `Deepgram/Models/Listen/v2/WebSocket/LiveSchema.cs`
+   - `Deepgram/Clients/Listen/v1/REST/Client.cs`
+   - `Deepgram/Clients/Listen/v2/WebSocket/Client.cs`
+2. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml
+3. **Canonical AsyncAPI (streaming / WSS)**: https://developers.deepgram.com/asyncapi.yaml
+4. **Context7**:
+   - repo mirror: `https://context7.com/deepgram/deepgram-dotnet-sdk`
+   - docs corpus: `/llmstxt/developers_deepgram_llms_txt`
+5. **Product docs**:
+   - https://developers.deepgram.com/docs/stt-intelligence-feature-overview
+   - https://developers.deepgram.com/docs/summarization
+   - https://developers.deepgram.com/docs/topic-detection
+   - https://developers.deepgram.com/docs/intent-recognition
+   - https://developers.deepgram.com/docs/sentiment-analysis
+   - https://developers.deepgram.com/docs/language-detection
+   - https://developers.deepgram.com/docs/redaction
+   - https://developers.deepgram.com/docs/diarization
+
+## Gotchas
+
+1. **`Summarize` on STT is a string.** Use `Summarize = "v2"`, not `true`.
+2. **Most intelligence overlays are REST-only.** The live schema does not expose summary/topic/intent/sentiment/language options.
+3. **Redaction is a `List<string>`.** This SDK does not expose the Python-style union of string-or-array.
+4. **Custom topics and intents need modes.** Set `CustomTopicMode` / `CustomIntentMode` or the model behavior will not match expectations.
+5. **Diarization is available in both paths, but the event shapes differ.** Live results expose speaker data word-by-word in streaming responses.
+
+## Example files in this repo
+
+- `examples/speech-to-text/rest/summary/Program.cs`
+- `examples/speech-to-text/rest/sentiment/Program.cs`
+- `examples/speech-to-text/rest/topic/Program.cs`
+- `examples/speech-to-text/rest/intent/Program.cs`
+- `examples/speech-to-text/rest/file/Program.cs`
+
+## Central product skills
+
+For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:
+
+```bash
+npx skills add deepgram/skills
+```
+
+This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).

.agents/skills/deepgram-dotnet-conversational-stt/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: deepgram-dotnet-conversational-stt
+description: Use when evaluating or extending conversational / Flux-style streaming STT support in this C# SDK. The repo has a latest WebSocket listen client under `Deepgram.Models.Listen.v2.WebSocket`, but it does not currently expose Flux-specific request params or turn-aware response types like `TurnInfo`. Use this skill to document that gap honestly and to guide work on the closest supported surface.
+---
+
+# Using Deepgram Conversational STT / Flux (.NET SDK)
+
+This repo does **not** currently expose a dedicated Flux / conversational STT API surface comparable to the Python SDK's `listen.v2.connect(...)` + `TurnInfo` flow.
+
+## When to use this product
+
+- Use this skill when someone asks for **Flux**, **conversational STT**, **turn-taking**, or `/v2/listen` support in the .NET SDK.
+- Use it when deciding whether the current `Listen.v2.WebSocket` client is sufficient for the task.
+
+**Use a different skill when:**
+- You only need standard streaming transcription with `ResultResponse`, `SpeechStartedResponse`, and `UtteranceEndResponse` → `deepgram-dotnet-speech-to-text`.
+- You need a full voice assistant instead of transcription-only → `deepgram-dotnet-voice-agent`.
+
+## Current repo status
+
+What exists:
+- `ClientFactory.CreateListenWebSocketClient()` returns the latest WebSocket listen client.
+- Request model: `Deepgram.Models.Listen.v2.WebSocket.LiveSchema`.
+- Event models: `OpenResponse`, `MetadataResponse`, `ResultResponse`, `SpeechStartedResponse`, `UtteranceEndResponse`, `CloseResponse`, `ErrorResponse`, `UnhandledResponse`.
+- Control helpers: `SendKeepAlive()`, `SendFinalize()`, `SendClose()`, `Send(...)`.
+
+What is **not** present in the current repo search:
+- No `flux` model constants or examples.
+- No `TurnInfo` / turn-aware event models.
+- No `language_hint`, `eager_eot_threshold`, `eot_threshold`, or similar Flux request properties.
+- No README/examples that mention conversational STT explicitly.
+
+## Authentication
+
+```bash
+dotnet add package Deepgram
+```
+
+```csharp
+using Deepgram;
+
+Library.Initialize();
+var client = ClientFactory.CreateListenWebSocketClient();
+```
+
+`ClientFactory` reads credentials from the `DEEPGRAM_API_KEY` (or `DEEPGRAM_ACCESS_TOKEN`) environment variable by default. To pass them explicitly: `ClientFactory.CreateListenWebSocketClient(apiKey: "...", options: ...)`. `DeepgramWsClientOptions` throws if neither the env var nor an explicit credential is provided.
+
+## Closest supported code path today
+
+```csharp
+using Deepgram.Models.Listen.v2.WebSocket;
+
+var liveClient = ClientFactory.CreateListenWebSocketClient();
+
+await liveClient.Subscribe(new EventHandler<ResultResponse>((sender, e) =>
+{
+    var transcript = e.Channel.Alternatives[0].Transcript;
+    if (!string.IsNullOrWhiteSpace(transcript))
+    {
+        Console.WriteLine(transcript);
+    }
+}));
+
+await liveClient.Subscribe(new EventHandler<UtteranceEndResponse>((sender, e) =>
+{
+    Console.WriteLine(e.Type);
+}));
+
+await liveClient.Connect(new LiveSchema()
+{
+    Model = "nova-3",
+    Encoding = "linear16",
+    SampleRate = 16000,
+    InterimResults = true,
+    UtteranceEnd = "1000",
+    VadEvents = true,
+});
+```
+
+Treat this as **standard live STT**, not true Flux parity.
+
+## Key params currently available
+
+On `LiveSchema`: `Model`, `Encoding`, `SampleRate`, `InterimResults`, `UtteranceEnd`, `VadEvents`, `Endpointing`, `NoDelay`, `Punctuate`, `SmartFormat`, `Keywords`, `Keyterm`, `Diarize`, `Redact`.
+
+## API reference (layered)
+
+1. **In-repo source of truth**:
+   - `Deepgram/ClientFactory.cs`
+   - `Deepgram/Clients/Listen/v2/WebSocket/Client.cs`
+   - `Deepgram/Models/Listen/v2/WebSocket/LiveSchema.cs`
+   - `Deepgram/Models/Listen/v2/WebSocket/*.cs`
+2. **Canonical OpenAPI**: not the primary reference for this streaming gap
+3. **Canonical AsyncAPI (what the product can support, even if this SDK is incomplete)**: https://developers.deepgram.com/asyncapi.yaml
+4. **Context7**:
+   - repo mirror: `https://context7.com/deepgram/deepgram-dotnet-sdk`
+   - docs corpus: `/llmstxt/developers_deepgram_llms_txt`
+5. **Product docs**:
+   - https://developers.deepgram.com/reference/speech-to-text/listen-flux
+   - https://developers.deepgram.com/docs/flux/quickstart
+   - https://developers.deepgram.com/docs/flux/language-prompting
+
+## Gotchas
+
+1. **Be honest: Flux is not first-class here yet.** Do not invent `TurnInfo`-style .NET models or `ConnectFluxAsync(...)` helpers.
+2. **The repo's `Listen.v2.WebSocket` naming is misleading if you expect Python parity.** It is the newest streaming client, but not a full conversational surface.
+3. **Default API version still resolves from shared options.** `DeepgramWsClientOptions` defaults `APIVersion` to `v1`, so inspect connection URIs before assuming `/v2/listen` behavior.
+4. **If the task requires real Flux parity, start by adding models, request params, examples, and tests.** Do not paper over the gap in docs or code.
+
+## Example files in this repo
+
+- `examples/speech-to-text/websocket/file/Program.cs`
+- `examples/speech-to-text/websocket/http/Program.cs`
+- `examples/speech-to-text/websocket/microphone/Program.cs`
+
+## Central product skills
+
+For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:
+
+```bash
+npx skills add deepgram/skills
+```
+
+This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).

.agents/skills/deepgram-dotnet-maintaining-sdk/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: deepgram-dotnet-maintaining-sdk
+description: Use when maintaining this hand-written Deepgram .NET SDK: editing client code, models, examples, tests, solution files, CI/CD packaging, or NuGet release flows. This repo is not Fern-generated. Covers `dotnet build`, `dotnet test`, `dotnet pack`, solution-file selection (`Deepgram.sln`, `Deepgram.Dev.sln`, `Deepgram.DevBuild.sln`), `clean-up.sh`, and NuGet publishing conventions from GitHub Actions.
+---
+
+# Maintaining the Deepgram .NET SDK
+
+This SDK is hand-maintained C#/.NET code. It is **not** Fern-generated. Do not use Fern regeneration instructions from other Deepgram SDKs here.
+
+## Repo shape
+
+- `Deepgram/` — main SDK package (`Deepgram.csproj`)
+- `Deepgram.Microphone/` — microphone helper package (`Deepgram.Microphone.csproj`)
+- `Deepgram.Tests/` — unit tests
+- `examples/` — runnable local examples
+- `tests/` — edge cases / expected failure projects
+- `clean-up.sh` — removes `.vs`, `dist`, `obj`, `bin`
+- `extras/dg_logo.png` — package icon packed into NuGet packages
+
+## Solution files
+
+- `Deepgram.sln`
+  - main CI/CD solution
+  - contains `Deepgram`, `Deepgram.Tests`, `Deepgram.Microphone`
+  - used by CI, release build, and stable NuGet packaging
+- `Deepgram.Dev.sln`
+  - broad developer solution
+  - includes examples, edge cases, expected failures, and test/debug projects
+- `Deepgram.DevBuild.sln`
+  - packaging-only developer-build solution
+  - contains `Deepgram` and `Deepgram.Microphone`
+  - used for unstable/dev NuGet packages
+
+## Build, test, pack
+
+Stable validation:
+
+```bash
+dotnet restore Deepgram.sln
+dotnet test Deepgram.sln
+dotnet build Deepgram.sln --configuration Release --no-restore
+```
+
+Stable pack:
+
+```bash
+dotnet restore Deepgram.sln
+dotnet build Deepgram.sln --configuration Release --no-restore
+dotnet pack Deepgram.sln --configuration Release --no-restore --output ./dist -p:Version=<VERSION>
+```
+
+Developer / prerelease pack:
+
+```bash
+dotnet restore Deepgram.DevBuild.sln
+dotnet build Deepgram.DevBuild.sln --configuration Release --no-restore
+dotnet pack Deepgram.DevBuild.sln --configuration Release --no-restore --output ./dist -p:Version=<VERSION>
+```
+
+Local cleanup:
+
+```bash
+bash ./clean-up.sh
+```
+
+## NuGet package behavior
+
+`Deepgram/Deepgram.csproj`:
+- stable package ID on `Deepgram.sln`: `Deepgram`
+- unstable package ID on `Deepgram.DevBuild.sln`: `Deepgram.Unstable.SDK.Builds`
+
+`Deepgram.Microphone/Deepgram.Microphone.csproj`:
+- stable package ID on `Deepgram.sln`: `Deepgram.Microphone`
+- unstable package ID on `Deepgram.DevBuild.sln`: `Deepgram.Unstable.Microphone.Builds`
+
+Both projects target:
+- `net8.0`
+- `netstandard2.0`
+
+Both enable:
+- nullable reference types
+- implicit usings
+- latest language version
+
+## Release flow from GitHub Actions
+
+From `.github/workflows/CD.yml`:
+- restore `Deepgram.sln`
+- build `Deepgram.sln`
+- pack `Deepgram.sln` into `./dist`
+- publish with `dotnet nuget push ./dist/**.nupkg --source nuget.org --api-key ${{secrets.NUGET_API_KEY}}`
+
+From `.github/workflows/CD-dev.yml`:
+- same flow, but against `Deepgram.DevBuild.sln`
+- tag patterns include `-dev`, `-alpha`, `-beta`, `-rc`
+
+## Contribution guidance
+
+- Read `.github/CONTRIBUTING.md` first.
+- This repo welcomes docs, tests, bug fixes, and feature work.
+- For broad manual validation, use the example projects under `examples/`.
+- Keep examples resettable; `examples/README.md` explicitly asks contributors to undo local test edits.
+
+## Codebase-specific maintenance notes
+
+1. **No Fern.** Do not add `.fernignore`, regen scripts, or “frozen file” workflows.
+2. **Prefer the non-deprecated client surface.** Use `CreateListenRESTClient`, `CreateListenWebSocketClient`, `CreateSpeakRESTClient`, `CreateSpeakWebSocketClient`, `CreateManageClient`, `CreateAuthClient`, `CreateAgentWebSocketClient`.
+3. **Deprecated classes still exist for compatibility.** Examples: `PreRecordedClient`, `LiveClient`, `SpeakClient`, `OnPremClient`. Avoid extending them for new features.
+4. **Authentication supports both API keys and bearer access tokens.** `DeepgramHttpClientOptions` and `DeepgramWsClientOptions` implement priority-based credential selection.
+5. **The microphone helper is a separate package.** Changes in streaming examples may affect both `Deepgram/` and `Deepgram.Microphone/`.
+6. **Packaging metadata depends on the solution name.** If pack output looks wrong, confirm which `.sln` you used.
+
+## Source-of-truth files for maintainers
+
+- `README.md`
+- `.github/CONTRIBUTING.md`
+- `.github/workflows/CI.yml`
+- `.github/workflows/CD.yml`
+- `.github/workflows/CD-dev.yml`
+- `Deepgram/Deepgram.csproj`
+- `Deepgram.Microphone/Deepgram.Microphone.csproj`
+- `clean-up.sh`