idempotency-handling
Idempotent API operations with idempotency keys, Redis caching, DB constraints. Use for payment systems, webhook retries, safe retries, or encountering duplicate processing, race conditions, key expiry errors.
79
73%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/idempotency-handling/skills/idempotency-handling/SKILL.mdQuality
Discovery
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 strong skill description with excellent trigger term coverage and clear completeness via the explicit 'Use for' clause. Its main weakness is that it describes components and technologies rather than listing specific concrete actions the skill performs. The description is concise and well-targeted to its niche.
Suggestions
Replace or supplement the component list with concrete actions, e.g., 'Implements idempotent API endpoints using idempotency keys, configures Redis-based response caching, adds DB uniqueness constraints to prevent duplicate processing.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (idempotent API operations) and mentions specific technologies (Redis caching, DB constraints, idempotency keys), but doesn't list concrete actions like 'implement idempotency key generation' or 'add duplicate detection middleware'. It describes components rather than actions. | 2 / 3 |
Completeness | Clearly answers both 'what' (idempotent API operations with idempotency keys, Redis caching, DB constraints) and 'when' (explicit 'Use for' clause listing payment systems, webhook retries, safe retries, duplicate processing, race conditions, key expiry errors). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would use: 'payment systems', 'webhook retries', 'safe retries', 'duplicate processing', 'race conditions', 'key expiry errors', 'idempotency keys', 'Redis caching'. These are terms developers would naturally mention when facing these problems. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche combining idempotency, Redis caching, and DB constraints specifically for API operations. The trigger terms like 'idempotency keys', 'duplicate processing', and 'race conditions' in this combination are unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides strong, executable code examples for both Redis and database-backed idempotency patterns, making it highly actionable. However, it suffers from verbosity—particularly the triple-language cleanup section and explanatory lists—and lacks progressive disclosure structure. The workflow could be more explicitly sequenced with validation checkpoints rather than relying on code comments to convey the process.
Suggestions
Move the cleanup strategies (3 language variants + best practices) to a separate CLEANUP.md file and reference it from the main skill, keeping only one example inline.
Remove the 'When to Apply' section—the skill description already covers this, and Claude can infer appropriate use cases.
Add an explicit numbered workflow at the top showing the implementation sequence: 1) Choose pattern (Redis vs DB), 2) Implement key generation, 3) Add middleware/handler, 4) Verify with duplicate request test, 5) Set up cleanup.
Consolidate cleanup examples to a single language to reduce token usage, or move alternatives to a referenced file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core patterns (Redis middleware, DB-backed idempotency) are well-presented, but the cleanup section is overly verbose with three language variants and extensive best practices that pad the content. The 'When to Apply' list and some comments explain things Claude already knows. | 2 / 3 |
Actionability | Provides fully executable code for both Redis-based and database-backed idempotency patterns, including SQL schema, JavaScript middleware, and the complete processPayment function with all edge cases handled. Code is copy-paste ready. | 3 / 3 |
Workflow Clarity | The database-backed pattern implicitly shows a workflow (insert → process → update status), but there's no explicit sequenced workflow for implementing idempotency end-to-end. The race condition handling is embedded in code rather than called out as validation checkpoints. No explicit verification steps for testing that idempotency actually works. | 2 / 3 |
Progressive Disclosure | All content is in a single monolithic file with no references to external files. The cleanup section alone with three language variants could be split out. The DB schema, middleware, and cleanup strategies would benefit from being organized into separate referenced files. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
100%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
- secondsky/claude-skills
- Commit
88da5ff
- Reviewed
Table of Contents
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.