api-designer

Overview of api-designer skill

What the api-designer skill does

The api-designer skill helps an agent design or review REST and GraphQL APIs with a stronger structure than a generic “design me an API” prompt. It is aimed at turning a product need into a usable API shape: resources, endpoints or schema patterns, HTTP methods, status codes, pagination, authentication, error handling, and versioning.

Who should use api-designer

This api-designer skill is best for developers, tech leads, platform teams, and architects who need a first-pass API design, a review checklist, or a repeatable spec draft. It is especially useful when you want a consistent starting point quickly, not just abstract advice.

Real job-to-be-done

Most users do not need API theory. They need to get from “we need user management” to “here is a sensible API design document we can discuss, validate, and implement.” The api-designer skill is most valuable when that gap is blocking delivery or causing inconsistent API choices across teams.

What makes this skill different

The main differentiator is that the skill is not only prompt text. It includes reference files for REST and GraphQL patterns plus two practical scripts:

• scripts/generate_api.py to create a starter design document
• scripts/validate_api.py to check whether key design sections are present

That makes api-designer more install-worthy than a lightweight advice-only skill if you want a tangible artifact and a basic validation step.

What it is good at and where it is thin

api-designer for API Development is good at standard API structure, CRUD-style resource modeling, baseline REST conventions, and GraphQL schema guidance. It is thinner on advanced domain modeling, event-driven APIs, long-running workflows, distributed consistency, and organization-specific governance. Treat it as a solid scaffold, not a full API review board.

How to Use api-designer skill

Install context for api-designer skill

This skill lives under skills/api-designer in the zhaono1/agent-playbook repository:
https://github.com/zhaono1/agent-playbook/tree/main/skills/api-designer

If your skill runner supports repository-based installs, use its standard install flow for this repo and select api-designer. The repository summary you have may show an npx skills add ... --skill api-designer pattern, but the skill itself does not declare its own install command in SKILL.md, so use the install method supported by your environment.

Read these files first

For a fast, high-signal api-designer guide, start here:

1. skills/api-designer/SKILL.md
2. skills/api-designer/references/rest-patterns.md
3. skills/api-designer/references/graphql-patterns.md
4. skills/api-designer/scripts/generate_api.py
5. skills/api-designer/scripts/validate_api.py

This order matters. SKILL.md gives activation and core principles; the references sharpen conventions; the scripts show the artifact shape the skill expects.

What input the skill needs

The api-designer usage quality depends heavily on what you provide. At minimum, give:

• API style: REST, GraphQL, or both
• Domain and core resources
• Main user actions
• Authentication model
• Consumer type: internal, partner, public
• Non-goals and constraints
• Pagination, filtering, and error expectations
• Whether backward compatibility or versioning matters

Without these inputs, the skill will default to generic CRUD patterns.

Turn a vague request into a strong prompt

Weak prompt:

• “Design an API for orders.”

Stronger prompt:

• “Use the api-designer skill to draft a REST API for order management for an internal admin tool. Core resources: orders, customers, refunds. Needed operations: list orders with filtering by status and date, get order details, create refund, update fulfillment status. Auth is service-issued bearer tokens. Must support pagination, standardized error responses, and future versioning. Non-goals: payments processing and bulk export. Produce a design doc with endpoints, request/response examples, status codes, auth, rate limits, and error model.”

This works better because it narrows scope, surfaces constraints, and asks for the exact artifact shape the skill can support.

Use the included generator for a draft spec

The repo includes a useful starter generator:

python skills/api-designer/scripts/generate_api.py --name orders --owner platform-team --output api-design.md

This is one of the strongest reasons to use api-designer install instead of copying patterns manually. It gives you a draft with sections such as:

• ## Overview
• ## Ownership
• ## Goals
• ## Non-Goals
• ## Resources
• ## Endpoints

Use it before asking the model to refine the design. You will get better results editing a structured draft than starting from a blank page.

Validate the design before review

After generating or revising a spec, run the validator:

python skills/api-designer/scripts/validate_api.py --input api-design.md

The validator checks for required sections including:

• ## Overview
• ## Ownership
• ## Resources
• ## Endpoints
• ## Authentication
• ## Error Model
• ## Pagination
• ## Rate Limits

You can also add custom required sections:

python skills/api-designer/scripts/validate_api.py --input api-design.md --require "## Versioning"

This is basic validation, not semantic review, but it catches incomplete drafts quickly.

REST workflow that fits this skill best

For REST, the skill is strongest when you work in this sequence:

1. Identify resources as nouns, not actions
2. Map operations to GET, POST, PUT, PATCH, DELETE
3. Choose paths and collection/item patterns
4. Define status codes and error model
5. Add pagination, filtering, auth, and rate limits
6. Review naming and versioning

The repo’s examples clearly favor resource-oriented design like /users and /users/{id} over action-heavy paths like /getUsers.

GraphQL workflow that fits this skill best

For GraphQL, use the references to steer the model toward:

• clear type names
• fewer overly generic fields
• cursor-based pagination
• input objects for complex mutations
• mutation responses that return updated entities and errors

