clerk-webhooks

Receive and verify Clerk webhooks. Use when setting up Clerk webhook handlers, debugging signature verification, or handling user events like user.created, user.updated, session.created, or organization.created.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

63%Weight 40%Scale 1-5

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

The core technical content — two complete verification implementations with in-code validation, an event table, and env-var guidance — is genuinely actionable. Its weaknesses are padding from promotional link sections, a partially incomplete FastAPI example, and dangling examples/* references that undermine the otherwise good progressive-disclosure structure.

Suggestions

Fix or remove the examples/express/, examples/nextjs/, and examples/fastapi/ links — either bundle those example directories or drop the 'For complete working examples with tests' block, since the paths do not exist and mislead navigation.

Trim the 'Related Skills' section (10 links), the external 'Recommended: webhook-handler-patterns' link list, and the attribution boilerplate — roughly 45 lines of non-task content that compete with the context window.

Complete the FastAPI example: add `app = FastAPI()`, a null/whsec_ check on the secret mirroring the Express version, and at least one concrete event-handling branch instead of the '# Handle event...' placeholder.

Dimension	Reasoning	Score
Conciseness	The code, event table, and env-var sections are lean and earn their tokens, but ~45 lines of non-task padding (the 10-link 'Related Skills' list, external 'Recommended' skill links, and the attribution block) are unnecessary explanation that could be trimmed — matching 'mostly efficient but includes some unnecessary explanation' rather than anchor 4's 'minor instances'.	3 / 5
Actionability	The Express handler is copy-paste ready with correct svix-to-webhook header mapping and error paths, but the FastAPI snippet is not fully executable (no `app = FastAPI()` instantiation, no null-check on the secret, and it ends at a '# Handle event...' placeholder), which is a minor gap against the fully-executable anchor 5.	4 / 5
Workflow Clarity	The verify-then-handle sequence embeds explicit validation checkpoints (missing-header 400s, signature verification, 5-minute timestamp window, error responses), and the Local Development section gives ordered steps, but there is no explicit numbered end-to-end setup sequence, leaving a minor validation gap versus anchor 5.	4 / 5
Progressive Disclosure	The four references/*.md files exist, are one level deep, and are clearly signaled, but the 'complete working examples' block points to examples/express/, examples/nextjs/, and examples/fastapi/ — paths that do not exist in the bundle — so navigation breaks exactly where a user is directed for working code; this is more than the 'minor organization gaps' of anchor 4.	3 / 5
	Total	14 / 20 Passed

Description

87%Weight 40%Scale 1-5

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

A strong description: concrete actions, explicit 'Use when' triggers with real event names, and a clearly bounded Clerk niche. The only weakness is modest keyword coverage — natural variants like 'svix' or 'webhook secret' are missing.

Dimension	Reasoning	Score
Specificity	"Receive and verify Clerk webhooks" plus the setup/debug/handle-events actions name several concrete capabilities, but coverage gaps (e.g., payload parsing, idempotency, endpoint configuration detail) keep it below the comprehensive anchor 5; it clearly exceeds anchor 3's '1-2 concrete actions, not comprehensive'.	4 / 5
Completeness	It explicitly answers what ("Receive and verify Clerk webhooks") and when ("Use when setting up... debugging... or handling user events like...") with concrete trigger phrases, matching the anchor-5 example structure exactly; anchor 4's 'when could be more explicit' does not apply.	5 / 5
Trigger Term Quality	Natural phrases like "setting up Clerk webhook handlers", "debugging signature verification", and concrete event names (user.created, session.created) match what users would say, but common variants such as "svix" or "webhook secret" are absent, so it falls between good (4) and comprehensive (5) coverage.	4 / 5
Distinctiveness Conflict Risk	The Clerk-specific trigger terms carve out a clear niche with minimal conflict risk against sibling webhook skills (stripe-webhooks, github-webhooks, etc.), since a query would need to mention Clerk or its event types to match.	5 / 5
	Total	18 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 3 missing	Warning

	Total	15 / 16 Passed

Repository: hookdeck/webhook-skills
Path: skills/clerk-webhooks/SKILL.md
Commit: 1b5cbf0

Reviewed: 6 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.