OpenSkillIndex← back to search
claude-code

Software_development_department api-design

install
source · Clone the upstream repo
git clone https://github.com/tranhieutt/software_development_department
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/tranhieutt/software_development_department "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/api-design" ~/.claude/skills/tranhieutt-software-development-department-api-design && rm -rf "$T"
manifest: .claude/skills/api-design/SKILL.md
source content

When this skill is invoked:

  1. Read the target API spec or route files in full.

  2. Identify the API type (REST, GraphQL, WebSocket) and apply appropriate standards.

  3. Evaluate REST design quality (if REST):

    • Resources use nouns, not verbs (
      /users
      , not 
      /getUsers
      )
    • Correct HTTP methods (GET=read, POST=create, PUT/PATCH=update, DELETE=remove)
    • Consistent plural resource naming (
      /users
      , 
      /orders
      )
    • Nested resources have max 2-3 levels of depth
    • Query parameters used for filtering, sorting, pagination (not in path)

  4. Evaluate request/response schemas:

    • All inputs are validated and typed
    • Responses are consistent in structure (envelope format if used)
    • Pagination is consistent (cursor or page-based, not mixed)
    • Timestamps in ISO 8601 (UTC)
    • Money values in smallest currency unit (cents), not floats

  5. Evaluate authentication & authorization:

    • Every endpoint has explicit auth requirement documented
    • Authorization is checked server-side, not just on the client
    • Sensitive data not leaked in error messages

  6. Evaluate error responses:

    • Consistent error format (RFC 7807 Problem Details recommended)
    • HTTP status codes used correctly (400 for client errors, 500 for server)
    • Error messages are user-safe (no stack traces, SQL errors)

  7. Evaluate versioning & backward compatibility:

    • Breaking changes require a version bump
    • Deprecation policy documented
    • Clients can negotiate API version

  8. Output the review:

## API Design Review: [API/Endpoint Name]

### REST Design: [CLEAN / ISSUES FOUND]
[List specific issues with examples]

### Schema Quality: [CLEAN / ISSUES FOUND]
[List schema inconsistencies or problems]

### Auth & Security: [SECURE / ISSUES FOUND]
[List authentication and authorization issues]

### Error Handling: [CONSISTENT / ISSUES FOUND]
[List error response problems]

### Versioning: [HANDLED / UNADDRESSED]
[Notes on breaking change risk]

### Positive Observations
[What is well-designed]

### Required Changes
[Must-fix items before shipping]

### Suggestions
[Nice-to-have improvements]

### Verdict: [APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]

Protocol

  • Question: Auto-starts from argument (path to API spec or route files); no clarification needed
  • Options: Skip — single review path
  • Decision: Skip — verdict is advisory
  • Draft: Full review report shown in conversation only
  • Approval: Skip — read-only; no files written

Output

Deliver exactly:

  • Endpoint compliance score (X/Y checks passing across naming, methods, validation, errors)
  • Security issues with severity — CRITICAL / HIGH / MEDIUM (or "None")
  • Required changes — must fix before shipping (or "None")
  • Verdict: 
    APPROVED
    / 
    APPROVED WITH SUGGESTIONS
    / 
    CHANGES REQUIRED