Content
75%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.
A strong, dense single-file walkthrough: five end-to-end scenarios with executable-ish code, explicit polling validation, a valuable anti-patterns checklist, and honest limitations. Weaknesses are minor: undefined helper functions, a slightly padded Overview and repeated citation phrasing, and a monolithic structure that inlines reference-grade tables instead of splitting them out.
Suggestions
Define the helper functions used in the code samples (toEpoch, waitForClockReady, getLatestInvoice) once, or inline their short implementations, so the examples are fully copy-paste executable.
Trim the Overview's re-explanation of subscription billing basics and consolidate the repeated 'Per docs.stripe.com/...' preambles into the final References section to save context tokens.
Move the webhook event matrix and CI integration YAML into references/ files (e.g., references/webhook-event-matrix.md) linked from short SKILL.md sections, so the main file stays an overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is non-obvious, Stripe-test-specific gotchas (poll clock until 'ready', 'canceled' is terminal, same proration_date for preview and update, retry-cycle testing), but minor over-explanation could be trimmed: the Overview re-explains subscription billing basics, and the 'Per docs.stripe.com/...' citation preamble repeats ~12 times. Not 5 because of that padding; not 3 since most tokens carry information Claude cannot be assumed to already know. | 4 / 5 |
Actionability | Near-executable TypeScript for every scenario plus concrete bash/YAML for CLI and CI, but helper functions (toEpoch, waitForClockReady, getLatestInvoice) and constants (PRICE_ID, NEW_PRICE_ID) are referenced without definitions, so code is not fully copy-paste ready. Matches the 'mostly executable with minor gaps' anchor. | 4 / 5 |
Workflow Clarity | Steps 1-6 are clearly sequenced with an explicit validation checkpoint ('Poll until clock.status === ready before asserting', reinforced in the anti-patterns table) and a dunning-recovery path. Not 5 because there is no error-recovery feedback loop (e.g., what to do when an advance fails or the clock errors), which the top anchor expects. | 4 / 5 |
Progressive Disclosure | Well-organized sections with clear headers, a clearly signaled References section, and no nested or buried references. Not 5 because the 345-line single file has no bundle split at all: the 9-row webhook event matrix and CI YAML are reference-shaped content inlined in SKILL.md rather than one-level-deep reference files. | 4 / 5 |
Total | 16 / 20 Passed |