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

## Summary

Adds 8 agent-agnostic skills under `.agents/skills/` following the
[skills.sh](https://skills.sh) convention. Discoverable by OpenCode,
Claude Code, Codex, Cursor, and 40+ other agent tools via `npx skills`.

## What's included

**7 product usage skills** — one per Deepgram product, each with
authentication, quick-start (real rust code from `examples/`), key
parameters, layered API references, gotchas, and sibling-skill routing:

| Skill | Endpoint | Notes |
|---|---|---|
| `using-speech-to-text` | `/v1/listen` | REST + WSS |
| `using-text-to-speech` | `/v1/speak` | REST + WSS |
| `using-text-intelligence` | `/v1/read` | REST only |
| `using-audio-intelligence` | `/v1/listen` w/ analytics | REST primary,
WSS subset |
| `using-voice-agent` | `agent.deepgram.com/v1/agent/converse` | WSS
full-duplex |
| `using-conversational-stt` | `/v2/listen` | Flux models, turn
detection |
| `using-management-api` | `/v1/projects`, `/v1/models`, etc. |
Management + agent configs |

**1 maintainer skill**:
- `maintaining-rust-sdk` — SDK-specific maintenance workflow

## Layered API references

Every skill cites:
1. In-repo reference
2. OpenAPI: `https://developers.deepgram.com/openapi.yaml`
3. AsyncAPI: `https://developers.deepgram.com/asyncapi.yaml`
4. Context7: `/llmstxt/developers_deepgram_llms_txt`
5. Product-specific doc pages

## How to use

```bash
# List all skills
npx skills add deepgram/deepgram-rust-sdk --list

# Install one skill to the active agent
npx skills add deepgram/deepgram-rust-sdk --skill using-speech-to-text

# Install all 8 to a specific agent (global)
npx skills add deepgram/deepgram-rust-sdk -g -a claude-code
```

## Verification

`npx skills add . --list` finds 8 skills with valid frontmatter.

Sibling PRs in the other Deepgram SDKs: python, js, java, go, rust,
swift, kotlin, dotnet, browser.

Author: lukeocodes

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

@@ -0,0 +1,128 @@
+---
+name: deepgram-rust-audio-intelligence
+description: Use when implementing Deepgram audio intelligence from the Rust SDK, especially when intelligence features are attached to STT Options and batch responses instead of a separate audio-intelligence module.
+---
+
+# Using Deepgram Audio Intelligence (Rust SDK)
+
+Use this skill when the user wants transcript plus enrichment from audio, not a standalone text analysis request.
+
+## When to use this product
+
+- Running summarization, topics, intents, sentiments, entity detection, paragraphs, search, diarization, or utterances against audio.
+- Explaining that the Rust crate exposes these features through STT `Options`, not a separate `audio_intelligence` module.
+
+## Authentication
+
+Audio intelligence rides on the `listen` feature because it is implemented through prerecorded transcription.
+
+```toml
+[dependencies]
+deepgram = { version = "0.9.2", default-features = false, features = ["listen"] }
+tokio = { version = "1", features = ["full"] }
+```
+
+```rust
+let dg = deepgram::Deepgram::new(std::env::var("DEEPGRAM_API_KEY")?)?;
+```
+
+## Quick start
+
+## Quick start: prerecorded audio + intelligence flags
+
+```rust
+use deepgram::{
+    common::{
+        audio_source::AudioSource,
+        options::{Language, Options},
+    },
+    Deepgram,
+};
+use tokio::fs::File;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api_key = std::env::var("DEEPGRAM_API_KEY")?;
+    let dg = Deepgram::new(&api_key)?;
+
+    let file = File::open("examples/audio/bueller.wav").await?;
+    let source = AudioSource::from_buffer_with_mime_type(file, "audio/wav");
+
+    let options = Options::builder()
+        .language(Language::en_US)
+        .punctuate(true)
+        .detect_entities(true)
+        .intents(true)
+        .sentiment(true)
+        .topics(true)
+        .summarize(true)
+        .paragraphs(true)
+        .utterances(true)
+        .diarize(true)
+        .build();
+
+    let response = dg.transcription().prerecorded(source, &options).await?;
+
+    println!("transcript: {}", response.results.channels[0].alternatives[0].transcript);
+    println!("summary: {:?}", response.results.summary);
+    println!("topics: {:?}", response.results.topics);
+    println!("intents: {:?}", response.results.intents);
+    println!("sentiments: {:?}", response.results.sentiments);
+    println!("entities: {:?}", response.results.channels[0].alternatives[0].entities);
+    Ok(())
+}
+```
+
+## Key parameters
+
+- Intelligence flags on `common::options::OptionsBuilder`: `detect_entities`, `intents`, `sentiment`, `topics`, `summarize`, `paragraphs`, `utterances`, `diarize`, `search`, `keywords`, `keyterms`, `multichannel`.
+- Result locations:
+  - `response.results.summary`
+  - `response.results.topics`
+  - `response.results.intents`
+  - `response.results.sentiments`
+  - `response.results.channels[0].alternatives[0].entities`
+  - `response.results.channels[0].alternatives[0].paragraphs`
+  - `response.results.utterances`
+  - `response.results.channels[0].search`
+
+## API reference (layered)
+
+1. **In-repo**
+   - `src/common/options.rs`
+   - `src/common/batch_response.rs`
+   - `src/listen/rest.rs`
+   - `examples/transcription/rest/prerecorded_from_file.rs`
+2. **OpenAPI**
+   - Raw spec: `https://developers.deepgram.com/openapi.yaml`
+   - Endpoint reference: `https://developers.deepgram.com/reference/speech-to-text/listen-pre-recorded`
+3. **AsyncAPI**
+   - Usually not the primary source for full audio-intelligence response shapes in this crate
+   - Raw spec: `https://developers.deepgram.com/asyncapi.yaml`
+4. **Context7**
+   - `/llmstxt/developers_deepgram_llms_txt`
+5. **Product docs**
+   - `https://developers.deepgram.com/docs/audio-intelligence`
+
+## Gotchas
+
+1. **No separate Rust module exists.** Audio intelligence is expressed as STT options plus prerecorded response fields.
+2. **Use prerecorded for full coverage.** The richest typed results live in `common::batch_response`; live `StreamResponse` does not expose the same intelligence objects.
+3. **Response fields are nested.** Some features live on `results`, others under `channels[...].alternatives[...]`.
+4. **Feature availability varies by API mode.** The crate shares one `Options` builder, but not every flag is equally meaningful for live streaming.
+
+## Example files in this repo
+
+- `examples/transcription/rest/prerecorded_from_file.rs`
+- `examples/transcription/rest/prerecorded_from_url.rs`
+- `examples/transcription/rest/callback.rs`
+
+## 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-rust-conversational-stt/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: deepgram-rust-conversational-stt
+description: Use when implementing Deepgram Flux conversational STT from the Rust SDK, including flux_request APIs, turn events, FluxResponse handling, and turn-detection tuning for voice-agent-style pipelines.
+---
+
+# Using Deepgram Conversational STT (Rust SDK)
+
+Use this skill for Deepgram Flux, the crate's supported turn-based conversational streaming path.
+
+## When to use this product
+
+- Building turn-based STT for voice-agent pipelines.
+- Handling `TurnEvent::{StartOfTurn, EndOfTurn, EagerEndOfTurn, TurnResumed, Update}`.
+- Tuning end-of-turn behavior with `eot_threshold`, `eager_eot_threshold`, and `eot_timeout_ms`.
+
+## Authentication
+
+Flux is under the `listen` feature.
+
+```toml
+[dependencies]
+deepgram = { version = "0.9.2", default-features = false, features = ["listen"] }
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+```
+
+```rust
+let dg = deepgram::Deepgram::new(std::env::var("DEEPGRAM_API_KEY")?)?;
+```
+
+## Quick start
+
+```rust
+use std::{io::Write, time::Duration};
+
+use deepgram::{
+    common::{
+        flux_response::{FluxResponse, TurnEvent},
+        options::{Encoding, Model, Options},
+    },
+    Deepgram,
+};
+use futures::stream::StreamExt;
+
+static PATH_TO_FILE: &str = "examples/audio/sample-mono.wav";
+static AUDIO_CHUNK_SIZE: usize = 18_063;
+static FRAME_DELAY: Duration = Duration::from_millis(100);
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api_key = std::env::var("DEEPGRAM_API_KEY")?;
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder()
+        .model(Model::FluxGeneralEn)
+        .eot_threshold(0.75)
+        .eot_timeout_ms(5000)
+        .keyterms(["activate", "cancel"])
+        .build();
+
+    let mut results = dg
+        .transcription()
+        .flux_request_with_options(options)
+        .encoding(Encoding::Linear32)
+        .sample_rate(44100)
+        .file(PATH_TO_FILE, AUDIO_CHUNK_SIZE, FRAME_DELAY)
+        .await?;
+
+    println!("Flux Request ID: {}", results.request_id());
+    while let Some(result) = results.next().await {
+        match result? {
+            FluxResponse::Connected { request_id, sequence_id } => {
+                println!("Connected: {request_id} (seq: {sequence_id})");
+            }
+            FluxResponse::TurnInfo { event, turn_index, transcript, end_of_turn_confidence, .. } => {
+                match event {
+                    TurnEvent::StartOfTurn => println!("▶ [Turn {turn_index}] START"),
+                    TurnEvent::EndOfTurn => println!("✓ [Turn {turn_index}] END ({end_of_turn_confidence:.2}): {transcript}"),
+                    TurnEvent::Update => {
+                        if !transcript.is_empty() {
+                            print!("\r[Turn {turn_index}] UPDATE: {transcript}");
+                            std::io::stdout().flush().unwrap();
+                        }
+                    }
+                    _ => {}
+                }
+            }
+            FluxResponse::FatalError { code, description, .. } => {
+                eprintln!("{code}: {description}");
+                break;
+            }
+            FluxResponse::Unknown(value) => println!("unknown: {value}"),
+        }
+    }
+
+    Ok(())
+}
+```
+
+## Key parameters
+
+- Entrypoints: `flux_request()`, `flux_request_with_options(options)`.
+- Flux transport builder fields: `encoding`, `sample_rate`, then `.file(...)`, `.stream(...)`, or `.handle().await?`.
+- Flux-specific tuning in shared `OptionsBuilder`: `model(Model::FluxGeneralEn)`, `eot_threshold`, `eager_eot_threshold`, `eot_timeout_ms`, `keyterms`.
+- Main response type: `common::flux_response::FluxResponse`.
+
+## API reference (layered)
+
+1. **In-repo**
+   - `src/listen/flux.rs`
+   - `src/common/flux_response.rs`
+   - `src/common/options.rs`
+   - `examples/transcription/flux/simple_flux.rs`
+   - `tests/flux_unknown_messages.rs`
+   - `tests/flux_e2e.rs`
+2. **OpenAPI**
+   - Raw spec: `https://developers.deepgram.com/openapi.yaml`
+   - Endpoint reference: `https://developers.deepgram.com/reference/speech-to-text/listen-flux`
+3. **AsyncAPI**
+   - Raw spec: `https://developers.deepgram.com/asyncapi.yaml`
+   - Flux channel docs are surfaced from the same product reference page above
+4. **Context7**
+   - `/llmstxt/developers_deepgram_llms_txt`
+5. **Product docs**
+   - `https://developers.deepgram.com/docs/stt/getting-started`
+
+## Gotchas
+
+1. **Flux is English-only in this crate's model surface.** The default supported model is `Model::FluxGeneralEn`.
+2. **Real-time pacing matters even more than standard streaming.** The example warns that bad chunk size / delay values can break turn detection.
+3. **Unknown events are intentional.** `FluxResponse::Unknown` and `TurnEvent::Unknown` are there for forward compatibility; handle them instead of assuming exhaustiveness.
+4. **Use Flux for turn-taking, not full agent control.** If you need TTS replies, prompts, or tool calls, that is Voice Agent territory and not a typed Rust SDK surface yet.
+
+## Example files in this repo
+
+- `examples/transcription/flux/simple_flux.rs`
+- `examples/transcription/flux/simple_flux_token.rs`
+- `examples/transcription/flux/microphone_flux.rs`
+- `tests/flux_unknown_messages.rs`
+- `tests/flux_e2e.rs`
+
+## 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-rust-maintaining-sdk/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: deepgram-rust-maintaining-sdk
+description: Use when maintaining the Deepgram Rust SDK itself: feature flags, examples, tests, cargo fmt/clippy/build/test, CHANGELOG updates, crate releases, and adding new endpoints without Fern workflows.
+---
+
+# Maintaining Deepgram Rust SDK
+
+Use this skill when changing the SDK itself rather than consuming it.
+
+## When to use this skill
+
+- Adding or updating API surfaces under `src/`.
+- Changing feature flags, examples, tests, or docs.
+- Preparing a release to crates.io.
+- Auditing the repo's current hand-maintained conventions.
+
+## Authentication
+
+Not applicable for repository maintenance.
+
+## Quick start
+
+## Quick start: local verification loop
+
+```sh
+cargo fmt --all
+cargo clippy --all-targets --all-features -- -D warnings
+cargo build --all-features
+cargo test --all-features
+```
+
+## Quick start: feature-aware development
+
+- Default features are `manage`, `listen`, and `speak`.
+- `listen` pulls in WebSocket dependencies.
+- If you add a module, decide whether it belongs behind a Cargo feature and wire examples accordingly in `Cargo.toml`.
+
+## Key parameters
+
+- Core files:
+  - `Cargo.toml`
+  - `src/lib.rs`
+  - `src/`
+  - `examples/`
+  - `tests/`
+  - `CHANGELOG.md`
+  - `CONTRIBUTING.md`
+- Current quality gates:
+  - `cargo fmt`
+  - `cargo clippy`
+  - `cargo build`
+  - `cargo test`
+- Contribution rules from `CONTRIBUTING.md`:
+  - PRs should target `dev`, not `main`
+  - tests must be complete and pass
+  - commit messages must be descriptive
+  - include a test for bug fixes
+
+## API reference (layered)
+
+1. **In-repo**
+   - `README.md`
+   - `CONTRIBUTING.md`
+   - `CHANGELOG.md`
+   - `Cargo.toml`
+   - `src/lib.rs`
+   - `examples/README.md`
+2. **OpenAPI**
+   - `https://developers.deepgram.com/openapi.yaml`
+3. **AsyncAPI**
+   - `https://developers.deepgram.com/asyncapi.yaml`
+4. **Context7**
+   - `/llmstxt/developers_deepgram_llms_txt`
+5. **Product docs**
+   - `https://developers.deepgram.com/reference/`
+   - `https://docs.rs/deepgram/latest/deepgram/`
+
+## Gotchas
+
+1. **This SDK is not Fern-generated.** Do not describe or assume any Fern regeneration workflow.
+2. **Match existing hand-maintained module patterns.** Add new product surfaces with explicit modules, option structs, response structs, examples, and feature gating where appropriate.
+3. **Update examples and tests with new APIs.** This repo treats example programs and integration tests as part of the public developer experience.
+4. **Keep `CHANGELOG.md` honest.** Follow the existing Keep a Changelog + SemVer style already used in the repo.
+5. **Release flow is branch-sensitive.** `main` is release-oriented; normal contribution PRs target `dev`.
+6. **If you publish a release, verify crate metadata first.** Ensure `version`, features, examples, and changelog all line up before `cargo publish`.
+
+## Example files in this repo
+
+- `examples/README.md`
+- `examples/transcription/`
+- `examples/speak/rest/`
+- `examples/manage/`
+- `tests/flux_unknown_messages.rs`
+- `tests/flux_e2e.rs`