magnus919/agent-skills

api-design-and-evolution

- Design, govern, document, review, and evolve consumer-facing APIs and event interfaces.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/magnus919/agent-skills --skill api-design-and-evolution

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

Reference Guide

Load whenFile
Assessing an API portfolio, ownership, duplication, discoverability, lifecycle, standards, or retirementreferences/api-landscape-and-governance.md and templates/api-landscape-assessment.md
Comparing gateways, ingress proxies, service meshes, traffic direction, routing, policy, telemetry, or failure boundariesreferences/api-infrastructure-topologies.md
Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streamingreferences/interface-selection.md
Modeling data, collection reads, schemas, or OpenAPIreferences/contract-semantics.md
Designing writes, errors, retry behavior, limits, or authorization handoffreferences/operations-and-failures.md
Designing event contracts, webhook delivery, or streamsreferences/events-webhooks-streaming.md
Reviewing compatibility, versions, deprecation, migration, or rollbackreferences/evolution-and-deprecation.md
Preparing contract/provider/consumer/deployment verificationreferences/contract-verification.md
Checking exact sources, versions, status, and intended usereferences/source-index.md
Reviewing APIs or tools used directly by agents and automationsreferences/agent-consumer-interfaces.md and templates/agent-consumer-interface-review.md
Exercising required edge cases before claiming readinessreferences/scenario-probes.md

Security Boundary

Document authentication requirements and server-side object/action authorization in the interface contract. For the threat model, credential handling, tenant isolation, untrusted URLs or files, webhook signature design, output minimization, redaction, or abuse resistance, load secure-software-engineering. An API contract cannot prove that an authorization boundary is enforced.

Ownership Boundaries

  • Product owners decide consumer outcomes, audience, value, and lifecycle intent;

this skill turns those decisions into interface agreements and evidence.

  • Platform owners decide gateway, ingress, mesh, networking, deployment, and

runtime operations. This skill identifies topology responsibilities and contract consequences but does not operate the substrate.

  • Security owners decide threat models, credential and secret controls, abuse

resistance, and tenant isolation. This skill records the contract handoff and required authorization behavior without substituting for the assessment.

  • Architecture owners decide cross-system principles, significant boundaries,

and durable architecture decisions. Use adr-authoring when a landscape or topology decision has consequences beyond the API portfolio.

An API landscape assessment is not a product roadmap, platform runbook, security review, or enterprise architecture repository. Escalate unresolved ownership, authority, or retirement decisions instead of assigning them implicitly.

Completion

Stop when the selected interface has an owner, an authoritative contract, explicit consumer and failure assumptions, a compatibility assessment for each change, and evidence or an explicit gap for each required review item. Escalate unresolved domain semantics, authority, delivery, or consumer-impact questions to their accountable owner.

タスクに関連する項目

同じリポジトリから

関連する Skills

すべての Skills
magnus919
コミュニティ

ai-governance

Design and operate AI governance: principles, decision rights, risk tiers, lifecycle gates, fairness, transparency, privacy, security, compliance mapping, maturity and board reporting across SaaS, API, self-hosted and agentic systems. Use to admit, update or retire Agent Skills, MCP servers and A2A capabilities; approve an agent for production actions; or decide earned-autonomy promotion, reduction or revocation. Cover GxP, ALCOA+, data integrity, electronic records, assurance and QMS interfaces

1時間の導入数
1
GitHub Stars
172
更新日
11月8日
magnus919
コミュニティ

amazon-memo

Create, adapt, or revise Amazon-style narrative decision memos, six-pagers, PR/FAQs, and short decision briefs, including reading meetings and async review. Use for choosing the right memo form, evidence-led reasoning, and revising mechanical AI prose for human readers. Do not use for general copywriting, document rendering, or replacing incident reports and technical design records.

1時間の導入数
1
GitHub Stars
172
更新日
11月8日
magnus919
コミュニティ

analog-occultism

Use this skill to create subject-neutral images and videos in an analog occultism / industrial CRT noir aesthetic: near-monochrome archival technical atmosphere, severe low-key lighting, tactile signal degradation, industrial geometry, and quiet unresolved tension. Use for portraits, products, environments, interfaces, diagrams, abstract forms, stills, and motion. Do not use for colorful cyberpunk, vaporwave, glossy advertising, conventional horror, or clean digital renders.

1時間の導入数
1
GitHub Stars
172
更新日
11月8日
magnus919
コミュニティ

binary-analysis

Plan static inspection of unknown binary files with a deterministic CLI whose Ghidra operations are currently unimplemented and fail closed. Use when you need to inspect a PE, ELF, or Mach-O file — triage suspicious binaries, map imported APIs, decompile functions, trace call paths, or produce structured evidence reports. Do not use for runtime analysis (debugging, dynamic tracing, sandbox execution), for modifying or patching binaries, or for binaries you already know everything about. The skil

1時間の導入数
1
GitHub Stars
172
更新日
11月8日