Design api design

Skill carson-sweet/sweetclaude/skills/design-api-design

Design API endpoints: routes, request/response shapes, authentication, pagination, error responses, and versioning strategy.From its SKILL.md

Install

npx -y skills add carson-sweet/sweetclaude --skill design-api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.6 KB, as published. Nobody here has run it

!bash ${CLAUDE_SKILL_DIR}/../../hooks/read-state.sh session-state

<preflight-guard> STOP. Before executing this skill, check: does .sweetclaude/state/sweetclaude.yaml or .sweetclaude/state/phase.yaml exist in the project directory? If NEITHER, do not proceed. Tell the user: "This project is not set up for SweetClaude. Running the pre-flight check now." Then invoke the sweetclaude master skill (Skill tool, skill: "sweetclaude:master") and run its pre-flight. Return here only after the pre-flight passes. </preflight-guard>

API Design

Artifact Path Resolution

Before writing any artifact file:

Read .sweetclaude/artifact-privacy.yaml. If it does not exist, stop and say:

"No artifact privacy manifest found. Run /sweetclaude:doctor to repair the artifact privacy configuration, then return here." Do not guess a path. Do not fall back to a default.
Read categories.technical.base_path. This is the base directory for all technical artifacts.
Check .sweetclaude/state/session-state.yaml → active_work_item.work_dir:
- If set: use {work_dir}/design/ as the write path. Create the directory if needed (mkdir -p). After writing, create a relative symlink from {base_path}/{filename} → the work-dir file.
- If not set: use {base_path}/{filename} as before.
Write artifacts to the resolved path.

Design the API for: $ARGUMENTS

Context

Read architecture doc, data model, and user stories from docs/ and .sweetclaude/stories/.

Process

1. Endpoint inventory

List every endpoint needed. For each:

HTTP method and path
Purpose (one sentence)
Who can call it (auth requirements)

2. Detailed design per endpoint

For each endpoint:

### {METHOD} {path}

**Purpose:** {what it does}
**Auth:** {required role/permission}

Request:
  Headers: {required headers}
  Params: {path and query params with types}
  Body: {JSON shape with types}

Response 200:
  {JSON shape with types}

Response 4xx:
  {error shapes — 400 validation, 401 unauth, 403 forbidden, 404 not found}

Response 5xx:
  {generic error shape}

3. Cross-cutting concerns

Pagination: pattern (cursor vs offset), defaults, maximums
Filtering/sorting: query param conventions
Versioning: strategy (URL path, header, none)
Rate limiting: if applicable
CORS: allowed origins

4. Save

Save to {base_path}/api-design.md. Record key decisions via design/manage-decisions.