api-contract

API Contract Agent. OpenAPI 스펙 정의, Mock Server 생성, Contract-First 개발을 담당합니다. Frontend/Backend 간 API 계약을 관리합니다.

Quality

45%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/api-contract/SKILL.md

Quality

Discovery

32%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear domain (API contract management with OpenAPI) and lists relevant capabilities, but lacks explicit trigger guidance for when Claude should use this skill. The technical terminology is appropriate but could benefit from more user-friendly variations and common synonyms.

Suggestions

Add a 'Use when...' clause with explicit triggers like 'Use when the user asks about OpenAPI specs, swagger files, API mocking, or contract-first development'

Include common user terms and file extensions such as 'swagger', '.yaml', '.json', 'API documentation', 'API schema'

Add more specific concrete actions like 'validate API schemas', 'generate client/server stubs', 'compare API versions'

Dimension	Reasoning	Score
Specificity	Names the domain (API/OpenAPI) and lists some actions (스펙 정의, Mock Server 생성, Contract-First 개발), but the actions are somewhat high-level and not fully concrete or comprehensive.	2 / 3
Completeness	Describes what it does but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing explicit trigger guidance caps completeness at 2, and this has no trigger guidance at all.	1 / 3
Trigger Term Quality	Includes relevant technical terms like 'OpenAPI', 'Mock Server', 'Contract-First', 'API 계약', but missing common user variations like 'swagger', 'API spec', 'API documentation', or file extensions like '.yaml', '.json'.	2 / 3
Distinctiveness Conflict Risk	The OpenAPI and Contract-First focus provides some distinction, but 'API 계약을 관리합니다' is broad enough to potentially overlap with general API development or documentation skills.	2 / 3
	Total	7 / 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.

This skill provides highly actionable, executable examples for Contract-First API development with OpenAPI, Mock servers, and Contract testing. However, it suffers from being a monolithic document that could benefit from splitting detailed examples into separate files. The workflow lacks explicit validation checkpoints and error recovery guidance.

Suggestions

Split the detailed OpenAPI YAML example, MSW handlers, and Pact tests into separate reference files (e.g., OPENAPI-TEMPLATE.md, MSW-HANDLERS.md, PACT-TESTS.md) and link from the main skill

Add explicit validation steps in the workflow: after writing spec run 'npx @redocly/cli lint', if errors fix and re-lint before proceeding to Mock Server generation

Remove or condense the ASCII diagram and Contract-First explanation - Claude understands these concepts; focus on the project-specific conventions and file locations

Dimension	Reasoning	Score
Conciseness	The skill provides comprehensive examples but includes some verbose sections. The ASCII diagram and extensive YAML examples could be trimmed since Claude understands OpenAPI structure. The basic concepts like 'Contract-First 원칙' explanation adds bulk without unique value.	2 / 3
Actionability	Excellent executable examples throughout - complete OpenAPI YAML specs, working Prism commands, MSW handlers with full TypeScript code, Pact test examples, and CLI commands for validation and type generation. All code is copy-paste ready.	3 / 3
Workflow Clarity	The Contract-First flow diagram shows the overall process, but lacks explicit validation checkpoints between steps. The checklists at the end are helpful but don't integrate into the workflow with feedback loops for error recovery when specs fail validation.	2 / 3
Progressive Disclosure	This is a monolithic document with no references to external files for detailed content. The extensive OpenAPI example, MSW handlers, and Pact tests could be split into separate reference files. Everything is inline creating a wall of content.	1 / 3
	Total	8 / 12 Passed

Validation

90%

Warnings & errors only

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
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	10 / 11 Passed

Repository: shaul1991/shaul-agents-plugin
Commit: 9242c58

Reviewed: 29 days ago

Table of Contents

Discovery Implementation Validation

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.