Content
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent workflow clarity and practical, executable code examples covering multiple frameworks and edge cases. Its main weakness is length—the comprehensive coverage of both verification approaches, multiple frameworks, and idempotency could be better organized through progressive disclosure into supporting files. Minor verbosity in explanatory text could be trimmed.
Suggestions
Extract the Express.js endpoint and manual Svix verification into separate referenced files to reduce the main SKILL.md length and improve progressive disclosure.
Trim the overview paragraph—Claude doesn't need to be told what HMAC-SHA256 is or that Clerk uses Svix; jump straight to the actionable content.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly comprehensive but includes some redundancy—the user.updated handler largely duplicates user.created, and both the verifyWebhook and manual Svix approaches are shown in full when the alternative could be more condensed. The overview sentence explaining what Svix is and what HMAC-SHA256 means is unnecessary for Claude. However, most content earns its place with critical gotchas (req.text() vs req.json()) and practical code. | 2 / 3 |
Actionability | The skill provides fully executable, copy-paste-ready TypeScript code for both Next.js and Express.js, complete with imports, error handling, and database operations. Critical pitfalls are called out inline (e.g., 'Use req.text(), NOT req.json()'). The error handling table and dashboard configuration steps are concrete and specific. | 3 / 3 |
Workflow Clarity | The steps are clearly numbered and sequenced from installation through endpoint creation, event handling, idempotency protection, dashboard configuration, and local testing. Validation is embedded throughout—signature verification acts as the primary checkpoint, idempotency handling addresses retry scenarios, and the error handling table provides a feedback loop for common failures. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and a helpful error table, but it's quite long (~200+ lines of code) and could benefit from splitting the alternative approaches (Express.js, manual Svix) and the idempotency module into separate referenced files. The external resource links at the bottom are good, but there are no bundle files to offload detailed content to. The reference to 'clerk-performance-tuning' is a nice forward pointer. | 2 / 3 |
Total | 10 / 12 Passed |