chore: add agent skills for product usage and maintenance [no-ci] by lukeocodes · Pull Request #695 · deepgram/deepgram-python-sdk

lukeocodes · 2026-04-24T11:55:10Z

Summary

Adds 8 agent-agnostic skills under .agents/skills/ following the skills.sh convention. These skills are 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 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 + TextBuilder helper
`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.	All manage + voice_agent.configurations

1 maintainer skill:

maintaining-python-sdk — Fern regeneration workflow (mirrors AGENTS.md)

Layered API references

Every skill cites:

In-repo reference.md (Fern-generated)
OpenAPI: https://developers.deepgram.com/openapi.yaml
AsyncAPI: https://developers.deepgram.com/asyncapi.yaml
Context7: /llmstxt/developers_deepgram_llms_txt
Product-specific doc pages

`.fernignore`

Added .agents to the permanently-frozen list so skills survive Fern regeneration.

How to use

```bash

List all skills in this SDK

npx skills add deepgram/deepgram-python-sdk --list

Install one skill to the active agent

npx skills add deepgram/deepgram-python-sdk --skill using-speech-to-text

Install all 8 to a specific agent (global)

npx skills add deepgram/deepgram-python-sdk -g -a claude-code
```

Verification

```
$ npx skills add . --list
✓ Local path validated
✓ Found 8 skills
```

Parallel PRs landing for the other 8 SDK repos (js, java, go, rust, swift, kotlin, dotnet, browser).

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-python-sdk — Fern regeneration workflow (mirrors AGENTS.md) Each skill includes authentication, quick-start with real code from examples/, key parameters, layered API references (in-repo reference.md, OpenAPI, AsyncAPI, Context7, product docs), gotchas, and sibling-skill routing. Add .agents/ to .fernignore so skills survive Fern regeneration.

Copilot

Pull request overview

Adds agent-tool “skills.sh”-compatible documentation under .agents/skills/ to make this SDK discoverable/usable via npx skills, and updates Fern regeneration ignores so these files survive codegen.

Changes:

Add 8 new .agents/skills/*/SKILL.md skill docs covering Deepgram product usage and SDK maintenance.
Update .fernignore to permanently freeze .agents/ (and clarify agent-file comments).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`.fernignore`	Freezes `.agents/` so skill docs aren’t overwritten/removed by Fern regeneration.
`.agents/skills/using-speech-to-text/SKILL.md`	Adds STT v1 usage guidance (REST + WSS).
`.agents/skills/using-text-to-speech/SKILL.md`	Adds TTS v1 usage guidance (REST + WSS) + TextBuilder helper notes.
`.agents/skills/using-text-intelligence/SKILL.md`	Adds `/v1/read` (text intelligence) usage guidance.
`.agents/skills/using-audio-intelligence/SKILL.md`	Adds `/v1/listen` analytics-overlay usage guidance.
`.agents/skills/using-conversational-stt/SKILL.md`	Adds `/v2/listen` (Flux) turn-aware streaming guidance.
`.agents/skills/using-voice-agent/SKILL.md`	Adds agent converse (full-duplex) usage guidance.
`.agents/skills/using-management-api/SKILL.md`	Adds management API + voice agent config storage guidance.
`.agents/skills/maintaining-python-sdk/SKILL.md`	Documents Fern regen workflow and freeze/unfreeze rules.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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.

Copilot review on #695 flagged 9 concrete correctness issues. All verified against src/deepgram/ and wire tests: using-management-api/SKILL.md: - Project-scoped resources are nested under `client.manage.v1.projects.*`, not top-level `client.manage.v1.keys` / `.members` / `.invites` / `.usage` / `.billing`. - Invites are under `client.manage.v1.projects.members.invites`, not a top-level invites module. - Usage is `.projects.usage.get(project_id=...)` (not `.usage.list`); billing balances are `.projects.billing.balances.get(...)`. - Think-model discovery is on the Agent client (`client.agent.v1.settings.think.models.list()`), not under manage. - Voice Agent `configurations.create(config=...)` stores the `agent` block ONLY (listen/think/speak providers + prompt), not the full Settings message. Removed the `audio` top-level field from the example. - Added new gotchas covering the nesting rule, agent path rule, and agent-block-only rule. using-text-intelligence/SKILL.md: - `summarize` on `/v1/read` takes the string `"v2"`, not a boolean. The SDK typedef is `TextAnalyzeRequestSummarize = typing.Union[typing.Literal["v2"], typing.Any]` and wire tests pass `summarize="v2"`. Fixed table, gotcha, and example. using-voice-agent/SKILL.md: - Clarify that reusable configs store the `agent` block only, not `AgentV1Settings`-shaped data. Top-level Settings fields (`audio`, etc.) still go in the live Settings message at connect time.

…v1/read Investigating the SDK more carefully: - SDK type: `TextAnalyzeRequestSummarize = typing.Union[typing.Literal["v2"], typing.Any]` The `Any` branch permits any value - including booleans. - Docstring on `client.read.v1.text.analyze`: 'For Listen API, supports string version option. For Read API, accepts boolean only.' - Wire test at `tests/wire/test_read_v1_text.py` uses `summarize="v2"` on `/v1/read` and the server round-trips it as-is. Both forms work. The previous commit overcorrected in the opposite direction (claiming only "v2" was valid). The skill now shows both are accepted and defaults the quick-start to `summarize=True` to match the documented docstring shape, while noting "v2" also works empirically.

… accepts bool or 'v2' Per the product contract and the `analyze` method docstring ("For Listen API, supports string version option. For Read API, accepts boolean only."): /v1/read — boolean ONLY /v1/listen — boolean OR "v2" (explicit model version) The SDK's shared `TextAnalyzeRequestSummarize = Union[Literal["v2"], Any]` type is wider than what either endpoint actually accepts; the Fern-generated wire test passing `summarize="v2"` on /v1/read is a URL-echo artifact, not proof of semantic support. using-text-intelligence/SKILL.md - Quick-start uses `summarize=True` (Read is bool-only) - Table row now specifies bool-only for /v1/read - Gotcha #3 explicitly states "don't pass 'v2' on /v1/read" and explains the Fern wire-test artifact using-audio-intelligence/SKILL.md - Quick-start keeps `summarize="v2"` with a note that `True` also works - Feature-availability table simplified from `summarize=v2` to `summarize` - Gotcha #1 rewritten to document both forms on /v1/listen and clarify the Read contrast

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-python-speech-to-text using-text-to-speech → deepgram-python-text-to-speech using-text-intelligence → deepgram-python-text-intelligence using-audio-intelligence → deepgram-python-audio-intelligence using-voice-agent → deepgram-python-voice-agent using-conversational-stt → deepgram-python-conversational-stt using-management-api → deepgram-python-management-api maintaining-python-sdk → deepgram-python-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.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…mespace (#4) ## Summary The 9 Deepgram SDK repos now publish their skills under the `deepgram-{lang}-{product}` namespace (e.g. `deepgram-python-speech-to-text` instead of `using-speech-to-text`). This avoids name collisions when installing skills from multiple SDKs. ## Why Previously every SDK published identically-named product skills: ``` deepgram-python-sdk → .agents/skills/using-speech-to-text/SKILL.md deepgram-js-sdk → .agents/skills/using-speech-to-text/SKILL.md deepgram-java-sdk → .agents/skills/using-speech-to-text/SKILL.md … ``` Installing skills from Python and then JS would overwrite the first with the second — users could only have one SDK's skills at a time. ## Changes in this PR - **`README.md`** — replace the hard-coded skill-name list with the namespace pattern + a full example set for the Python SDK. - **`skills/api/SKILL.md`** — document the `deepgram-{lang}-` prefix in the SDK-Specific Skills section; update the `--skill` install example from `using-speech-to-text` → `deepgram-python-speech-to-text`. ## Sibling PRs (one per SDK) Each SDK's `lo/add-agent-skills` PR now includes a follow-up rename commit: | SDK | PR | Rename commit | |---|---|---| | python | [#695](deepgram/deepgram-python-sdk#695) | adds `chore: namespace skill names with deepgram-python-` | | js | [#486](deepgram/deepgram-js-sdk#486) | adds `chore: namespace skill names with deepgram-js-` | | java | [#39](deepgram/deepgram-java-sdk#39) | adds `chore: namespace skill names with deepgram-java-` | | go | [#325](deepgram/deepgram-go-sdk#325) | adds `chore: namespace skill names with deepgram-go-` | | rust | [#153](deepgram/deepgram-rust-sdk#153) | adds `chore: namespace skill names with deepgram-rust-` | | swift | [#2](deepgram/deepgram-swift-sdk#2) | adds `chore: namespace skill names with deepgram-swift-` | | kotlin | [#2](deepgram/deepgram-kotlin-sdk#2) | adds `chore: namespace skill names with deepgram-kotlin-` | | dotnet | [#401](deepgram/deepgram-dotnet-sdk#401) | adds `chore: namespace skill names with deepgram-dotnet-` | | browser | [#12](deepgram/browser#12) | adds `chore: namespace skill names with deepgram-browser-` | Each renames 8 folders, updates every SKILL.md's frontmatter `name`, and updates all sibling-skill cross-references.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 11 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

All 11 new Copilot threads on PR #695: TextBuilder (deepgram-python-text-to-speech): - Fluent API is .text()/.pronunciation()/.pause()/.build(). There is no .add() method. Replaced the example + added a one-line API summary. Management API paths (deepgram-python-management-api): - keys.create takes a single request= payload (CreateKeyV1RequestOne), not top-level comment=/scopes= kwargs. - invites.create is the real method name (no invites.send). - The top-level client.manage.v1.* surface exposes only projects and models; 'requests utilities' are at client.manage.v1.projects.requests. Auth scheme (deepgram-python-speech-to-text + voice-agent): - Previously stated 'Token, not Bearer'. The custom DeepgramClient in src/deepgram/client.py installs an Authorization: Bearer <access_token> override when access_token=... is passed. Gotchas now say: API keys use Token; temporary/access tokens use Bearer. .fernignore sync (audio-intelligence, conversational-stt, voice-agent, maintaining-python-sdk): - Removed claims about listen_v1redact.py and listen/v1|v2/client.py patches — those entries have been removed from .fernignore as Fern output improved. - redact is typed Optional[str] in the current generated SDK; the earlier Union[str, Sequence[str]] patch is not in .fernignore. - listen/v2/socket_client.py is the only patched listen/v2 file. - agent/v1/socket_client.py is temporarily (not permanently) frozen — classification matches .fernignore's comment. - The maintainer-skill 'temporarily frozen' list now mirrors the actual .fernignore contents (4 socket clients + 3 listen_v1response types), with a pointer telling maintainers to re-check .fernignore directly.

Copilot AI review requested due to automatic review settings April 24, 2026 11:55

Copilot started reviewing on behalf of lukeocodes April 24, 2026 11:55 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

lukeocodes added 4 commits April 24, 2026 13:26

lukeocodes requested a review from Copilot April 24, 2026 13:27

Copilot started reviewing on behalf of lukeocodes April 24, 2026 13:27 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

lukeocodes mentioned this pull request Apr 24, 2026

docs: update SDK skill references to new deepgram-{lang}-{product} namespace deepgram/skills#4

Merged

lukeocodes requested review from GregHolmes and Copilot April 24, 2026 16:28

Copilot started reviewing on behalf of lukeocodes April 24, 2026 17:52 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

lukeocodes changed the title ~~chore: add agent skills for product usage and maintenance~~ chore: add agent skills for product usage and maintenance [no-ci] Apr 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

chore: add agent skills for product usage and maintenance [no-ci]#695
lukeocodes wants to merge 7 commits intomainfrom
lo/add-agent-skills

lukeocodes commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lukeocodes commented Apr 24, 2026

Summary

What's included

Layered API references

.fernignore

How to use

List all skills in this SDK

Install one skill to the active agent

Install all 8 to a specific agent (global)

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`.fernignore`