Idempotent API design — safe retries for POST endpoints, idempotency keys,
93
90%
Does it follow best practices?
Impact
100%
10.00xAverage score across 4 eval scenarios
Passed
No known issues
Quality
Discovery
100%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 that clearly defines its scope (idempotent API design), lists specific capabilities (safe retries, idempotency keys, duplicate prevention), and provides explicit trigger conditions. The description uses proper third-person voice and includes both technical terms and problem-oriented language that users would naturally use.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'safe retries for POST endpoints', 'idempotency keys', and 'preventing duplicate orders'. These are concrete, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('safe retries for POST endpoints, idempotency keys, preventing duplicate orders') and when ('Apply AUTOMATICALLY whenever building any POST endpoint that creates resources or triggers side effects'). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'idempotent', 'API', 'retries', 'POST endpoints', 'idempotency keys', 'duplicate orders'. These cover both technical terms and problem descriptions users might mention. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on idempotent API design with distinct triggers like 'idempotency keys', 'POST endpoints', 'duplicate orders'. Unlikely to conflict with general API or coding skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
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, actionable skill with excellent executable code examples and clear workflow guidance. The content successfully teaches idempotency patterns with concrete implementations for server, client, and database layers. Main weakness is length—the document could benefit from splitting detailed implementations into separate files while keeping SKILL.md as a concise overview with references.
Suggestions
Consider moving the detailed server-side middleware implementation to a separate MIDDLEWARE.md file, keeping only a brief example in the main skill
The problem explanation and HTTP method comparison table could be trimmed—Claude understands HTTP semantics
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is comprehensive but includes some unnecessary explanation (e.g., explaining what GET/PUT/DELETE idempotency means, the ASCII diagram of the problem). Some sections could be tightened, though most content earns its place with concrete examples. | 2 / 3 |
Actionability | Excellent executable code examples throughout: complete TypeScript middleware, client-side fetch with retry handling, SQL schema with constraints, and database error handling. All code is copy-paste ready with proper error handling. | 3 / 3 |
Workflow Clarity | Clear multi-step workflow with explicit validation checkpoints: lock-before-process sequence, 409 handling for concurrent requests, and a comprehensive checklist at the end. The 'How it works' section clearly sequences the decision tree. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but it's a long monolithic document (~300 lines). The verifier references at the end are good, but detailed implementations (server middleware, client code, database schema) could be split into separate reference files. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents