/build-contract-first-integrations

When to use it

The skill is meant to be pulled in when one of these conditions is true.

• Frontend, backend, workers, services, or scripts repeat assumptions about each other.
• Runtime bugs come from changed payloads, missing headers, or inconsistent errors.
• Generated clients exist but still need product-safe adapters.
• The team needs earlier feedback when an integration boundary changes.

Start by asking

These questions keep the work from jumping straight to implementation details.

• Where is the contract defined, and which side owns it?
• What are the required inputs, outputs, headers, errors, permissions, and version rules?
• Which transport details are leaking into product logic?
• What should be generated, what should be handwritten, and what should be validated?
• How will the system detect contract drift before users do?

Universal principal-level checks

Every skill should carry these concerns, even when the immediate request sounds narrower.

Skill-specific considerations

Process

Deliver

• A contract map with source of truth, consumers, and generated artifacts.
• A product-safe integration layer above the raw client.
• Drift checks for changed routes, payloads, errors, and visibility.
• A failure-mode checklist for unavailable or incompatible dependencies.

Failure modes

These are the quiet ways the work can look finished while still being risky.

• Generated code exposes internal operations to product code.
• Runtime behavior differs from the generated type contract.
• Every screen handles auth, headers, and errors slightly differently.

Avoid

• Handwriting types that duplicate an existing contract.
• Letting product screens call low-level clients directly.
• Treating code generation as a replacement for contract ownership.

Verify before finishing

• Does a changed response fail a local or CI check?
• Can a product screen call the operation without knowing transport details?
• Are public, internal, deprecated, and experimental operations separated?

Prompt to copy

Paste this into an AI session when you want the model to apply the full skill instead of giving a shallow answer.

Use this skill: /build-contract-first-integrations.
Title: Build contract-first integrations

Goal: Treat system boundaries as contracts so product code does not guess what another layer accepts or returns.

Frame: Use this skill when two systems exchange data. The goal is to make the boundary explicit enough that changes fail early, product code stays small, and integration details do not leak everywhere.

Universal principal-level considerations:
- Product intent
  - Name the user, operator, developer, or business outcome the work protects.
  - Separate what the system must do from how the current implementation happens to do it.
  - Identify the smallest useful improvement and the larger direction it should not block.
- Ownership and boundaries
  - Decide which layer owns policy, presentation, transport, persistence, validation, and side effects.
  - Make shared abstractions explicit about what they own and what they leave to the caller.
  - Prefer boundaries that reduce repeated decisions without hiding important context.
- Data and state integrity
  - Define the source of truth, derived state, cached state, temporary state, and persisted state.
  - Handle missing, stale, partial, conflicting, duplicated, and invalid data deliberately.
  - Keep transformations close to system boundaries so product code does not accumulate guesses.
- Security, privacy, and abuse
  - Treat external input, user-provided values, remote resources, generated output, and stored content as untrusted.
  - Avoid leaking internal identifiers, sensitive defaults, private routes, tokens, or implementation details.
  - Consider who can trigger expensive, destructive, or externally visible behavior.
- Accessibility and comprehension
  - Check semantic structure, accessible names, focus order, keyboard behavior, contrast, and reduced-motion behavior.
  - Write states and errors so a user can understand what happened and what to do next.
  - Make important information available without relying only on color, animation, hover, or layout position.
- Performance and scale
  - Identify work that runs per request, per render, per item, per file, per route, or per user action.
  - Avoid moving repeated work into a shared abstraction if that also hides expensive behavior.
  - Plan for growth in records, tenants, users, routes, generated files, and integration consumers.
- Reliability and operations
  - Design for retries, partial failure, timeouts, idempotency, rollback, reconciliation, and observability.
  - Make failures explain what broke, who is affected, and what should be inspected next.
  - Leave an audit trail for changes that affect access, content, billing, data, publishing, or public behavior.
- Testing and release
  - Test the contract, not only the implementation detail.
  - Cover role, permission, plan, device, theme, and failure-state differences when they change behavior.
  - Add preflight checks for generated files, configuration, fixtures, migrations, and runtime definitions.
- Documentation and handoff
  - Document decisions, tradeoffs, naming rules, escape hatches, and cleanup conditions.
  - Write for the next person who has to extend, debug, or remove the system.
  - Keep examples small enough to trust and realistic enough to reuse.
- Maintenance and reversibility
  - Prefer changes that can be migrated incrementally and rolled back safely.
  - Name temporary decisions and set conditions for removing them.
  - Watch for abstractions that become permanent because nobody knows what they were originally solving.

Use this when:
- Frontend, backend, workers, services, or scripts repeat assumptions about each other.
- Runtime bugs come from changed payloads, missing headers, or inconsistent errors.
- Generated clients exist but still need product-safe adapters.
- The team needs earlier feedback when an integration boundary changes.

Start by asking:
- Where is the contract defined, and which side owns it?
- What are the required inputs, outputs, headers, errors, permissions, and version rules?
- Which transport details are leaking into product logic?
- What should be generated, what should be handwritten, and what should be validated?
- How will the system detect contract drift before users do?

Skill-specific considerations:
- Contract shape
  - Include success, empty, partial, validation, authorization, and failure responses.
  - Model pagination, sorting, filtering, metadata, and version behavior explicitly.
  - Avoid treating generated types as enough if runtime behavior can still differ.
- Adapter boundary
  - Keep transport, auth, headers, retries, and response parsing below product code.
  - Map raw contract language into product language before it reaches screens.
  - Make unsafe or internal operations impossible to call from normal product code.
- Feedback loop
  - Run generation, validation, or contract checks in CI.
  - Use fixtures or contract tests for real consumer scenarios.
  - Fail close to the changed operation, not after a full manual QA pass.

Process:
- Define
  - Name the boundary and enumerate every operation it exposes.
  - Document inputs, outputs, errors, auth, versioning, and side effects.
- Generate or validate
  - Use schemas, generated clients, fixtures, or validators to remove repeated assumptions.
  - Keep product-specific mapping outside the generated layer.
- Integrate
  - Expose product-safe operations with consistent loading, error, retry, and empty behavior.
  - Add drift checks and review gates for contract changes.

Deliver:
- A contract map with source of truth, consumers, and generated artifacts.
- A product-safe integration layer above the raw client.
- Drift checks for changed routes, payloads, errors, and visibility.
- A failure-mode checklist for unavailable or incompatible dependencies.

Watch for failure modes:
- Generated code exposes internal operations to product code.
- Runtime behavior differs from the generated type contract.
- Every screen handles auth, headers, and errors slightly differently.

Avoid:
- Handwriting types that duplicate an existing contract.
- Letting product screens call low-level clients directly.
- Treating code generation as a replacement for contract ownership.

Verify before finishing:
- Does a changed response fail a local or CI check?
- Can a product screen call the operation without knowing transport details?
- Are public, internal, deprecated, and experimental operations separated?