api-contract
Verify field-level alignment between ORM schema, Zod schemas, and route handler shapes, or that SQL migrations match ORM tables. NOT for writing new routes (use api-integration) or code style (use code-standards).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 8
- Forks
- 5
01 前言 Front Matter
- docs
- { "status": "reviewed", "updated": 1785974400000, "source_sha": 863955755827 }
- name
- api-contract
- owner
- swarmery-core
- version
- 1.0.0
- description
- Verify field-level alignment between ORM schema, Zod schemas, and route handler shapes, or that SQL migrations match ORM tables. NOT for writing new routes (use api-integration) or code style (use code-standards).
- allowed-tools
- Read, Grep, Glob
- disable-model-invocation
- true
02 资源文件 2
- 参考文档resources/verification-procedure.md8.3 KB
- 参考文档resources/worked-example-device.md2.6 KB
03 SKILL.md 正文
Purpose
Detects field-name, type, and nullable/optional mismatches across the layers defining an API entity: the ORM schema (apps/<mainApp>/src/lib/db/schema.ts), the Zod schema, the route handler's JSON response, and the SQL migrations in the infrastructure repo. Examples use Drizzle and Flyway-style migrations — adapt to the project's stack (project.json -> stack.db). Read-only: fixes go to @implementation-agent or a developer.
Rules (never violate)
- Read-only skill (Read, Grep, Glob) — never auto-fix a mismatch; refuse if asked.
- Every finding cites
file:lineand carries a severity; findings below 80% confidence are marked[LOW-CONFIDENCE]. - The report contains zero placeholder text and ends with
CONTRACT-ISSUES: {entity} | CRITICAL: {n} | HIGH: {n} | MEDIUM: {n} | LOW: {n}. - A field name that differs between layers is this skill's job; a naming convention preference belongs to
code-standards. - Do not flag Zod
.optional()vs ORM.default(), migration-tool bookkeeping tables, or vendored/generated files; wire-protocol fields keep UPPER_SNAKE_CASE. - Stop and ask on an ORM type with no Zod equivalent, or >10 Critical findings in one entity.
Resources
- Read
resources/verification-procedure.mdwhen running a check — the 7-step procedure, output template, severity criteria, self-check, escalation, and failure modes. - Read
resources/worked-example-device.mdwhen you need a full end-to-end example with real code across all four layers.
How to use
What it does
Checks that one API entity means the same thing in every layer: it reads the ORM table, the Zod schema, the route handler's JSON response, and the SQL migration, then compares them field by field and reports every mismatch with a file:line citation, a severity, and a suggested fix. It never edits code.
When to use it
- You added, renamed, or retyped an ORM column and want to know what drifted.
- You changed a route handler's response shape or wrote a new Zod schema.
- A SQL migration landed and the ORM table definition needs verification.
Not for writing routes (api-integration), convention review (code-standards), or complexity audits (code-quality).
How to invoke
Skill(skill: "core:api-contract")
Pass entity (e.g. order-line-item) and scope (single-entity or full-scan); the skill locates the four sources itself — no file paths needed.
Worked example
Skill(skill: "core:api-contract")
entity: order-line-item, scope: single-entity
The skill compares the order_line_item table, its Zod schema, the route handler, and the migration. It finds Zod declares productId while ORM and SQL use product_id, plus raw ORM output with no validation — three cited findings, closing with CONTRACT-ISSUES: order-line-item | CRITICAL: 0 | HIGH: 0 | MEDIUM: 2 | LOW: 1.
Related
api-integration— building the route;code-standards— conventions;code-quality— complexity audits.
04 同仓库更多 Skills
short-desc
Too short.
no-frontmatter
暂无简介
global-skill
Fixture global skill (minimal user-scope shape, format doc §2.3).
documented-skill
Fixture skill whose usage guide deliberately omits the Worked example subsection.
z
NOT auto-discovered — only skills/ is scanned for plugins (§2.2).
y
Plugin skill y from toolpack — stored as "toolpack:y".