chore: add agent skills for product usage and maintenance [no-ci]#39
Merged
Conversation
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-java-sdk — Java SDK maintenance workflow Each skill includes authentication, quick-start with real Java 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.
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.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds agent-agnostic “skills.sh” skill documents to this SDK repo so external agent tools (via npx skills) can discover product usage and maintenance guidance, and updates Fern regeneration ignore rules so the new agent content is preserved.
Changes:
- Add 8 new skill documents under
.agents/skills/covering Deepgram products and Java SDK maintenance. - Update
.fernignoreto freeze agent-related files/directories so they survive Fern regeneration.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
.fernignore |
Adds agent-related paths to the Fern ignore list to prevent regeneration from overwriting them. |
.agents/skills/using-voice-agent/SKILL.md |
Documents Voice Agent WebSocket usage patterns and repo example entry points. |
.agents/skills/using-text-to-speech/SKILL.md |
Documents Speak (TTS) REST and WebSocket usage in the Java SDK. |
.agents/skills/using-text-intelligence/SKILL.md |
Documents Read (Text Intelligence) request/response patterns and options. |
.agents/skills/using-speech-to-text/SKILL.md |
Documents Listen v1 REST + WebSocket transcription usage and options. |
.agents/skills/using-management-api/SKILL.md |
Documents Manage API usage (projects/models/keys/members/usage/billing) and related SDK paths. |
.agents/skills/using-conversational-stt/SKILL.md |
Documents Listen v2 (Flux) WebSocket usage and turn events. |
.agents/skills/using-audio-intelligence/SKILL.md |
Documents enabling intelligence overlays on Listen v1 REST (and subset on WS). |
.agents/skills/maintaining-java-sdk/SKILL.md |
Documents Fern regen workflow and freeze/unfreeze practices specific to this repo. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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-java-speech-to-text using-text-to-speech → deepgram-java-text-to-speech using-text-intelligence → deepgram-java-text-intelligence using-audio-intelligence → deepgram-java-audio-intelligence using-voice-agent → deepgram-java-voice-agent using-conversational-stt → deepgram-java-conversational-stt using-management-api → deepgram-java-management-api maintaining-java-sdk → deepgram-java-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.
lukeocodes
added a commit
to deepgram/skills
that referenced
this pull request
Apr 24, 2026
…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.
…olish All 5 Copilot threads: - .fernignore: add trailing slashes on .claude/ and .agents/ to match the file's dir/ convention. Add a comment explaining that CLAUDE.md is a defensive entry (file may not exist in every checkout). - deepgram-java-speech-to-text/SKILL.md: guard channels + alternatives against empty results before indexing, matching the pattern in examples/listen/TranscribeUrl.java. Prevents IndexOutOfBoundsException on empty/quiet audio. - deepgram-java-text-to-speech/SKILL.md: close the FileOutputStream in an onDisconnected handler (previously leaked the file handle); log IO errors in the audio callback rather than rethrowing RuntimeException from the WebSocket thread. Matches examples/speak/StreamingTts.java. - deepgram-java-management-api/SKILL.md: guard projects.isEmpty() before indexing projects.get(0) — new accounts may have zero projects.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
deepgram-java-voice-agent/SKILL.md gotcha #5 previously asserted that provider config is 'strongly typed'. The wrappers (OpenAiThinkProvider, AnthropicThinkProvider, etc.) produce a union variant but the underlying payload is Object, so provider-field mistakes aren't caught at compile time. Rewritten to describe the actual shape (sealed-union wrappers around Object payloads) so readers don't rely on non-existent field-level type safety.
lukeocodes
changed the title
GregHolmes
approved these changes
Apr 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds 8 agent-agnostic skills under
.agents/skills/following the skills.sh convention. Discoverable by OpenCode, Claude Code, Codex, Cursor, and 40+ other agent tools vianpx skills.What's included
All skills are namespaced with a
deepgram-java-prefix to avoid collisions when a user installs skills from multiple Deepgram SDKs:deepgram-java-speech-to-text/v1/listenREST + WSSdeepgram-java-text-to-speech/v1/speakREST + WSSdeepgram-java-text-intelligence/v1/readRESTdeepgram-java-audio-intelligence/v1/listenw/ analyticsdeepgram-java-voice-agentagent.deepgram.com/v1/agent/converseWSSdeepgram-java-conversational-stt/v2/listenFlux WSSdeepgram-java-management-api1 maintainer skill:
deepgram-java-maintaining-sdk.How to use
.fernignore
Added
.agents/so Fern regeneration won't wipe these skills.Sibling PRs in the other Deepgram SDKs: python, js, go, rust, swift, kotlin, dotnet, browser.