api-contract-auditor

What This Skill Does

The api-contract-auditor is a specialized OpenClaw agent skill designed to act as a rigorous quality gate for API lifecycle management. Its core function is to systematically audit API documentation, request/response examples, and schema definitions to ensure internal consistency. By leveraging predefined standards (spec.json) and flexible templates (template.md), it identifies discrepancies before they reach the development or testing phase. The skill focuses on detecting breaking changes, verifying schema adherence, and ensuring that documentation accurately reflects the underlying API contract. It serves as an essential tool for architects and developers to maintain documentation integrity and avoid costly runtime errors caused by unexpected schema deviations.

Installation

To install this skill, use the ClawHub command-line tool within your OpenClaw environment: clawhub install openclaw/skills/skills/52yuanchangxing/api-contract-auditor Ensure your working directory has access to the standard {baseDir}/resources/ structure, as the auditor relies on the included spec.json and template.md files to generate its reports.

Use Cases

This skill is ideal for:

1. Pre-deployment audit: Scanning updated OpenAPI specifications to identify potential breaking changes before they are committed.
2. Documentation validation: Ensuring that manual API document updates match the implemented field types, required constraints, and example payloads.
3. Team standard enforcement: Automatically checking if new API definitions comply with company-wide architectural standards defined in the resources folder.
4. Change impact analysis: Assessing how a proposed field change in a service impact downstream consumers by checking against existing documentation.

Example Prompts

1. "Audit the following OpenAPI YAML against our team standard: [Paste YAML content]. Focus specifically on breaking changes for existing fields."
2. "Compare the API response example provided at [URL/Path] with the field definitions in our swagger file. Are there any missing fields or type mismatches?"
3. "Run a full contract audit for the user service based on the current spec.json and provide a list of high-risk breaking changes."

Tips & Limitations

• Safety First: This tool is a read-only auditor. It does not possess the authority to modify production code, update live API gateways, or push changes to configuration files.
• Context is Key: The accuracy of the auditor depends on the quality of your {baseDir}/resources/spec.json. Keep this file updated to reflect your current API standards.
• Not a Test Runner: While it identifies risks, it does not replace functional contract testing. Use this skill as a static analysis phase in your pipeline, followed by dynamic contract testing.
• Partial Data: If you provide incomplete documentation, the skill will output a list of '待确认项' (Items to Confirm) rather than guessing, ensuring you maintain control over the audit results.