deepgram-webhooks

Receive and verify Deepgram webhooks (callbacks). Use when setting up Deepgram webhook handlers, processing transcription callbacks, or handling asynchronous transcription results.

Quality

77%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/deepgram-webhooks/SKILL.md

Quality

Content

64%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a solid, actionable skill with executable code examples and good coverage of Deepgram webhook handling. Its main weaknesses are moderate verbosity (explanatory comments and notes that Claude doesn't need) and a lack of clear sequential workflow with validation checkpoints. The progressive disclosure structure is reasonable but the main file carries more detail than an overview ideally should.

Suggestions

Trim inline comments and explanatory text—remove notes like 'This is NOT your API Key secret' and reduce code comments to essential ones only.

Add a clear numbered workflow at the top: 1) Set up endpoint → 2) Register callback URL → 3) Receive and verify webhook → 4) Process payload → 5) Return 200, with explicit validation/error handling at step 3.

Move the detailed authentication methods, event types table, and important notes sections into reference files (verification.md, event-types.md) and keep only a brief summary in the main SKILL.md.

Dimension	Reasoning	Score
Conciseness	The skill includes some unnecessary explanations (e.g., explaining what webhooks/callbacks are, the comment-heavy code examples, and the 'Note: This is NOT your API Key secret' explanation). The environment variables section and some inline comments could be tightened, but overall it's reasonably efficient.	2 / 3
Actionability	Provides fully executable code examples: a complete Express.js webhook handler, a curl command for making callback requests, middleware for authentication, and a concrete local development setup command. All examples are copy-paste ready with specific headers, status codes, and endpoints.	3 / 3
Workflow Clarity	The skill covers the pieces needed (make request with callback, receive webhook, verify token, process result) but doesn't present them as a clearly sequenced workflow with validation checkpoints. The steps are scattered across sections rather than forming a coherent numbered sequence, and there's no explicit error recovery flow for failed verifications or malformed payloads.	2 / 3
Progressive Disclosure	The Resources section references overview.md, setup.md, verification.md, and examples/ which is good structure, but no bundle files were provided to verify these exist. The main SKILL.md includes substantial inline content (authentication methods, event types table, environment variables, important notes) that could arguably be split into reference files, making the overview heavier than ideal.	2 / 3
	Total	9 / 12 Passed

Description

89%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a solid description with a clear 'Use when' clause and good trigger term coverage specific to Deepgram's webhook/callback ecosystem. The main weakness is that the 'what' portion could be more specific about the concrete actions performed (e.g., signature validation, payload parsing, error handling). Overall it performs well for skill selection purposes.

Suggestions

Expand the capability list with more concrete actions, e.g., 'Receive and verify Deepgram webhooks, validate signatures, parse transcription payloads, and handle callback errors.'

Dimension	Reasoning	Score
Specificity	Names the domain (Deepgram webhooks) and some actions ('receive and verify', 'processing transcription callbacks'), but doesn't list multiple concrete actions like validating signatures, parsing response payloads, handling error callbacks, etc.	2 / 3
Completeness	Clearly answers both 'what' (receive and verify Deepgram webhooks) and 'when' (explicit 'Use when' clause covering setting up handlers, processing callbacks, and handling async results).	3 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'Deepgram', 'webhooks', 'callbacks', 'transcription callbacks', 'asynchronous transcription results', 'webhook handlers'. Good coverage of terms a user working with Deepgram's async API would naturally use.	3 / 3
Distinctiveness Conflict Risk	Very specific niche — Deepgram webhooks specifically. Unlikely to conflict with general webhook skills or other transcription skills due to the explicit 'Deepgram' qualifier and transcription-specific context.	3 / 3
	Total	11 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: hookdeck/webhook-skills
Commit: da37fc7

Reviewed: 18 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.