Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add magnus919/agent-skills --skill api-design-and-evolutiongit clone --depth 1 https://github.com/magnus919/agent-skillsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/magnus919/agent-skills/api-design-and-evolution)<a href="https://agentmods.dev/skills/magnus919/agent-skills/api-design-and-evolution"><img src="https://agentmods.dev/badge/skills/magnus919/agent-skills/api-design-and-evolution/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/magnus919/agent-skills/api-design-and-evolution"><img src="https://agentmods.dev/badge/skills/magnus919/agent-skills/api-design-and-evolution.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- NVIDIA SkillSpector pass
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00148 | $0.01918 |
| Opus 5.5 | $0.00059 | $0.00767 |
| Sonnet 5.5 | $0.00030 | $0.00384 |
| Haiku 4.5 | $0.00015 | $0.00192 |
Grade A, and why
api-design-and-evolution scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 19d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 138 lines — stays where its author put it; the contents beside it link to each section on GitHub.
API Design And Evolution
Design an interface as a durable agreement with its consumers, not a route list. Start with the consumer job, domain meaning, authority boundary, and failure modes; then choose the interface style and contract format. Keep facts, assumptions, and policy decisions distinguishable.
When to use
Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or message contract, webhook, or streaming interface. Use it before implementation and again whenever consumer-visible behavior changes.
When not to use
Do not use this as an ADR template, a complete product-discovery method, a security assessment, or an implementation test plan. Hand those concerns to adr-authoring, product-discovery, secure-software-engineering, and verification-methodology, respectively.
Workflow
- Classify the scope. If the request spans more than one interface, start templates/api-landscape-assessment.md and read references/api-landscape-and-governance.md. If it changes where traffic is admitted, routed, observed, or isolated, read references/api-infrastructure-topologies.md. Keep portfolio findings separate from any individual contract decision.
- Discover the agreement. State consumer jobs, domain terms and invariants, authoritative data and schema owners, actors, object/action authority boundaries, data sensitivity, and failure modes. Record unanswered questions rather than inventing policy. Start templates/api-design-brief.md. When an agent or automation is a direct consumer, also read references/agent-consumer-interfaces.md and complete templates/agent-consumer-interface-review.md.
- Choose the interface shape. Compare interaction direction, coupling, delivery needs, query flexibility, mutation semantics, caching, observability, and evolution surface. Read references/interface-selection.md. Record the choice and rejected options in the brief; use an ADR only when the choice is consequential beyond this interface.
- Make the contract explicit. Define representations and their semantics, including null versus absent, defaults, enums/unions, identifiers, timestamps, units, ordering, filtering, and pagination. Use templates/endpoint-contract.md with references/contract-semantics.md.
- Design mutation and failure behavior. Define authority checks, preconditions, idempotency scope and equivalence, retries, concurrency, partial outcomes, long-running operation state, errors, and resource limits. Read references/operations-and-failures.md and create templates/error-taxonomy.md when errors are shared across operations.
- Describe asynchronous delivery where relevant. For messages, webhooks, or streams, state the publisher/subscriber perspective, envelope, delivery contract, duplicate/gap/reordering behavior, ordering scope, and security boundary. Read references/events-webhooks-streaming.md.
- Assess change from each consumer's perspective. Inventory consumers, generated clients, strict decoders, signatures, caches, quotas, and operational dependencies. Complete templates/compatibility-change-assessment.md. Do not call a change safe solely because it is additive.
- Plan and verify rollout. For a deprecation or migration, use templates/deprecation-migration-plan.md and references/evolution-and-deprecation.md. Review the contract using templates/contract-review.md. Test provider conformance, consumer expectations, compatibility diffs, examples, negative cases, and the deployed boundary. Load release-engineering for release sequencing, artifact promotion, progressive exposure, and coordinated rollback after the compatibility policy is defined.
What ships with it
21 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
- evals/evals.json 15 KB
- README.md 2.5 KB
- references/agent-consumer-interfaces.md 5.8 KB
- references/api-infrastructure-topologies.md 5.1 KB
- references/api-landscape-and-governance.md 5.2 KB
- references/contract-semantics.md 4.9 KB
- references/contract-verification.md 1.4 KB
- references/events-webhooks-streaming.md 2.3 KB
- references/evolution-and-deprecation.md 1.7 KB
- references/interface-selection.md 2.2 KB
- references/operations-and-failures.md 3.4 KB
- references/scenario-probes.md 1.7 KB
- references/source-index.md 6.2 KB
- templates/agent-consumer-interface-review.md 2.0 KB
- templates/api-design-brief.md 833 B
- templates/api-landscape-assessment.md 2.0 KB
- templates/compatibility-change-assessment.md 807 B
- templates/contract-review.md 1.7 KB
- templates/deprecation-migration-plan.md 634 B
- templates/endpoint-contract.md 1.3 KB
- templates/error-taxonomy.md 599 B
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 19d ago Changed · +4 lines 92fa87bbef18
- 1mo ago First seen · 134 lines · 148 tokens per session scan A 9155a44705ee
api-design-and-evolution is a skill published in the GitHub repository magnus919/agent-skills (147 stars, last pushed yesterday), licensed MIT. It adds 148 tokens to every session and 1,918 once invoked, about $0.0006 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
stripe-projects
Provision SaaS services + sync creds via Stripe Projects.
fastapi-patterns
FastAPI patterns for async APIs, dependency injection, Pydantic request and response models, OpenAPI docs, tests, security, and production readiness.
mem0-test-integration
Verify a Mem0 integration produced by /mem0-integrate. Runs in the same workspace on the same branch (loose coupling) — installs dependencies, runs the repo's native test suite, then exercises a real end-to-end smoke flow against the user's API key. Produces a scorecard. TRIGGER when: user has just run /mem0-integrate…
open-source
Documentation reference for writing Python code using the browser-use open-source library. Use this skill whenever the user needs help with Agent, Browser, or Tools configuration, is writing code that imports from browseruse, asks about @sandbox deployment, supported LLM models, Actor API, custom tools, lifecycle…
mem0-oss-to-platform
Plan, then execute, a migration of a project from the mem0 open-source / self-hosted SDK (local Memory class) to the mem0 Platform / hosted SDK (MemoryClient). TRIGGER when: the developer wants to move, switch, or migrate mem0 off OSS/self-hosted to the hosted API, e.g. "migrate my mem0 setup to the platform", "switch…
ax-go-flow
Use when writing Go code with github.com/ax-llm/ax/packages/go for flows, nodes, program graphs, nested programs, dynamic options, caching, and optimizer components.