How do I install the API Design skill?

Run npx skillmds@latest add odjaramillo/api-design 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 API Design 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 API Design?

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 API Design free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published API Design?

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

API Design by odjaramillo — Agent Skill

Name: API Design
Author: odjaramillo

File contents

Critical Patterns

API-First Approach (REQUIRED)

Design the API (OpenAPI Spec) BEFORE writing code or user stories.
Protocol: Assume HTTP RESTful by default unless specified (gRPC, EDA).

User Story Format (REQUIRED)

As [user role],
I want [specific objective],
So that [benefit and/or value].

Acceptance Criteria (REQUIRED)

Scenario: [Scenario Name]
  Given [pre-condition]
  When [action]
  Then [expected result]

Decision Tree

Need API design?           → Start with OpenAPI spec
Need user story?           → Use As/I want/So that format
Need test cases?           → Use Gherkin Given/When/Then
Need flow visualization?   → Use Mermaid sequenceDiagram

Code Examples

OpenAPI Endpoint

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

Sequence Diagram

sequenceDiagram
    Client->>API: POST /orders
    API->>Service: validateOrder()
    Service->>Database: INSERT order
    Database-->>Service: orderId
    Service-->>API: Order created
    API-->>Client: 201 Created

User Story Example

As an authenticated user,
I want to view my order history,
So that I can track my past purchases.

Acceptance Criteria:
Scenario: View order history
  Given I am logged in
  When I navigate to /orders
  Then I see a list of my orders sorted by date
  And each order shows status and total amount

Success Metrics

Business: ROI, user adoption
Performance: Latency, throughput
Infrastructure: Error rates, uptime
SLIs/SLOs: Specific service level objectives

---name: api-designdescription: API-First design patterns, user stories, and sequence diagrams. Trigger: When designing APIs with OpenAPI, user stories, or sequence diagrams.license: Apache-2.0---## Critical Patterns### API-First Approach (REQUIRED)```Design the API (OpenAPI Spec) BEFORE writing code or user stories.Protocol: Assume HTTP RESTful by default unless specified (gRPC, EDA).```### User Story Format (REQUIRED)```As [user role],I want [specific objective],So that [benefit and/or value].```### Acceptance Criteria (REQUIRED)```gherkinScenario: [Scenario Name] Given [pre-condition] When [action] Then [expected result]```---## Decision Tree```Need API design? → Start with OpenAPI specNeed user story? → Use As/I want/So that formatNeed test cases? → Use Gherkin Given/When/ThenNeed flow visualization? → Use Mermaid sequenceDiagram```---## Code Examples### OpenAPI Endpoint```yamlpaths: /users/{userId}: get: summary: Get user by ID operationId: getUserById parameters: - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: User found content: application/json: schema: $ref: '#/components/schemas/User' '404': description: User not found```### Sequence Diagram```mermaidsequenceDiagram Client->>API: POST /orders API->>Service: validateOrder() Service->>Database: INSERT order Database-->>Service: orderId Service-->>API: Order created API-->>Client: 201 Created```### User Story Example```As an authenticated user,I want to view my order history,So that I can track my past purchases.Acceptance Criteria:Scenario: View order history Given I am logged in When I navigate to /orders Then I see a list of my orders sorted by date And each order shows status and total amount```---## Success Metrics- **Business**: ROI, user adoption- **Performance**: Latency, throughput- **Infrastructure**: Error rates, uptime- **SLIs/SLOs**: Specific service level objectives

Frequently asked questions

API Design