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

* 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-js-sdk      — JavaScript/TypeScript SDK maintenance workflow

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

Add .agents to .fernignore so skills survive Fern regeneration.

* 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-js- 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-js-speech-to-text
  using-text-to-speech     → deepgram-js-text-to-speech
  using-text-intelligence  → deepgram-js-text-intelligence
  using-audio-intelligence → deepgram-js-audio-intelligence
  using-voice-agent        → deepgram-js-voice-agent
  using-conversational-stt → deepgram-js-conversational-stt
  using-management-api     → deepgram-js-management-api
  maintaining-js-sdk       → deepgram-js-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: sync maintainer skill and AGENTS.md with .fernignore (address Copilot feedback)

Copilot flagged two threads on deepgram-js-maintaining-sdk/SKILL.md and
asked that AGENTS.md be kept consistent. Both correct:

- .agents/ was added to .fernignore in the initial commit but the
  maintainer skill's permanently-frozen list and note still claimed
  .agents/ wasn't frozen.
- AGENTS.md agent-file bullet didn't list .agents/ either.

All three source-of-truth surfaces now agree: CLAUDE.md, AGENTS.md,
.claude/, .agents/ are permanently frozen.

* docs: unify variable name and strip stray space (Copilot re-review feedback)

All 8 new Copilot threads on PR #486:

- 7 skills defined the client as `const client` in the auth section
  but the quick-start snippets below used `deepgramClient`. Renamed
  the auth variable to `deepgramClient` so every code block can be
  copy/pasted standalone without renaming.
- deepgram-js-speech-to-text/SKILL.md: removed a trailing space inside
  the backticked `Token` auth scheme.

Affected skills: deepgram-js-speech-to-text, deepgram-js-text-to-speech,
deepgram-js-text-intelligence, deepgram-js-audio-intelligence,
deepgram-js-voice-agent, deepgram-js-conversational-stt,
deepgram-js-management-api.

* docs: define vars in snippets, fix attribution, sync AGENTS.md (Copilot feedback)

All 6 new Copilot threads on PR #486:

- deepgram-js-management-api/SKILL.md:
  - Attribution now includes examples/32-management-project-models.ts (where
    `include_outdated: false` is actually demonstrated).
  - Declared `const projectId = process.env.DEEPGRAM_PROJECT_ID;` once at
    the top of each snippet and used `projectId` consistently instead of
    switching between `process.env.DEEPGRAM_PROJECT_ID` and an undefined
    `projectId` identifier.
- deepgram-js-speech-to-text/SKILL.md + deepgram-js-conversational-stt/SKILL.md:
  WebSocket quick-start snippets referenced an undefined `audioStream`.
  Added the `createReadStream` setup (from the referenced examples) so
  the snippets are copy/paste runnable.
- AGENTS.md: added `.mcp.json` to the permanently-frozen agent-file
  bullet so the list matches .fernignore and the maintainer skill.

Author: lukeocodes

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

