x-lint-contract-tests
Validates API contracts (OpenAPI 3.1, AsyncAPI 2.6, Protobuf 3) against their specifications. Reports structural errors, missing fields, and spec violations.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-lint-contract-tests
- description
- Validates API contracts (OpenAPI 3.1, AsyncAPI 2.6, Protobuf 3) against their specifications. Reports structural errors, missing fields, and spec violations.
- allowed-tools
- Read, Grep, Glob, Bash
- argument-hint
- [contract-file-path]
- user-invocable
- true
- requires-capabilities
- []
02 资源文件 1
- 参考文档README.md1.5 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Contract Lint
Purpose
Validate API contracts before approval. Check OpenAPI 3.1, AsyncAPI 2.6, or Protobuf 3 specs for structural errors, missing fields, and specification violations.
Activation Condition
Include this skill when the project uses API contracts (OpenAPI, AsyncAPI, or Protobuf).
Triggers
/x-lint-contract-tests path/to/contract-openapi.yaml-- validate an OpenAPI contract/x-lint-contract-tests path/to/service.proto-- validate a Protobuf contract/x-lint-contract-tests path/to/events-asyncapi.yaml-- validate an AsyncAPI contract
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
contract-file-path |
String | Yes | (none) | Path to the contract file to validate |
Workflow
Step 1 — Detect Contract Format
Detect the contract format from the file extension and content:
| File Pattern | Format | Spec Version |
|---|---|---|
*-openapi.yaml |
OpenAPI | 3.1 |
*.proto |
Protobuf | 3 |
*-asyncapi.yaml |
AsyncAPI | 2.6 |
Step 2 — Validate Contract
OpenAPI 3.1
- Structure:
openapi,info,paths,componentssections present - Info:
title,versionfields populated - Paths: Each path has at least one operation (GET/POST/PUT/DELETE/PATCH)
- Operations: Each operation has
summary,operationId,responses - Responses: Each response has
descriptionandcontentschema - Schemas: All
$refreferences resolve tocomponents/schemas - Error Responses: 4xx/5xx responses use RFC 7807 ProblemDetail schema
- Servers: At least one server entry with
urlanddescription - Tags: Operations are tagged for grouping
AsyncAPI 2.6
- Structure:
asyncapi,info,channelssections present - Info:
title,versionfields populated - Channels: Each channel has
subscribeorpublishoperation - Messages: Each operation has
messagewithpayloadschema - Payload: Schema defines
type,properties,requiredfields - Servers: At least one server with
protocol(kafka, amqp, etc.) - Components: Reusable schemas defined in
components/schemas
Protobuf 3
- Syntax:
syntax = "proto3"declaration present - Package:
packagedeclaration present - Services: At least one
servicewithrpcmethods - Messages: Each
rpchas request and response message types - Fields: Fields have sequential numbering, no gaps
- Options:
java_packageor language-specific options present
Step 3 — Generate Report
CONTRACT LINT REPORT
====================
File: {contract-path}
Format: {format} {version}
Status: VALID | INVALID
Errors ({count}):
- [E001] {description} at {location}
- [E002] {description} at {location}
Warnings ({count}):
- [W001] {description} at {location}
Summary: {count} errors, {count} warnings
Error Handling
| Scenario | Action |
|---|---|
| Contract file not found | Report error with provided path |
| Unrecognized file format | Report unsupported format with list of supported formats |
| Validation errors found | Report INVALID status with all errors listed; errors block contract approval |
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
| x-implement-story | called-by | Invoked by Phase 0.5 (Step 0.5.3) for contract validation before approval |
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.