api-contract-strategy
Skill3 starsChanged 8 days agoMITView on GitHub
Analyze and design API contract authoring, ownership, compatibility gates, provider conformance, consumer adapters, OpenAPI/Arazzo workflows, generated code and documentation, client lifecycle, and incremental legacy adoption. Use for HTTP providers with web, mobile, firmware, or multi-repository consumers when contract drift, duplicated DTOs, oversized OpenAPI files, manual API docs, Swagger annotations, CDC/Pact, Redocly/Respect, GUI collections, workflow tooling, or client generation decisions need clear boundaries.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- analyze-projectSkill
- architecture-patternsSkill
- close-changeSkill
- design-changeSkill
- development-standardsSkill
- docker-multiarch-buildSkill
- error-patternsSkill
- go-guidelinesSkill
- herdr-implementSkill
- implement-changeSkill
- logging-standardsSkill
- lua-guidelinesSkill
- organize-docsSkill
- output-stylesSkill
- plan-changeSkill
- powershell-guidelinesSkill
- python-guidelinesSkill
- review-changeSkill
- review-designSkill
- review-implementationSkill
- review-planSkill
- routeros-scripting-guidelinesSkill
- runtime-diagnosisSkill
- security-guardrailsSkill
- shell-guidelinesSkill
- skill-authoringSkill
- skill-minerSkill
- skills-routingSkill
- smart-commitSkill
- sops-age-guardrailsSkill
- sync-truthSkill
- testing-strategySkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Read references/oracle-selection.md in skills-routing when the evidence strategy is unresolved.
- Distinctive: line 35
Treat only deterministic validators and reviewable artifacts as contract authority.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
API Contract Strategy
Purpose
Design the smallest sufficient contract and verification architecture for an API system: meaningful boundary evidence, clear ownership, deterministic compatibility, and low operational cost. Measure maturity by which boundaries have independent evidence and clear ownership.
Scope
Read references/oracle-selection.md in skills-routing when the evidence strategy is unresolved. This Skill decomposes API ownership, compatibility, provider, consumer, workflow, and generation boundaries once a contract oracle exists, either a selected method or an existing OpenAPI/conformance setup.
Decision Workflow
- Map the provider, consumers, repository boundaries, release cadences, existing tests, current contract source, and duplicated representations.
- Choose the maintained authoring source, domain split, bundle, generated projections, workflow specification, runner, and human documentation model using structured contract stack.
- Classify existing evidence and decide which claims it supports using verification layers.
- Decide contract ownership, repository placement, workspace inputs, development generation, and release artifacts using contract lifecycle.
- Identify the smallest missing verification layer and close that gap.
- Select project-owned gates and tools using tool selection;
testing-strategyplaces the resulting suites, fixtures, and CI lanes. - Stage legacy adoption using legacy adoption, preserving useful existing oracles.
- Record rejected approaches and observable upgrade triggers.
Each reference holds the defaults, conditions, and upgrade triggers for its decision; read the one the decision touches.
Output
Render only the decision-relevant conclusions. When the user explicitly requests a comprehensive assessment, cover current state, missing verification layers, target architecture and ownership, the incremental migration plan, tool choices with alternatives and operational cost, and rejected approaches with upgrade triggers.
Guardrails
- Treat only deterministic validators and reviewable artifacts as contract authority.
- Apply
implement-changeAcceptance Integrity when implementation conflicts with a schema, fixture, assertion, or compatibility rule. - Apply the demand test in
architecture-patternsto operational infrastructure, and record its named owner and upgrade trigger.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.