How do I install the Docs Interfaces skill?

Run npx skillmds@latest add jh941213/docs-interfaces-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Docs Interfaces safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Docs Interfaces?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Docs Interfaces free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Docs Interfaces?

jh941213 (@jh941213) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Docs Interfaces by jh941213 — Agent Skill

Name: Docs Interfaces
Author: jh941213

Docs Interfaces

Generate interface/API docs — OpenAPI 3.1/AsyncAPI 3.0 specs, API topology diagrams, interface flow (sequence) diagrams, API changelog. Use when writing API docs/specs (OpenAPI, swagger, AsyncAPI), interface/API topology diagrams, endpoint docs, API changelogs. Whole-system diagrams → docs-architecture; user manuals → docs-manuals; API design principles themselves → api-design-principles

jh941213 23ba97b 3.3 KB Updated Sep 17, 2026

File contents

Interface/API Documentation Skill

Documents contracts between systems. The spec in Git is the single source of truth (docs-as-code).

Input

$ARGUMENTS

Artifact map

Target	Artifact	Location
REST API	OpenAPI 3.1 spec	`docs/api/openapi.yaml`
Event/message interfaces	AsyncAPI 3.0 spec	`docs/api/asyncapi.yaml`
API topology (inter-system calls)	C4 Container + per-flow sequence diagrams	`docs/api/README.md`
Human-readable reference	Per-endpoint markdown (inherits docs-writer's api.md format)	`docs/api/reference.md`
API change history	breaking/non-breaking + deprecation schedule	`docs/api/CHANGELOG.md`

Spec-first vs code-first

Multiple teams/external consumers → spec-first: author and review docs/api/openapi.yaml first; code follows the spec
Single-team internal service → code-first is fine, but the generated spec must be committed and diffed in CI (the drift gate is installed by the docs-ci skill)
Either way a spec file must exist in the repo — "the code is the doc" doesn't count

OpenAPI rules

Write from actual routes/schemas read from code — no guessing. Mark unverifiable fields with TODO comments
operationId required, group resources with tags, include 4xx/5xx responses
Examples must be real working values
Declare auth schemes (securitySchemes)
Don't force event-driven interfaces (queues, websockets, webhooks) into OpenAPI — split into AsyncAPI

API topology + flow diagrams

Inter-system topology: 1 C4 Container diagram
One sequence diagram per key flow (auth, order creation, …) — use the shared conventions in ../docs-architecture/references/mermaid-conventions.md
Include at least one error path (alt block) — never draw only the happy path

API CHANGELOG rules

## [v1.4.0] - 2026-07-27
### Breaking
- `GET /users` response: removed `nickname` → `profile.nickname` (migration: …)
### Added
- `POST /invoices/bulk`
### Deprecated
- `GET /v1/legacy-search` — sunset 2026-10-01

Breaking changes must ship with a migration path
If oasdiff is installed, draft with oasdiff changelog <base> <rev> then polish

Procedure

Find route/handler/schema files (**/routes/**, **/api/**, **/controllers/**, framework patterns)
If a spec exists, diff it against actual code → report mismatches first, then update
If new, generate an OpenAPI 3.1 skeleton → fill per resource
Write docs/api/README.md with topology + flow diagrams
Update docs/docs.yaml manifest entries for docs/api/* (covers: route path globs)
Validate the spec: npx @redocly/cli lint docs/api/openapi.yaml or npx @stoplight/spectral-cli lint (only if installed; otherwise skip and suggest docs-ci)

Constraints

Modify only docs/. Never touch source code
Never put endpoints in the spec that don't exist in code

---name: docs-interfaces-2description: Generate interface/API docs — OpenAPI 3.1/AsyncAPI 3.0 specs, API topology diagrams, interface flow (sequence) diagrams, API changelog. Use when writing API docs/specs (OpenAPI, swagger, AsyncAPI), interface/API topology diagrams, endpoint docs, API changelogs. Whole-system diagrams → docs-architecture; user manuals → docs-manuals; API design principles themselves → api-design-principles---# Interface/API Documentation SkillDocuments contracts between systems. The spec in Git is the single source of truth (docs-as-code).## Input$ARGUMENTS## Artifact map| Target | Artifact | Location ||--------|----------|----------|| REST API | OpenAPI 3.1 spec | `docs/api/openapi.yaml` || Event/message interfaces | AsyncAPI 3.0 spec | `docs/api/asyncapi.yaml` || API topology (inter-system calls) | C4 Container + per-flow sequence diagrams | `docs/api/README.md` || Human-readable reference | Per-endpoint markdown (inherits docs-writer's api.md format) | `docs/api/reference.md` || API change history | breaking/non-breaking + deprecation schedule | `docs/api/CHANGELOG.md` |## Spec-first vs code-first- **Multiple teams/external consumers** → spec-first: author and review `docs/api/openapi.yaml` first; code follows the spec- **Single-team internal service** → code-first is fine, but the generated spec must be committed and diffed in CI (the drift gate is installed by the docs-ci skill)- Either way a spec file must exist in the repo — "the code is the doc" doesn't count## OpenAPI rules1. Write from actual routes/schemas read from code — no guessing. Mark unverifiable fields with TODO comments2. `operationId` required, group resources with tags, include 4xx/5xx responses3. Examples must be real working values4. Declare auth schemes (`securitySchemes`)5. Don't force event-driven interfaces (queues, websockets, webhooks) into OpenAPI — split into AsyncAPI## API topology + flow diagrams- Inter-system topology: 1 C4 Container diagram- One sequence diagram per key flow (auth, order creation, …) — use the shared conventions in `../docs-architecture/references/mermaid-conventions.md`- Include at least one error path (`alt` block) — never draw only the happy path## API CHANGELOG rules```markdown## [v1.4.0] - 2026-07-27### Breaking- `GET /users` response: removed `nickname` → `profile.nickname` (migration: …)### Added- `POST /invoices/bulk`### Deprecated- `GET /v1/legacy-search` — sunset 2026-10-01```- Breaking changes must ship with a migration path- If oasdiff is installed, draft with `oasdiff changelog <base> <rev>` then polish## Procedure1. Find route/handler/schema files (`**/routes/**`, `**/api/**`, `**/controllers/**`, framework patterns)2. If a spec exists, diff it against actual code → report mismatches first, then update3. If new, generate an OpenAPI 3.1 skeleton → fill per resource4. Write `docs/api/README.md` with topology + flow diagrams5. Update `docs/docs.yaml` manifest entries for `docs/api/*` (covers: route path globs)6. Validate the spec: `npx @redocly/cli lint docs/api/openapi.yaml` or `npx @stoplight/spectral-cli lint` (only if installed; otherwise skip and suggest docs-ci)## Constraints- Modify only `docs/`. Never touch source code- Never put endpoints in the spec that don't exist in code

Frequently asked questions