Back to catalog
Human reviewedDevelopment

Skill dossier

api-designer

Source declaration

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

The author's original description, preserved in English. It describes intent, not verified performance.

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

developmentreferences

Research summary

Human reviewed

Skill Atlas editorial review · editorial-preview-1.0.0

Walks through designing REST or GraphQL APIs: model resources, define endpoints, write an OpenAPI 3.1 contract, lint and mock it, then plan versioning.

Review scope

Deterministic static analysis of collected SKILL.md and supporting text/code. Machine-assisted candidates and findings await human editorial review; no dynamic behavior or effect is assessed.

Observable capabilities

  • Models resources and relationships and sketches an entity diagram before any spec.
  • Writes an OpenAPI 3.1 specification and lints it with npx @redocly/cli lint.
  • Spins up a mock server with npx @stoplight/prism-cli mock to test the contract.
  • Designs RFC 7807 error responses, cursor pagination and a versioning and deprecation strategy.

Limitations & scope

  • Produces designs and specifications, not a running API implementation.
  • Lint and mock steps rely on npx fetching Redocly and Prism packages, which needs network access and Node.js.
  • Framework-specific guidance is delegated to related skills rather than covered here.

Relevant for

  • Backend and platform engineers designing new APIs
  • Teams standardizing error formats and pagination
  • Reviewers evaluating an API contract

What ships with the skill

The file inventory comes from the collected source at the recorded commit. Paths and sizes are structural observations, not a measure of quality.

files
6
Markdown files
6
scripts
0
references
5
Size
59.6 KB
Structural complexity
Low

File inventory

PathTypeBytes
skills/api-designer/references/error-handling.mdReference11.3 KB
skills/api-designer/references/openapi.mdReference16 KB
skills/api-designer/references/pagination.mdReference9.4 KB
skills/api-designer/references/rest-patterns.mdReference7.3 KB
skills/api-designer/references/versioning.mdReference7.8 KB
skills/api-designer/SKILL.mdInstruction7.8 KB

SKILL.md frontmatter

{
  "name": "api-designer",
  "description": "Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.",
  "license": "MIT",
  "metadata": {
    "author": "https://github.com/Jeffallan",
    "company": "https://synergetic.solutions",
    "version": "1.1.0",
    "domain": "api-architecture",
    "triggers": "API design, REST API, OpenAPI, API specification, API architecture, resource modeling, API versioning, GraphQL schema, API documentation",
    "role": "architect",
    "scope": "design",
    "output-format": "specification",
    "related-skills": "graphql-architect, fastapi-expert, nestjs-expert, spring-boot-engineer, security-reviewer"
  }
}

A reading of the operating sequence

This workflow reconstructs the apparent sequence from source material. Unless controlled evaluation is explicitly recorded, it is provisional—not an observed trace.

  1. 01
    Input

    Analyze the domain

    Understand business requirements, data models and client needs.

  2. 02
    Action

    Specify the contract

    Create the OpenAPI 3.1 spec and lint it with Redocly before proceeding.

  3. 03
    Decision

    Mock and verify

    Run a Prism mock server to test the contract, then plan versioning and deprecation.

  4. 04
    Output

    Deliver the design package

    Provide the resource model, endpoint specs, OpenAPI YAML, auth flows, error catalog and lint result.

Potential risk surfaces

Static findings identify points to inspect before installation. They do not establish that a skill is safe, malicious, or effective.

Items warrant review

42 deterministic lexical finding(s) require review across the collected text. Findings can occur in documentation and do not prove execution or exploitability; binary-only files were not scanned.

Network accessObserved
File writesObserved
Credential useNot observed
Medium

Network access is mentioned

28 occurrences

A URL or network client appears in this source line. Review destinations, data sent, and trust boundaries; static text cannot establish actual network activity. This rule matched 28 location(s) in the collected text; 3 representative location(s) are cited. Matching text may be documentation, and the analyzer did not execute it.

Note

File modification is described or implemented

14 occurrences

This line contains a possible file-write or redirection operation. Check destination paths and overwrite behavior; the static review did not write any file. This rule matched 14 location(s) in the collected text; 3 representative location(s) are cited. Matching text may be documentation, and the analyzer did not execute it.

Editorial security note

Review the npx commands it suggests before running them, since they download and execute third-party packages.

Where context can be spent

Discovery, activation, and resource layers have different meanings. Exact values appear only when the official token-counting method was run with a named model.

Exact token counts unavailable

All token values, including per-file inventory, are null until the pipeline performs an official exact count with an explicit model.

No token measurement was recorded with the required official method. This dossier does not substitute character counts, file sizes, or estimates.

Controlled evaluation

No controlled evaluation

This skill has only the evidence identified above. No task success, token efficiency, latency, or quality advantage is claimed.

Not tested

Use with the source in view

Install command
git clone https://github.com/Jeffallan/claude-skills.git cd claude-skills # Copy this skill directory into one of: # ~/.claude/skills/api-designer # .claude/skills/api-designer
  1. Open the pinned source at https://github.com/Jeffallan/claude-skills/blob/67c1961b180dc92cf08983344627109e983e8f51/skills/api-designer/SKILL.md.
  2. Review the license, prerequisites and all bundled reference files.
  3. Install the skill into a personal or project-level Claude Code skills directory.
  4. Restart or refresh Claude Code so the skill can be discovered.
Verify installation

Confirm api-designer/SKILL.md exists at the destination, then ask Claude Code to use the api-designer skill on a small test task.

Prerequisites

  • Produces designs and specifications, not a running API implementation.
  • Lint and mock steps rely on npx fetching Redocly and Prism packages, which needs network access and Node.js.
  • Framework-specific guidance is delegated to related skills rather than covered here.

Example prompts

Representative task

Use the api-designer skill to design a REST API for an order-management service: model the resources, write an OpenAPI 3.1 spec with cursor pagination and RFC 7807 errors, and lint it.

Inspect before use

Read the api-designer skill at https://github.com/Jeffallan/claude-skills/blob/67c1961b180dc92cf08983344627109e983e8f51/skills/api-designer/SKILL.md and its referenced files. Explain its workflow, required tools, permissions and the main risks before I decide whether to install it.

A decision, with its limits attached

Strengths

  • Includes a copy-paste OpenAPI starter and an RFC 7807 error example.
  • Ends with a checklist that requires lint to pass with no errors.

Considerations

  • Mandates pagination on all collections and a versioning policy, which may be heavy for internal prototypes.
  • Template defaults such as bearer JWT auth are illustrative and need adapting.
Research conclusion

A well-structured contract-first workflow for API design that is only as good as the domain input you give it.

Traceable by construction

The dossier is a time-bound reading of a public artifact, not an endorsement. Use the source link to inspect the exact upstream material.

Jeffallanclaude-skillsskills/api-designer
Source type
Community
Commit
67c1961b180dc92cf08983344627109e983e8f51
Collected
20 Nov 2026
Last checked
20 Nov 2026
Upstream license
MIT
Repository stars
12,464
Content basis

Deterministic lexical parsing, YAML frontmatter validation, file inventory, source-described workflow extraction, and heuristic provisional classification of the supplied files only. Generated by machine; no LLM, execution, dynamic testing, or human editorial approval.