validating-api-responses
Validate API responses against schemas to ensure contract compliance and data integrity. Use when ensuring API response correctness. Trigger with phrases like "validate responses", "check API responses", or "verify response format".
59
51%
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/api-development/api-response-validator/skills/validating-api-responses/SKILL.mdQuality
Discovery
82%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 reasonably well-constructed description that clearly communicates both what the skill does and when to use it, with explicit trigger phrases. Its main weaknesses are moderate specificity—it could enumerate more concrete actions beyond 'validate'—and some potential overlap with adjacent API testing or schema validation skills. The inclusion of both a 'Use when' clause and a 'Trigger with' clause is a strength.
Suggestions
Add more specific concrete actions beyond 'validate', e.g., 'compare response fields against OpenAPI/JSON Schema specs, flag missing required fields, detect type mismatches, report unexpected properties'
Improve distinctiveness by specifying supported schema formats (e.g., JSON Schema, OpenAPI, GraphQL) to differentiate from general API testing or contract testing skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (API responses, schemas) and a core action (validate against schemas), but doesn't list multiple concrete actions beyond validation. 'Ensure contract compliance and data integrity' is somewhat abstract rather than describing specific operations like 'compare response fields to OpenAPI spec, flag missing required fields, detect type mismatches.' | 2 / 3 |
Completeness | Clearly answers both 'what' (validate API responses against schemas for contract compliance and data integrity) and 'when' (explicit 'Use when' clause and 'Trigger with phrases like' clause providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes natural trigger phrases users would say: 'validate responses', 'check API responses', 'verify response format', plus terms like 'schema', 'contract compliance', and 'data integrity'. Good coverage of how users would naturally phrase this need. | 3 / 3 |
Distinctiveness Conflict Risk | Fairly specific to API response validation against schemas, but could overlap with general API testing skills, schema validation skills, or contract testing skills. The scope is narrowed to responses specifically, but 'contract compliance' and 'data integrity' are broad enough to cause some overlap. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
20%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a high-level architecture document than an actionable skill for Claude. It describes what to build at a conceptual level but provides no executable code, concrete commands, or specific implementation patterns. The verbose explanations of well-known concepts waste token budget while the lack of actual code examples undermines the skill's core purpose of teaching Claude how to validate API responses.
Suggestions
Replace abstract instructions ('Implement response validation middleware') with concrete, executable code examples showing actual middleware implementation with a JSON Schema validator like Ajv.
Remove the prerequisites section and error handling explanations of basic concepts (type mismatches, null values) that Claude already understands — instead, provide a concise code snippet showing how to configure strict validation.
Add at least one complete, copy-paste-ready example showing end-to-end response validation (loading a schema, validating a response, handling failures).
Provide the referenced bundle files (implementation.md, errors.md, examples.md) or inline the critical implementation details to make the skill self-contained and actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is verbose and explains many concepts Claude already knows (what OpenAPI is, what JSON Schema validators are, what different HTTP status codes mean). The prerequisites section lists obvious tooling, and the instructions read like a tutorial rather than actionable directives. The error handling table explains basic concepts like type mismatches and null values that Claude understands natively. | 1 / 3 |
Actionability | Despite being lengthy, the skill contains zero executable code, no concrete commands, and no copy-paste-ready examples. Every instruction is abstract and descriptive ('Implement response validation middleware', 'Build a contract test suite') rather than providing actual implementation. The examples section describes scenarios conceptually without any code. | 1 / 3 |
Workflow Clarity | The 8 steps are sequenced logically and cover a reasonable workflow from reading specs to generating reports. However, there are no validation checkpoints or feedback loops — no step says 'verify this worked before proceeding' — and for a process involving middleware integration and CI pipeline changes, this is a significant gap. | 2 / 3 |
Progressive Disclosure | The skill references external files (implementation.md, errors.md, examples.md) which is good structure, but no bundle files are provided, making these references dead links. The main content itself is still quite long and could benefit from moving the error handling table and detailed instructions to reference files, keeping SKILL.md as a concise overview. | 2 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
3a2d27d
- 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.