api-and-interface-design

Name: api-and-interface-design
Author: pimenov

20stars2forks

How to install api-and-interface-design?

pimenov/codex-first-skills-pack/api-and-interface-design

$npx -y skills add pimenov/codex-first-skills-pack --skill api-and-interface-design

Installs into the current project.

Summary

Designs stable API, interface, schema, event, CLI, module, and service contracts before implementation so callers, consumers, and future agents can depend on them safely. Use when creating or changing public/internal APIs, SDK surfaces, webhooks, GraphQL/REST/RPC routes, database

Files · 1

View on GitHub

SKILL.md

1	# API and Interface Design
2
3	## Overview
4
5	Use this skill to define the contract before implementation. Treat "API" broadly: HTTP, GraphQL, RPC, webhooks, events, CLI commands, config files, module exports, component props, database schemas, message payloads, and service boundaries.
6
7	The goal is not to produce more ceremony. The goal is to prevent accidental coupling, silent breaking changes, unclear errors, and interfaces that future consumers cannot safely depend on.
8
9	## Relationship To Other Skills
10
11	- Use `spec-driven-development` first when product intent, user behavior, or acceptance criteria are unclear.
12	- Use this skill when the behavior is clear enough, but the interface contract needs precision.
13	- Use `source-driven-development` when the contract depends on current external docs, SDK behavior, platform rules, or standards.
14	- Use `planning-and-task-breakdown` after the contract is stable enough to split into work.
15	- Use `test-driven-development` for contract tests, schema validation tests, compatibility tests, or examples that prove the contract.
16	- Use `incremental-implementation` to implement the contract in small slices: schema/types first, then producer, then consumers.
17	- Use `doubt-driven-review` before claiming public, breaking, production, data, auth, or migration-sensitive changes are safe.
18	- Use `code-review-and-quality` before final acceptance.
19
20	## Do Not Use
21
22	- Do not use for a tiny private helper where no caller boundary or future dependency exists.
23	- Do not use as a replacement for product spec, UX design, security review, or deployment approval.
24	- Do not imply approval for production, auth, schema, data, billing, or public API mutations.
25	- Do not create durable docs by default when a short chat contract is enough.
26
27	## Core Loop
28
29	Work in this order:
30
31	1. CONSUMERS
32	2. CONTRACT
33	3. COMPATIBILITY
34	4. FAILURE MODES
35	5. VERIFICATION
36	6. HANDOFF
37
38	## 1. Consumers
39
40	Name who or what will depend on the interface.
41
42	- Direct callers: frontend, backend service, worker, CLI user, external customer, integration partner, agent, or human operator.
43	- Indirect consumers: dashboards, logs, analytics, automations, tests, docs, runbooks, support workflows.
44	- Trust boundaries: user input, third-party API, internal service, database, queue, browser, admin-only tool.
45	- Source of truth: current implementation, OpenAPI/GraphQL schema, TypeScript types, docs, production behavior, migration plan, Linear issue, repo docs.
46	- Current behavior: explicitly separate documented behavior from observed behavior.
47
48	If consumers are unknown, do read-only discovery before designing the change.
49
50	## 2. Contract
51
52	Define the observable contract before writing implementation.
53
54	Cover the relevant fields:
55
56	- Operation names, routes, commands, events, functions, or exported symbols.
57	- Inputs: required fields, optional fields, defaults, type/schema, validation, allowed values, limits.
58	- Outputs: response shape, status, generated fields, nullability, ordering, pagination, timestamps, units.
59	- Error model: status codes or exception types, machine-readable codes, user-facing message rules, retryability.
60	- Auth and permissions: identity, roles, scopes, tenant/account boundary, admin-only behavior.
61	- Idempotency: idempotency keys, duplicate handling, retry safety, delete semantics.
62	- Consistency: read-after-write, eventual consistency, cache behavior, transaction boundary.
63	- Versioning: version field/path/header/schema, feature flags, compatibility window.
64	- Observability: logs, metrics, audit fields, correlation IDs, public traces.
65
66	Prefer schemas or types where the codebase already supports them: OpenAPI, GraphQL SDL, Zod, JSON Schema, protobuf, TypeScript types, database migrations, or CLI help snapshots.
67
68	## 3. Compatibility
69
70	Apply Hyrum's Law: if a behavior is observable, assume someone may depend on it.
71
72	Classify every change:
73
74	- Additive: new optional field, new endpoint, new enum value only if consumers can tolerate unknown values.
75	- Behavior-preserving: refactor with the same observable contract.
76	- Breaking: removing fields, changing types, changing meanings, changing default ordering, changing error codes, making optional fields required, tightening validation after consumers exist, changing auth/permission expectations.
77	- Ambiguous: looks additive but changes timing, ordering, caching, side effects, rate limits, or error text that might be consumed.
78
79	For breaking or ambiguous changes, define:
80
81	- migration path;
82	- deprecation notice;
83	- com