@@ -0,0 +1,134 @@
+---
+name: deepgram-js-audio-intelligence
+description: Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram audio analytics overlays on `/v1/listen` - summarize, topics, intents, sentiment, diarize, redact, detect_language, and entity detection. Same endpoint as plain STT, different params. Covers REST via `client.listen.v1.media.transcribeUrl` / `transcribeFile` and the WebSocket-supported subset on `client.listen.v1.createConnection()` / `connect()`. Use `deepgram-js-speech-to-text` for plain transcription and `deepgram-js-text-intelligence` for analytics on already-transcribed text. Triggers include "audio intelligence", "summarize audio", "diarize", "sentiment from audio", "redact PII", and "detect language audio".
+---
+
+# Using Deepgram Audio Intelligence (JavaScript / TypeScript SDK)
+
+Analytics overlays applied to `/v1/listen`: summaries, topics, intents, sentiment, language detection, diarization, redaction, entities. Same client surface as STT; turn features on with parameters.
+
+## When to use this product
+
+- You have **audio** and want analytics returned alongside the transcript.
+- REST is the primary path; the WebSocket path supports only a subset of intelligence features.
+
+**Use a different skill when:**
+- You just want transcript output → `deepgram-js-speech-to-text`.
+- You already have text and want analytics on that text → `deepgram-js-text-intelligence`.
+- You need Flux turn-taking → `deepgram-js-conversational-stt`.
+- You need a full interactive voice agent → `deepgram-js-voice-agent`.
+
+## Feature availability: REST vs WSS
+
+| Feature | REST | WSS |
+|---|---|---|
+| `diarize` | yes | yes |
+| `redact` | yes | yes |
+| `detect_entities` | yes | yes |
+| `punctuate`, `smart_format` | yes | yes |
+| `summarize` | yes | no in current WSS connect args |
+| `topics` | yes | no |
+| `intents` | yes | no |
+| `sentiment` | yes | no |
+| `detect_language` | yes | no |
+
+## Authentication
+
+```js
+require("dotenv").config();
+
+const { DeepgramClient } = require("@deepgram/sdk");
+
+const deepgramClient = new DeepgramClient({
+  apiKey: process.env.DEEPGRAM_API_KEY,
+});
+```
+
+## Quick start — REST with analytics
+
+From `examples/22-transcription-advanced-options.ts`:
+
+```js
+const data = await deepgramClient.listen.v1.media.transcribeUrl({
+  url: "https://dpgr.am/spacewalk.wav",
+  model: "nova-3",
+  language: "en",
+  punctuate: true,
+  paragraphs: true,
+  utterances: true,
+  smart_format: true,
+  sentiment: true,
+  topics: true,
+  custom_topic: "custom_topic",
+  custom_topic_mode: "extended",
+  intents: true,
+  custom_intent: "custom_intent",
+  custom_intent_mode: "extended",
+  detect_entities: true,
+  detect_language: true,
+  diarize: true,
+  keyterm: ["keyword1", "keyword2"],
+  redact: ["pci", "ssn"],
+});
+```
+
+## Quick start — WSS subset
+
+Start from `examples/07-transcription-live-websocket.ts` and keep the same socket flow, but only use WSS-supported intelligence flags such as `diarize`, `redact`, and `detect_entities` in the connection args.
+
+```js
+const deepgramConnection = await deepgramClient.listen.v1.createConnection({
+  model: "nova-3",
+  diarize: true,
+  redact: "pci",
+  detect_entities: true,
+});
+```
+
+## Key parameters / API surface
+
+- Analytics flags: `summarize`, `topics`, `intents`, `sentiment`, `detect_language`, `detect_entities`, `diarize`, `redact`, `custom_topic`, `custom_topic_mode`, `custom_intent`, `custom_intent_mode`.
+- Standard STT flags still apply: `model`, `language`, `encoding`, `sample_rate`, `punctuate`, `smart_format`, `utterances`, `paragraphs`, `multichannel`.
+- Nova-3-specific biasing in repo examples uses `keyterm`, not `keywords`.
+
+## API reference (layered)
+
+1. **In-repo reference**: `reference.md` → `Listen V1 Media`; WSS subset behavior lives in `src/CustomClient.ts` and `src/api/resources/listen/resources/v1/client/{Client,Socket}.ts`.
+2. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml
+3. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml
+4. **Context7**: library ID `/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 `/v1/listen` is versioned, not plain boolean.** The generated REST surface and examples point at `"v2"`.
+2. **Most intelligence flags are REST-only.** Current WSS connect args do not expose `topics`, `intents`, `sentiment`, `summarize`, or `detect_language`.
+3. **`redact` typing is looser in practice than in the generated alias.** Examples pass arrays like `["pci", "ssn"]`, even though `ListenV1Redact` itself is just a string alias.
+4. **Use `keyterm` for Nova-3 biasing.** `examples/22-transcription-advanced-options.ts` explicitly notes keywords are not supported for Nova-3.
+5. **Model/feature support is product-side.** `nova-3` is the safest choice when mixing many overlays.
+6. **Diarization quality depends on audio quality and duration.** Short or noisy clips churn speakers.
+
+## Example files in this repo
+
+- `examples/22-transcription-advanced-options.ts`
+- `examples/04-transcription-prerecorded-url.ts`
+- `examples/05-transcription-prerecorded-file.ts`
+- `examples/07-transcription-live-websocket.ts`
+
+## 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-js-conversational-stt/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: deepgram-js-conversational-stt
+description: Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Conversational STT v2 / Flux (`/v2/listen`) for turn-aware streaming transcription. Covers `client.listen.v2.createConnection()` / `connect()`, Flux models, and turn events like `TurnInfo`. Use `deepgram-js-speech-to-text` for standard v1 ASR and `deepgram-js-voice-agent` for full-duplex assistants. Triggers include "flux", "v2 listen", "conversational STT", "turn detection", "end of turn", "EOT", and "listen.v2".
+---
+
+# Using Deepgram Conversational STT / Flux (JavaScript / TypeScript SDK)
+
+Turn-aware streaming STT via `/v2/listen` for conversational audio and explicit turn events.
+
+## When to use this product
+
+- You need **turn-aware** transcription, not just a word stream.
+- You want Flux-style events like `TurnInfo` and `Connected`.
+- You are building a conversational interface but do **not** want the full Voice Agent runtime.
+
+**Use a different skill when:**
+- You want general v1 transcription or prerecorded REST → `deepgram-js-speech-to-text`.
+- You want a hosted assistant with think + speak built in → `deepgram-js-voice-agent`.
+- You want analytics overlays like sentiment and summaries → `deepgram-js-audio-intelligence`.
+
+## Authentication
+
+```js
+require("dotenv").config();
+
+const { DeepgramClient } = require("@deepgram/sdk");
+
+const deepgramClient = new DeepgramClient({
+  apiKey: process.env.DEEPGRAM_API_KEY,
+});
+```
+
+## Quick start
+
+From `examples/26-transcription-live-websocket-v2.ts`:
+
+```js
+const deepgramConnection = await deepgramClient.listen.v2.createConnection({
+  model: "flux-general-en",
+});
+
+deepgramConnection.on("message", (data) => {
+  if (data.type === "Connected") {
+    console.log("Connected:", data);
+  } else if (data.type === "TurnInfo") {
+    console.log("Turn Info:", data);
+  } else if (data.type === "FatalError") {
+    deepgramConnection.close();
+  }
+});
+
+deepgramConnection.connect();
+await deepgramConnection.waitForOpen();
+
+// Swap this for a live mic capture in real apps; the repo example uses
+// `createReadStream` over a sample file.
+const { createReadStream } = require("node:fs");
+const audioStream = createReadStream("samples/spacewalk.wav");
+
+audioStream.on("data", (chunk) => {
+  deepgramConnection.sendMedia(chunk);
+});
+
+audioStream.on("end", () => {
+  deepgramConnection.sendCloseStream({ type: "CloseStream" });
+});
+```
+
+## Key parameters / API surface
+
+- Connect args from `src/api/resources/listen/resources/v2/client/Client.ts`: `model`, `encoding`, `sample_rate`, `eager_eot_threshold`, `eot_threshold`, `eot_timeout_ms`, `keyterm`, `tag`, `mip_opt_out`.
+- Socket methods from `src/api/resources/listen/resources/v2/client/Socket.ts`: `sendMedia(...)`, `sendCloseStream(...)`, `sendListenV2Configure(...)`, `waitForOpen()`.
+- Custom wrapper additions from `src/CustomClient.ts`: `createConnection(...)` alias and Node-only `ping(...)` helper.
+
+## Limitations
+
+- The current generated `ListenV2Model` type only exposes `"flux-general-en"`.
+- Product docs mention broader Flux capabilities, but `flux-general-multi` / `language_hint` are **not** surfaced in this repo's generated types today.
+
+## API reference (layered)
+
+1. **In-repo reference**: `reference.md` does not currently document `listen.v2`; use `src/CustomClient.ts` and `src/api/resources/listen/resources/v2/client/{Client,Socket}.ts` as the in-repo source of truth.
+2. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml
+3. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml
+4. **Context7**: library ID `/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. **There is no REST path here.** This skill is `/v2/listen` WebSocket only.
+2. **Current repo typing only allows `flux-general-en`.** Treat multilingual Flux support as a product capability not yet reflected in this SDK surface.
+3. **Close with `sendCloseStream`, not `sendFinalize`.** Finalize is the v1 pattern.
+4. **`ping()` is Node-only.** `src/CustomClient.ts` throws in browsers because browser WS ping frames are not user-exposed.
+5. **`createConnection()` is lazy.** Call `connect()` after registering handlers.
+6. **The example explicitly warns about access/availability.** A 400 may mean your account or endpoint is not enabled yet, not that your socket code is wrong.
+7. **Omit `encoding` for containerized audio.** Keep it for raw PCM/Opus streams.
+
+## Example files in this repo
+
+- `examples/26-transcription-live-websocket-v2.ts`
+- `examples/27-deepgram-session-header.ts`
+
+## 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-js-maintaining-sdk/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: deepgram-js-maintaining-sdk
+description: Use when regenerating this JavaScript/TypeScript SDK with Fern, editing `.fernignore`, preparing the repo for a generator release, reconciling hand-maintained files after regen, or deciding whether a file should be permanently frozen vs temporarily frozen. This SDK is Fern-generated - most files under `src/` should not be edited directly. Triggers include "fern regen", "regenerate SDK", ".fernignore", "unfreeze", "re-apply patches", "SDK regeneration", and "freeze classification".
+---
+
+# Maintaining the Deepgram JavaScript / TypeScript SDK
+
+This SDK is generated by [Fern](https://buildwithfern.com/). Most files under `src/` are auto-generated and should not be edited directly. Some files are hand-written or protected in `.fernignore` so Fern does not overwrite them.
+
+When a new Fern generator release is available, prepare the repo so Fern can replace generated output, then re-apply any still-needed manual work after reviewing the diff.
+
+## Freeze classification rules
+
+Every entry in `.fernignore` falls into one of two categories. The comment above the entry is the first clue, but use these rules when in doubt.
+
+### Never unfreeze (permanently frozen)
+
+These files are entirely hand-written or repo-maintained. Fern should never own them.
+
+How to identify:
+
+- The file was created by Deepgram, not by Fern (`src/CustomClient.ts`, curated exports, helper scripts, hand-written tests).
+- The file is documentation, tooling, config, or examples managed outside generator output.
+- The file lives outside `src/api/` or deliberately wraps generated code.
+
+Current permanently frozen entries from `.fernignore` / `AGENTS.md`:
+
+- `src/CustomClient.ts` — custom wrapper for auth prefixing, session ID propagation, browser/Node WebSocket handling, reconnect behavior, binary message fixes, and `createConnection()` aliases
+- `src/index.ts` — curated re-exports with backwards-compatible namespace behavior
+- `scripts/fix-wire-test-imports.js`, `scripts/revert-wire-test-imports.js` — post-generation import fixups
+- `scripts/proxy-server.js` — development proxy
+- `scripts/validate-esm-build.mjs` — ESM build validation
+- `webpack.config.js` — browser bundle config
+- `tests/browser/` — browser-specific suite
+- `tests/esm-build.test.ts` — ESM validation test
+- `tests/unit/*` — hand-written unit tests
+- `tests/wire/websocket/` — hand-written websocket wire tests
+- `tests/wire/listen/v1/transcription.test.ts` — hand-written wire test
+- `vitest.config.mts` — test config
+- `Makefile` — developer command runner
+- `MIGRATION_GUIDE_V4_TO_V5.md` — migration docs
+- `README.md`, `CHANGELOG.md`, `docs/`, `examples/` — repo docs and examples
+- `.npmignore`, `.gitignore`, `.npmrc`, `.github/` — package/repo config
+- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.mcp.json` — agent/tooling files
+
+### Unfreeze for regen (temporarily frozen)
+
+These are generated files with local patches. They stay frozen between regens, but should be temporarily swapped to `.bak` during a regen prep so Fern can overwrite the original path.
+
+How to identify:
+
+- Fern would recreate the file if it were removed.
+- Your current copy is a patched version of generator output, not a fully hand-written file.
+
+Current temporarily frozen entries:
+
+- **None right now.** `AGENTS.md` explicitly says all current `.fernignore` entries are permanently frozen.
+
+If you patch a generated file in the future, add it to `.fernignore` with a comment explaining the patch and update this skill plus `AGENTS.md`.
+
+## Prepare repo for regeneration
+
+1. Create a branch from `main` named `lo/sdk-gen-<YYYY-MM-DD>`.
+2. Push it and open a PR titled `chore: SDK regeneration <YYYY-MM-DD>`.
+3. Read `.fernignore` and classify every entry.
+4. For each **temporarily frozen** file only:
+   - copy it to `<filename>.bak` beside the original
+   - replace the original path in `.fernignore` with the `.bak` path
+5. Leave permanently frozen entries untouched.
+6. Commit as `chore: unfreeze files pending regen` and push.
+
+## After regeneration
+
+1. Diff each `.bak` file against the newly generated original.
+2. Re-apply only the patches that are still needed.
+3. Change `.fernignore` entries from `.bak` back to the original path for files that still need freezing.
+4. Remove `.fernignore` entries entirely for files where the generator is now correct.
+5. Delete the `.bak` files.
+6. Run verification.
+7. Commit as `chore: re-apply manual patches after regen` and push.
+
+## Verification commands
+
+Repo guidance in `AGENTS.md` says:
+
+```bash
+make build && make test && make lint
+```
+
+Package scripts in `package.json` resolve to:
+
+```bash
+pnpm build
+pnpm test
+pnpm lint
+pnpm check
+```
+
+Relevant underlying commands today:
+
+- `pnpm build` → `tsc --project ./tsconfig.cjs.json` + `tsc --project ./tsconfig.esm.json` + ESM rename script
+- `pnpm test` → `vitest`
+- `pnpm lint` / `pnpm check` → Biome lint/check
+
+## JS-specific maintainer notes
+
+1. **Do not edit most generated files under `src/api/` directly.** Prefer Fern input changes or post-regen patch review.
+2. **`src/CustomClient.ts` is the highest-risk permanent wrapper.** It carries auth prefixing, browser subprotocol auth, custom websocket startup, binary handling, and the user-facing `createConnection()` aliases used by examples.
+3. **The repo ships both CJS and ESM.** Validate both outputs after generator changes.
+4. **Browser behavior matters.** The wrapper intentionally diverges for browser WebSocket auth because browsers cannot send arbitrary socket headers.
+5. **`.agents/` is permanently frozen in `.fernignore`.** Treat these skills as hand-written documentation during regeneration; Fern will not touch the folder. Keep this note aligned with `AGENTS.md` whenever the frozen-file list changes.
+
+## Source-of-truth note
+
+`AGENTS.md` is the maintainer source of truth in this repo. Keep this skill aligned with it whenever the regeneration workflow or frozen-file list changes.