feat: improve 5 lowest-scoring skill definitions

[rohan-tessl]

Hey @deepgram 👋

I ran your skills through tessl skill review at work and found targeted improvements in your skills. Here's the before/after:

Skill	Before	After	Change
deepgram-js-text-intelligence	10%	90%	+80%
deepgram-js-text-to-speech	89%	100%	+11%
deepgram-js-audio-intelligence	90%	100%	+10%
deepgram-js-voice-agent	86%	90%	+4%
deepgram-js-management-api	86%	90%	+4%

These were easy changes to bring the skill's structure and activation in line with what performs well against Anthropic's best practices. text-intelligence had unquoted YAML with special characters that broke parsing (10% score). Trimmed verbose sections, added workflows and error handling.

In addition, I stress-tested your deepgram-js-management-api skill against a few real-world scenarios, and it held up really well. This means that your skill meaningfully improves agent steering and contributes to stronger output quality. Kudos for that!

Honest disclosure, I work at @tesslio where we build tooling around skills like these. Not a pitch, just saw room for improvement and wanted to contribute.

If you want to self-improve your skills, or define your own scenarios to pressure test, just ask your agent (Claude Code, Codex, etc.) to evaluate and optimize your skill with Tessl. Ping me @rohan-tessl, if you hit any snags.

[lukeocodes]

@GregHolmes check this out! :o

[lukeocodes]

love this less-is-more approach!

[rohan-tessl]

@GregHolmes following up on @lukeocodes's ping from a couple weeks back the same change is shipped across all four Deepgram SDKs:

• JS feat: improve 5 lowest-scoring skill definitions #498 — approved by @lukeocodes, CI green, ready to merge
• Python #708 — approved by @lukeocodes, ready to merge
• Java #53 — approved by @lukeocodes but still shows REVIEW_REQUIRED (likely needs a CODEOWNERS sign-off)
• Go #331 — approved by @lukeocodes but still shows REVIEW_REQUIRED

Happy to wait if there's a release window or batching reason, just wanted to flag in case they slipped off the queue. Let me know if you'd like any tweaks before merge, or who to loop in for the second sign-off on Java/Go.

[GregHolmes]

Hi @rohan-tessl, thank you for taking the time to suggest these changes. The YAML parse fix on text-intelligence is a genuine catch (I confirmed its frontmatter fails to load with js-yaml on main), and the new Workflow / error-handling sections are solid additions.

Two things your changes remove that I believe we need to restore in audio-intelligence before this merges, both were removed in this PR:

1. The ## Authentication block. All seven deepgram-js-* skills carry the same client-setup block, and each skill loads in isolation. Dropping it here leaves an agent using audio-intelligence with no cue that it needs DEEPGRAM_API_KEY or how to construct deepgramClient, even though every deepgramClient.listen.v1... snippet below assumes it. Please re-add it verbatim from the siblings, between the intro and ## Quick start — REST with analytics:

require("dotenv").config();

const { DeepgramClient } = require("@deepgram/sdk");

const deepgramClient = new DeepgramClient({
  apiKey: process.env.DEEPGRAM_API_KEY,
});

2. The diarization-quality gotcha. This line was dropped:

Diarization quality depends on audio quality and duration. Short or noisy clips churn speakers.

It's product/runtime knowledge an agent can't infer from the types or examples, and it lives only in this skill — no sibling carries it — so removing it loses it from the skill set entirely. Please keep it in the Gotchas list.

Everything else looks good to merge once those two are back.

[rohan-tessl]

Thanks @GregHolmes both points are fair, will restore them.

1. Re-adding the ## Authentication block verbatim between the intro and ## Quick start — REST with analytics so the skill stands on its own when loaded in isolation.
2. Putting the diarization-quality gotcha back in the Gotchas list — agreed it's product knowledge that doesn't live anywhere else in the skill set.

Will push the restore in a moment.