People who liked this also viewed

6 picks

Type

api-and-interface-design

20stars2forks

View on GitHub

How to install api-and-interface-design?

pimenov/codex-first-skills-pack/api-and-interface-design

$npx -y skills add pimenov/codex-first-skills-pack --skill api-and-interface-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API and Interface Design
2
3	## Overview
4
5	Use this skill to define the contract before implementation. Treat "API" broadly: HTTP, GraphQL, RPC, webhooks, events, CLI commands, config files, module exports, component props, database schemas, message payloads, and service boundaries.
6
7	The goal is not to produce more ceremony. The goal is to prevent accidental coupling, silent breaking changes, unclear errors, and interfaces that future consumers cannot safely depend on.
8
9	## Relationship To Other Skills
10
11	- Use `spec-driven-development` first when product intent, user behavior, or acceptance criteria are unclear.
12	- Use this skill when the behavior is clear enough, but the interface contract needs precision.
13	- Use `source-driven-development` when the contract depends on current external docs, SDK behavior, platform rules, or standards.
14	- Use `planning-and-task-breakdown` after the contract is stable enough to split into work.
15	- Use `test-driven-development` for contract tests, schema validation tests, compatibility tests, or examples that prove the contract.
16	- Use `incremental-implementation` to implement the contract in small slices: schema/types first, then producer, then consumers.
17	- Use `doubt-driven-review` before claiming public, breaking, production, data, auth, or migration-sensitive changes are safe.
18	- Use `code-review-and-quality` before final acceptance.
19
20	## Do Not Use
21
22	- Do not use for a tiny private helper where no caller boundary or future dependency exists.
23	- Do not use as a replacement for product spec, UX design, security review, or deployment approval.
24	- Do not imply approval for production, auth, schema, data, billing, or public API mutations.
25	- Do not create durable docs by default when a short chat contract is enough.
26
27	## Core Loop
28
29	Work in this order:
30
31	1. CONSUMERS
32	2. CONTRACT
33	3. COMPATIBILITY
34	4. FAILURE MODES
35	5. VERIFICATION
36	6. HANDOFF
37
38	## 1. Consumers
39
40	Name who or what will depend on the interface.
41
42	- Direct callers: frontend, backend service, worker, CLI user, external customer, integration partner, agent, or human operator.
43	- Indirect consumers: dashboards, logs, analytics, automations, tests, docs, runbooks, support workflows.
44	- Trust boundaries: user input, third-party API, internal service, database, queue, browser, admin-only tool.
45	- Source of truth: current implementation, OpenAPI/GraphQL schema, TypeScript types, docs, production behavior, migration plan, Linear issue, repo docs.
46	- Current behavior: explicitly separate documented behavior from observed behavior.
47
48	If consumers are unknown, do read-only discovery before designing the change.
49
50	## 2. Contract
51
52	Define the observable contract before writing implementation.
53
54	Cover the relevant fields:
55
56	- Operation names, routes, commands, events, functions, or exported symbols.
57	- Inputs: required fields, optional fields, defaults, type/schema, validation, allowed values, limits.
58	- Outputs: response shape, status, generated fields, nullability, ordering, pagination, timestamps, units.
59	- Error model: status codes or exception types, machine-readable codes, user-facing message rules, retryability.
60	- Auth and permissions: identity, roles, scopes, tenant/account boundary, admin-only behavior.
61	- Idempotency: idempotency keys, duplicate handling, retry safety, delete semantics.
62	- Consistency: read-after-write, eventual consistency, cache behavior, transaction boundary.
63	- Versioning: version field/path/header/schema, feature flags, compatibility window.
64	- Observability: logs, metrics, audit fields, correlation IDs, public traces.
65
66	Prefer schemas or types where the codebase already supports them: OpenAPI, GraphQL SDL, Zod, JSON Schema, protobuf, TypeScript types, database migrations, or CLI help snapshots.
67
68	## 3. Compatibility
69
70	Apply Hyrum's Law: if a behavior is observable, assume someone may depend on it.
71
72	Classify every change:
73
74	- Additive: new optional field, new endpoint, new enum value only if consumers can tolerate unknown values.
75	- Behavior-preserving: refactor with the same observable contract.
76	- Breaking: removing fields, changing types, changing meanings, changing default ordering, changing error codes, making optional fields required, tightening validation after consumers exist, changing auth/permission expectations.
77	- Ambiguous: looks additive but changes timing, ordering, caching, side effects, rate limits, or error text that might be consumed.
78
79	For breaking or ambiguous changes, define:
80
81	- migration path;
82	- deprecation notice;
83	- com

People who liked this also viewed

6 picks

Type