New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

API Design

by epam in epam/ai-dial-chat

Design, review, or change HTTP API contracts for AI DIAL Chat.

Apache-2.0Auto-check passedBackend & APIs

Install API Design

skills CLI
$ npx skills add epam/ai-dial-chat --skill api-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install epam/ai-dial-chat api-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/epam/ai-dial-chat.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/api-design .claude/skills/api-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
api-design
GitHub stars
504
Token cost
~1.2k tokens
SKILL.md length
549 words
Files
1
Skills in repo
18
Repo updated
First seen
Licence
Apache-2.0

At a glance

Design, review, or change HTTP API contracts for AI DIAL Chat.

  • Works in 2 steps: Read openspec/config.yaml for API… → Inspect the closest existing endpoint…
  • Modifying REST endpoints
  • SKILL.md covers Start Here, Contract Checklist, Versioning And Compatibility and OpenSpec Integration, plus 1 more section
  • Calls npm

What it does

API Design is an agent skill from epam/ai-dial-chat. Design, review, or change HTTP API contracts for AI DIAL Chat. Use when adding or modifying REST endpoints, request/response DTOs, status codes, pagination, filtering, API versioning, auth requirements, cache behavior, OpenAPI/Swagger docs, or frontend server-api clients.

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering OpenAPI specifications, REST APIs and API design. It works with OpenAPI. The repository describes itself as: A default UI for AI DIAL. The licence is Apache-2.0.

When your agent uses it

  • Modifying REST endpoints
  • Request/response DTOs
  • Auth requirements
  • OpenAPI/Swagger docs

Example prompts

  • “/api-design”

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. Read openspec/config.yaml for API architecture, project boundaries, and proposal/spec/task rules.
  2. Inspect the closest existing endpoint and its matching frontend client before designing a new contract

What it can do on your machine

Read from SKILL.md and the folder at commit 933c12c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

API Design loads about 1.2k tokens when it runs. Until then it costs about 71 tokens; SKILL.md has 549 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~71
When it runs · the whole SKILL.md, loaded when a task matches
~1.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from epam/ai-dial-chat at commit 933c12c, republished under its Apache-2.0 licence (© epam). 549 words, ~1,222 tokens.