This skill can help with schema structure, but you should still provide domain-specific query patterns; otherwise the model will produce a shallow schema that looks neat but does not match real frontend or integration needs.

Practical prompt pattern for api-designer usage

A reliable prompt template:

Use the api-designer skill.

Design a [REST/GraphQL] API for [product or workflow].
Users: [who consumes it]
Core resources/types: [list]
Main operations: [list]
Auth: [model]
Constraints: [compliance, performance, backward compatibility, public/internal]
Non-goals: [list]
Need included: endpoints or schema, examples, pagination, error model, versioning, rate limits.
Output format: a markdown design doc ready for team review.

This prompt structure materially improves output because it aligns with the validator and generator rather than fighting them.

Best repository-reading path for adoption decisions

If you are deciding whether to adopt api-designer skill, inspect:

• SKILL.md for scope and conventions
• references/rest-patterns.md to see how opinionated the REST guidance is
• references/graphql-patterns.md to check GraphQL fit
• scripts/generate_api.py to judge template usefulness
• scripts/validate_api.py to judge workflow maturity

If those files match how your team writes design docs, the skill is worth installing. If you need OpenAPI generation, policy linting, or deep protocol governance, this skill alone is probably too light.

api-designer skill FAQ

Is api-designer good for beginners

Yes, if the beginner already understands basic API concepts. The api-designer skill gives structure and conventions, but it does not replace learning why one resource model is better than another. It is a guided scaffold, not a full tutorial.

Is this better than a normal prompt

Usually yes for repeatability. A plain prompt may generate acceptable endpoints once, but api-designer skill gives you a reusable workflow with references and scripts. That matters when you want consistency across multiple services or reviewers.

Does api-designer support both REST and GraphQL

Yes. The repository explicitly includes REST principles in SKILL.md and separate reference files for both REST and GraphQL patterns. In practice, it is more concrete for common REST design, while GraphQL guidance is useful but lighter.

When should I not use api-designer

Skip api-designer for API Development when your main problem is:

• event-driven or streaming interface design
• async workflow orchestration
• protocol-specific design beyond REST/GraphQL
• strict enterprise governance requiring OpenAPI-first pipelines, formal review gates, or compatibility testing

In those cases, use this skill only as a rough first pass.

Can it generate production-ready specs

Not by itself. It can generate a credible design draft and ensure key sections exist, but you still need domain review, security review, naming cleanup, and implementation-level decisions. The validator checks completeness, not correctness.

Does api-designer install include automated enforcement

Only lightly. The included validator checks required headings, not HTTP semantics, schema correctness, or compatibility guarantees. If you need stronger enforcement, pair it with OpenAPI linters, contract tests, or GraphQL schema tooling.

How to Improve api-designer skill

Give the skill sharper product constraints

The biggest upgrade to api-designer output quality is better constraints. Include:

• who the consumers are
• which actions happen most often
• what must remain stable
• what is intentionally out of scope
• expected list sizes and pagination needs
• whether errors must be client-friendly or integration-friendly

This prevents generic CRUD designs that ignore actual usage patterns.

Ask for decisions, not just documentation

Instead of “write an API spec,” ask the skill to make explicit tradeoffs:

• choose between REST and GraphQL and explain why
• justify PATCH vs PUT
• recommend cursor vs offset pagination
• propose a versioning strategy
• define an error envelope

That turns the api-designer guide into a design assistant instead of a markdown formatter.

Common failure modes to watch for

Typical weak outputs include:

• verb-based endpoints like /createUser
• missing auth assumptions
• status codes without error body structure
• GraphQL schemas with vague fields
• no pagination plan for list endpoints
• no non-goals, leading to scope creep

These are not random mistakes; they usually happen when the initial prompt is under-specified.

Improve the first draft with the repo scripts

A practical refinement loop:

1. Generate a starter doc with generate_api.py
2. Ask the agent to revise it using the api-designer skill
3. Run validate_api.py
4. Add missing sections or custom requirements
5. Re-run the skill for deeper review on naming, consistency, and edge cases

This workflow is more reliable than asking for a perfect design in one pass.

Provide examples of real consumer behavior

A strong way to improve api-designer usage is to include a few real requests:

• “Admin lists failed orders from the last 7 days”
• “Support agent retrieves a customer’s active subscriptions”
• “Partner app creates a refund with a reason code”

These examples help the skill choose better resources, filters, mutation shapes, and response fields.

Add your own required sections to match team standards

The built-in validator is intentionally simple. Extend it by requiring sections your team cares about, such as:

• ## Versioning
• ## Idempotency
• ## Observability
• ## Deprecation Policy
• ## Webhooks

That makes the api-designer skill more useful in real delivery workflows without modifying the core prompt content.

Use api-designer as a review tool, not only a generator

One high-value pattern is to paste an existing API design and ask the skill to review it for:

• resource naming consistency
• method misuse
• missing status codes
• pagination gaps
• GraphQL mutation design problems
• incomplete auth or error sections

This is often a better fit than generation because the repo’s principles are compact and easy to apply as a checklist.