contract-first

Use when multiple consumers and providers must evolve an API or event schema without field drift, integration surprises, or one side silently redefining the interface.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/contract-first/SKILL.md

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is a well-structured, actionable process skill with concrete code at each step, explicit validation checkpoints, feedback loops, and a completion checklist. Its only real weakness is that everything lives inline in one long file with no progressive disclosure to reference files.

Suggestions

Move the detailed code examples (OpenAPI schema, generated-type usage, provider mapping) and/or the Anti-Patterns catalog into one-level-deep reference files (e.g., examples.md, anti-patterns.md) to shorten the core SKILL.md and improve progressive disclosure.

Trim a few explanatory prose passages (e.g., the opening 'This skill governs how teams change a boundary' paragraph) where the section headers already convey the point.

Dimension	Reasoning	Score
Conciseness	The body is efficient and avoids explaining concepts Claude already knows (no 'what is OpenAPI' padding), with punchy principle statements like 'The filename is not important. Authority is.', though at ~285 lines some explanatory prose could still be trimmed.	4 / 5
Actionability	Provides real, executable artifacts at each workflow step (OpenAPI YAML, `npm run generate:api-types`, TypeScript consumer types and a provider `toOrderSummary` mapping), covering the common cases; the snippets are illustrative fragments needing project adaptation rather than fully copy-paste ready, keeping it just below the top anchor.	4 / 5
Workflow Clarity	The Consumer-First Workflow (6 numbered steps) and Contract Change Protocol (7 numbered steps) are clearly sequenced, with explicit validation gates ('Verify the Provider', 'Integrate by Comparing Evidence' before-merge checks), feedback via re-validation, and a Completion Checklist for the complex process.	5 / 5
Progressive Disclosure	Well-organized with clear section headers and a Related Skills pointer list, but the skill is a single ~285-line file with no bundle/reference files, so detailed code examples and anti-patterns are all inlined rather than split into one-level-deep references.	4 / 5
	Total	17 / 20 Passed

Description

70%Weight 40%Scale 1-5

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 is specific and uses a clear 'Use when' trigger with natural domain vocabulary, cleanly answering when to activate the skill. Its main weakness is that the 'what' is expressed as outcomes to avoid rather than concrete actions the skill performs.

Suggestions

Lead with one or two concrete actions the skill performs (e.g., 'Define and verify a single authoritative contract artifact across consumers and providers') before the 'Use when' clause.

Add common synonyms users might say, such as 'contract', 'OpenAPI', or 'protobuf', to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('API or event schema') and one concrete action ('evolve... without field drift'), but frames the skill mostly via anti-outcomes rather than enumerating several discrete actions, so it does not reach the 'lists several specific actions' anchor.	3 / 5
Completeness	Explicitly answers 'when' via the 'Use when multiple consumers and providers must evolve...' clause and conveys the 'what' (collaborative schema evolution without drift), but the 'what' is goal-framed rather than stated as concrete actions, so it stops short of the fully explicit anchor.	4 / 5
Trigger Term Quality	Uses natural terms a practitioner would say ('consumers and providers', 'API or event schema', 'field drift', 'integration surprises') with a 'Use when' trigger, though it omits common synonyms like 'contract', 'OpenAPI', or 'protobuf'.	4 / 5
Distinctiveness Conflict Risk	The trigger (multi-party parallel schema evolution with drift risk) is a distinct niche, with only minor overlap risk against closely related skills like api-design, which the body itself acknowledges as complementary.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: affaan-m/ECC
Path: skills/contract-first/SKILL.md
Commit: d8409a4

Reviewed: 1 day 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.