AGENT SKILL

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

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

  1. Structure: openapi, info, paths, components sections present
  2. Info: title, version fields populated
  3. Paths: Each path has at least one operation (GET/POST/PUT/DELETE/PATCH)
  4. Operations: Each operation has summary, operationId, responses
  5. Responses: Each response has description and content schema
  6. Schemas: All $ref references resolve to components/schemas
  7. Error Responses: 4xx/5xx responses use RFC 7807 ProblemDetail schema
  8. Servers: At least one server entry with url and description
  9. Tags: Operations are tagged for grouping

AsyncAPI 2.6

  1. Structure: asyncapi, info, channels sections present
  2. Info: title, version fields populated
  3. Channels: Each channel has subscribe or publish operation
  4. Messages: Each operation has message with payload schema
  5. Payload: Schema defines type, properties, required fields
  6. Servers: At least one server with protocol (kafka, amqp, etc.)
  7. Components: Reusable schemas defined in components/schemas

Protobuf 3

  1. Syntax: syntax = "proto3" declaration present
  2. Package: package declaration present
  3. Services: At least one service with rpc methods
  4. Messages: Each rpc has request and response message types
  5. Fields: Fields have sequential numbering, no gaps
  6. Options: java_package or 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

review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0