Download SKILL.mdSave it as .claude/skills/api-design/SKILL.md (or your agent's skills folder).
name
api-design
description
Design, review, or change HTTP API contracts for AI DIAL Chat. Use when adding or modifying REST endpoints, request/response DTOs, status codes, pagination, filtering, API versioning, auth requirements, cache behavior, OpenAPI/Swagger docs, or frontend server-api clients.

API Design

Use this skill before implementing or reviewing any HTTP API contract. It defines the contract-first procedure for this repo. For backend implementation mechanics (DTO/Swagger/SDK patterns, tests, Nx verification) follow apps/chat-api/AGENTS.md — do not restate them here. For library isolation follow the "Library isolation" section in the root AGENTS.md: host/API/transport details stay in apps; hand-authored libs/* receive resolved data, values, or callbacks. Exception: libs/chat-api-client is the generated OpenAPI client.

Start Here

  1. Read openspec/config.yaml for API architecture, project boundaries, and proposal/spec/task rules.
  2. Inspect the closest existing endpoint and its matching frontend client before designing a new contract:
    • Backend controllers: apps/chat-api/src/**/**.controller.ts
    • Backend DTOs: apps/chat-api/src/**/dto/*.dto.ts
    • Frontend API helpers: apps/chat/src/server-api/
    • Shared interfaces: libs/chat-shared/

Contract Checklist

For every new or changed endpoint, define these before coding:

  • Method and full path. Business endpoints are URI-versioned (/api/v1/<resource>); infrastructure endpoints stay unversioned (/api/<resource>).
  • Request shape: path params, query params, body DTO, headers, cookies.
  • Success response shape and status code.
  • Error status codes and what each means: at least validation/auth/authorization/not found, plus 502 (upstream non-OK), 503 (upstream timeout/unavailable). Never 500 exposing internals.
  • Authentication and authorization requirements, including whether the endpoint is explicitly public.
  • Cache behavior when applicable: TTL, invalidation, and key naming (<domain>:<resource>[:<param>]).
  • Pagination for list endpoints: prefer cursor for large/append-heavy datasets; offset is acceptable for small admin-style or search flows.
  • Frontend impact: thin domain wrapper in apps/chat/src/server-api/ that delegates to generated @epam/chat-api-client, shared type in libs/chat-shared/ if needed, and i18n strings for any errors surfaced in UI.
  • Library impact: if a hand-authored lib needs the data/behavior, name the prop/callback/resolved value it receives (see lib-isolation note above).
  • Generated client impact: expected SDK class, method name (derived from the controller handler name via operationIdFactory), request type, response type, and whether callers need Raw access for headers/status.

Versioning And Compatibility

  • Non-breaking changes need no new version: adding optional query params, adding response fields, or adding new endpoints.
  • Breaking changes require a new versioned controller or endpoint path. Keep the previous version until callers are migrated.
  • Proposals/specs must call out frontend migration impact and whether shared types change.
Show full SKILL.md (211 more words)Show less

OpenSpec Integration

When writing or reviewing an OpenSpec change that touches API behavior:

  • Specs must include method, full versioned path, request body, response body, and error codes.
  • Tasks must name concrete files, not vague "update API" wording.
  • Include dedicated tasks for: Swagger DTO/annotation updates, npm run openapi, npm run openapi:check, chat-api-client build/lint, backend controller/service tests, generated API singleton updates in apps/chat/src/server-api/api-client.ts, and frontend wrappers using generated @epam/chat-api-client.
  • Generated-client frontend usage is required for new or changed business REST endpoints. Direct base.ts get/post/put/del usage is allowed only for documented generator gaps, streaming calls, or infrastructure endpoints.
  • If endpoint behavior is surfaced through a lib, tasks must keep the generated-client/server-api call in apps/chat and pass only resolved data, values, or callbacks into the lib.
  • Changes under libs/chat-api-client must come from OpenAPI generation (npm run openapi, npm run openapi:sdk, or the documented check), not manual edits.
  • Include cache requirements when relevant.

Avoid

  • Returning 200 for error cases.
  • Designing backend-only contracts without checking the frontend server-api layer.
  • Adding handwritten frontend REST helpers over base.ts for business endpoints the generated client can represent.
  • Hand-editing generated files under libs/chat-api-client/src/generated.
  • Adding unversioned business endpoints.
  • Introducing a generic { data } envelope unless the domain already uses it or the change explicitly standardizes responses.
  • Mixing API redesign with unrelated implementation refactors.

© epam, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/api-design of epam/ai-dial-chat.

Open the folder on GitHubat commit 933c12c

Compare with similar skills

API Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

API Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
API Design this skillepam/ai-dial-chat504—~1.2kAutomated safety check: PassApache-2.0
API Design Assistantmajiayu000/claude-skill-registry6661 repos~2.7kAutomated safety check: PassMIT
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
Old Coder API DesignAmazingAng/old-coder7491 repos~3.4kAutomated safety check: PassMIT
OpenAPI Spec Generationwshobson/agents40k9 repos~511Automated safety check: PassMIT
API Design Patternsrohitg00/awesome-claude-code-toolkit2.7k—~1.2kAutomated safety check: PassApache-2.0

Similar skills

  • API Design Assistant

    majiayu000/claude-skill-registry

    Design and review APIs with suggestions for endpoints, parameters, return types, and best practices.

    666 GitHub starsUsed in 1 repo~2.7k tokens
    Backend & APIsAuto-check passed

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • Old Coder API Design

    AmazingAng/old-coder

    Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers.

    749 GitHub starsUsed in 1 repo~3.4k tokens
    Backend & APIsAuto-check passed

  • OpenAPI Spec Generation

    wshobson/agents

    Create, validate and maintain OpenAPI 3.1 specs for REST APIs, whether designed first or generated from existing code, and use them for docs and client SDKs.

    40k GitHub starsUsed in 9 repos~511 tokens
    Backend & APIsAuto-check passed

  • API Design Patterns

    rohitg00/awesome-claude-code-toolkit

    REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

    2.7k GitHub stars~1.2k tokensUpdated 4 mo ago
    Backend & APIsAuto-check passed

  • API Design

    WrongStack/WrongStack

    A skill your agent uses when designing, implementing, or reviewing an HTTP API — endpoints, request and response shapes, errors, pagination, versioning, and authorization.

    368 GitHub stars~1.3k tokensUpdated yesterday
    Backend & APIsAuto-check passed

More from epam/ai-dial-chat

All 18 skills in this repo

  • Refactoring Audit

    epam/ai-dial-chat

    Deep codebase refactoring audit for AI DIAL Chat. An agent skill from epam/ai-dial-chat.

    504 GitHub stars~4.3k tokensUpdated today
    Auto-check passed

  • Address Current Branch Review

    epam/ai-dial-chat

    Read unresolved GitHub code review threads for the pull request associated with the current branch, classify each comment, and implement and verify required code fixes.

    504 GitHub stars~1.7k tokensUpdated today
    Auto-check passed

  • Create Ticket

    epam/ai-dial-chat

    Interactively create OR update GitHub issues (Bug, Feature, Task) for the current repository.

    504 GitHub stars~4.6k tokensUpdated today
    Auto-check passed

  • Dep Scan

    epam/ai-dial-chat

    Runs Trivy filesystem scan against the repo root and emits structured vulnerability findings (CVE, package, versions) in the SDLC reviewer schema.

    504 GitHub stars~1.2k tokensUpdated today
    Auto-check passed

  • Figma

    epam/ai-dial-chat

    Design-to-code workflow for Figma designs. An agent skill from epam/ai-dial-chat.

    504 GitHub stars~997 tokensUpdated today
    Auto-check passed

  • Git Ship

    epam/ai-dial-chat

    A skill your agent uses whenever the user wants to commit, push, or ship changes in a git repository.

    504 GitHub stars~1.2k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about API Design

What does API Design do?

Design, review, or change HTTP API contracts for AI DIAL Chat. API Design is an agent skill from epam/ai-dial-chat. Design, review, or change HTTP API contracts for AI DIAL Chat.

When should I use API Design?

API Design fits situations like: modifying REST endpoints; request/response DTOs; auth requirements; openAPI/Swagger docs.

How do I install API Design in Claude Code?

Run `npx skills add epam/ai-dial-chat --skill api-design -a claude-code`. Or copy the skill folder (.claude/skills/api-design in epam/ai-dial-chat) into .claude/skills/api-design in your project. Claude Code loads it when a task matches its description.

How do I install API Design in Codex?

Run `npx skills add epam/ai-dial-chat --skill api-design -a codex`. Or copy the skill folder (.claude/skills/api-design in epam/ai-dial-chat) into .agents/skills/api-design in your project. Codex loads it when a task matches its description.

Can I use API Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add epam/ai-dial-chat --skill api-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-design, .gemini/skills/api-design, .github/skills/api-design and .opencode/skills/api-design in your project.

What does API Design need to run?

Going by SKILL.md and its folder, API Design needs the command-line tools its instructions call (npm).

Does API Design access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is API Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does API Design use?

API Design is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does API Design use?

About 1.2k tokens (SKILL.md is roughly 4.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to API Design?

Skills that share tags, products or a category with API Design: API Design Assistant (majiayu000/claude-skill-registry, 666 stars), API Designer (Jeffallan/claude-skills, 12k stars), Old Coder API Design (AmazingAng/old-coder, 749 stars) and OpenAPI Spec Generation (wshobson/agents, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains API Design?

epam (a GitHub organization) maintains it in epam/ai-dial-chat, which has 504 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on October 7, 2026.

Source: epam/ai-dial-chat on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.