Content
57%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a dense, highly actionable API reference with executable examples across languages and thoughtful extras (anti-patterns, checklists, env var patterns). Its main weaknesses are its monolithic single-file structure — no progressive disclosure despite reference-worthy volume — and missing validation/feedback loops for its batch and sync workflows.
Suggestions
Split the long-tail reference material (campaigns, flows, webhook topics, filtering/sorting, pagination) into references/ files (e.g., references/api-reference.md, references/events.md) and keep SKILL.md as a concise overview with clearly signaled one-level-deep links.
Add validation checkpoints and feedback loops to the batch/sync workflows, e.g., verify the tracked event appears via GET /events after syncOrderToKlaviyo, and retry/rollback guidance for bulk list operations.
Remove the 'Why Klaviyo' marketing benefits table and other non-instructional padding, and fix internal inconsistencies such as the undefined getProfileIdByEmail helper and the WEBHOOK_SECRET vs KLAVIYO_WEBHOOK_SECRET mismatch.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is almost entirely executable code with almost no padded conceptual explanation, but the "Why Klaviyo" benefits table is marketing fluff and the ~800-line inline API reference (campaigns, flows, filtering, pagination, webhooks) could be substantially tightened or trimmed, matching 'mostly efficient but could be tightened'. | 3 / 5 |
Actionability | Concrete, mostly copy-paste-ready TypeScript, Python, HTTP, and client-side examples cover the common cases (profile upsert, e-commerce events, list management, webhook verification, rate-limit retry, cursor pagination), but there are minor gaps: getProfileIdByEmail is called in the order-sync pattern but never defined, and the Express handler uses WEBHOOK_SECRET while the env docs define KLAVIYO_WEBHOOK_SECRET. | 4 / 5 |
Workflow Clarity | A rough setup → integration → testing sequence exists via the checklists and the numbered order-sync pattern, and the testing checklist includes 'Verify events in Klaviyo dashboard', but batch operations (bulk addToList, getAllProfiles pagination, webhook-driven sync) lack validation checkpoints and feedback loops, capping workflow clarity at 3. | 3 / 5 |
Progressive Disclosure | There are no references/, scripts/, or assets/ bundle files, and roughly 800 lines of API reference that clearly belongs in separate files is fully inlined; section headers are well-organized so it is above 'minimal structure', matching 'some structure but content that should be separate is inline'. | 3 / 5 |
Total | 13 / 20 Passed |