Skip to content
SkillModel-led1,717 tokens in use

API Designer

Designs REST and GraphQL APIs from resource models to a linted OpenAPI 3.1 spec, with RFC 7807 errors, pagination and a versioning plan.

12,471 stars on the repository MIT LicenseJeffallan/claude-skills · skills/api-designer
/plugin marketplace add jeffallan/claude-skills /plugin install fullstack-dev-skills@fullstack-dev-skills
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing API Designer costs

38tokens idle
1,717tokens in use
15,483tokens, up to

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Up to adds the files its instructions link. Counts are approximate, made offline with cl100k_base.

Model dependence Model-led

Script-ledMixedModel-led

Mostly instructions, so how well it works depends on the model that follows them.

This describes the skill's structure, how much of it is scripts. It does not say how well it works.

Touches

shelldetected

Declared tags come from the skill's frontmatter; detected ones from its scripts, its code blocks and the commands it names in inline code. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Excellent
  • Frontmatter15/15
  • Structure22/25
  • Examples12/15
  • Output15/15
  • Size15/15
  • Resources15/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Excellent

No findings.

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity100
  • Maintenance100
  • Community60
  • Maturity36
  • Momentum40

API Designer walks Claude through API design in order: understand the domain, model resources, define endpoints, write the contract and plan how the API will change over time.

The contract is an OpenAPI 3.1 specification that the skill lints with Redocly and can serve from a Prism mock server. It ships a starter spec with cursor pagination, bearer authentication and RFC 7807 problem responses.

What You Get

  • A resource model with relationships before any spec is written
  • An OpenAPI 3.1 spec built from a copy-paste starter with cursor pagination and bearer auth
  • Error responses in RFC 7807 problem format with stable type URIs
  • A mock server command to test the contract with Prism
  • A versioning and deprecation plan with a migration path for breaking changes

Common Use Cases

  • Designing a new public REST API from a domain description
  • Writing an OpenAPI spec for an existing service
  • Defining a pagination and error format that every endpoint shares
  • Planning a v2 of an API with a deprecation path
  • Reviewing endpoint naming and status code use

What Makes It Unique

Most API prompts stop at endpoint lists. This skill adds a hard validation step, linting the spec and mocking it, and carries explicit rules such as no verbs in resource URIs, pagination on every collection and a documented error code for each failure. Separate references cover REST patterns, versioning, pagination, error handling and OpenAPI.

Under The Hood

The skill is a SKILL.md with five reference files and no scripts of its own. During a run it tells the agent to execute two npx commands, the Redocly linter on the spec and the Prism mock server, so it runs shell commands in your project, can download those npm packages, and writes the OpenAPI file there. It does not fetch web pages or call outside APIs by itself.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers