CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl-labs/api-idempotency

Idempotent API design — safe retries for POST endpoints, idempotency keys,

93

10.00x
Quality

90%

Does it follow best practices?

Impact

100%

10.00x

Average score across 4 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

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.

DimensionReasoningScore

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

DimensionReasoningScore

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Reviewed

Table of Contents