skills.rest
Jin9
Jin9COMMUNITY
Explore all skills by this author →
GitHub

universal-spec-validator

Validate agent tool schemas and specs as a CI gate blocking unsafe or breaking changes.

Updated Apr 26, 2026
Search Tags:#pre-commit#schema validation#json schema#backward compatibility#mcp tools#ci gate#command safety
One-click install
npx skills add https://github.com/Jin9/skillify-foundation --skill universal-spec-validator-jin9
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: universal-spec-validator
Source: https://github.com/Jin9/skillify-foundation/tree/main/treasury/universal-spec-validator
Command: npx skills add https://github.com/Jin9/skillify-foundation --skill universal-spec-validator-jin9

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? Malformed tool schemas, unsafe command surfaces, and breaking schema changes can silently reach AI agents in production, causing malformed tool calls, data corruption, or dangerous autonomous actions. This Skill adds a deterministic CI/pre-commit enforcement gate that fails the build before those specs ship. ## Core Features & Use Cases - Three-axis validation: Detects cross-model portability drift (OpenAI/Anthropic/Gemini dialect lock-in, strict-mode incompatibility), unsafe command surfaces (destructive commands, over-broad permissions, injection-exposed fields, missing HITL gates), and breaking schema evolution versus a baseline spec. - Risk-tiered gating: Maps severity to gate actions via .spec-validator.yaml so critical/high findings block the build while warnings and info findings stay exit-neutral, avoiding blanket build kills. - Machine and human reports: Emits spec-validation.json and spec-validation.md with per-finding axis, severity, locator, and rule references, plus exit codes 0/1/2 for direct CI wiring. - Use Case: Before merging a pull request that changes an MCP tool manifest, run the gate against the new spec with the previously shipped spec as baseline; the build fails if a required field was added without a default or a destructive command pattern was introduced. ## Quick Start Ask the agent to run the spec-validation gate on your tool schema files with the previously shipped spec as the baseline and wire the exit code into your CI pipeline.

Frequently Asked Questions about universal-spec-validator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a schema validation gate to CI for tool specs?▼

Run scripts/validate_spec.py with your spec files or globs, optionally passing --baseline and --config, and wire its exit code into a CI job step or pre-commit hook. Exit code 1 means at least one blocking finding, so the pipeline fails automatically.

How do I check if a tool schema change is backward compatible?▼

Pass the previously shipped spec via --baseline and the new spec as the target. The gate diffs top-level properties and flags removed fields, type changes, new required fields without defaults, narrowed enums, and optional-to-required flips as breaking under the configured compatibility mode.

What spec formats does the validator support?▼

It accepts JSON Schema tool or function definitions, MCP tool manifests, OpenAPI tool definitions, SKILL.md frontmatter, and JSON or YAML data contracts. Files are parsed as JSON or YAML, and unparseable structured specs cause a fail-closed exit code 2.

Can I downgrade or suppress specific validation rules?▼

Yes, the .spec-validator.yaml config supports gate_overrides to remap a rule's gate to block, warn, or info, and an ignore list to suppress findings by rule ID and path glob. The fail_on list controls which severities count as blocking.

Does the validator execute or sandbox the commands it inspects?▼

No, the gate is purely static spec inspection and never executes, sandboxes, or fetches anything described by a spec. Runtime safety and sandboxing are explicitly out of scope and must be handled by separate runtime controls.

Why does the schema-evolution check report skipped?▼

Evolution checks require a --baseline pointing to the previously shipped spec. Without a baseline, the gate emits a single info finding stating the checks were skipped and stays exit-neutral on that axis.

Related Skills

Explore More Software Engineering Skills→
avibebuilderavibebuilder
113

skill-creator

Create testable Claude Code SKILL.md files with frontmatter and evaluation benchmarks.

Official
Advanced
jimmymalhanjimmymalhan
1

five-agent-verification

Automate code review with five AI agents posting PR comments.

Community
Advanced
BenjamindaosonBenjamindaoson

vercel-sandbox

Automates browser commands in Vercel Sandbox microVMs for deployed apps.

Community
Intermediate
indrasvatindrasvat
3

api-compat

Detect breaking changes in protobuf, OpenAPI, GraphQL, and Go API definitions.

Community
Advanced