agentsclimarketplace
Sign in

Api designer

Skill JochenYang/Jochen-ai-rules/skills/api-designer

API architecture design and documentation for RESTful, GraphQL, and gRPC services. Creates OpenAPI specifications, defines versioning strategies, and establishes authentication/authorization patterns. Use when user asks to design API, create endpoints, document REST/GraphQL, or plan API architecture.From its SKILL.md

Install
npx -y skills add JochenYang/Jochen-ai-rules --skill api-designer

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

  • 20 stars20 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

3.2 KB, as published. Nobody here has run it

API Designer

Design high-quality API interfaces and output standardized interface documentation and design specifications.

Core Capabilities

  • RESTful/GraphQL/gRPC architecture design
  • Unified naming conventions and error handling
  • OpenAPI/Swagger documentation generation
  • API versioning and backward compatibility
  • Authentication, authorization, and rate limiting strategies

Quick Reference

HTTP Method Semantics

MethodPurposeIdempotent
GETRead resource✅
POSTCreate resource❌
PUTFull update✅
PATCHPartial update❌
DELETEDelete resource✅

Common Status Codes

  • 200 Success / 201 Created / 204 No Content
  • 400 Bad Request / 401 Unauthorized / 403 Forbidden / 404 Not Found
  • 500 Server Error

Design Principles

  1. Resource-Oriented: Use plural nouns in URLs, express actions with HTTP methods
  2. Unified Format: Consistent request/response format, structured error messages
  3. Version Management: URL or Header version control, backward compatibility
  4. Security First: Authentication, authorization, input validation, rate limiting

Boundaries

Focus on API design and documentation standards, not specific business logic implementation.

When NOT to Use

  • Writing implementation code → use developer
  • Database schema design → use database-engineer
  • Frontend UI development → use frontend-design
  • Infrastructure or DevOps setup → use devops-engineer

When To Use

Use this skill when the user asks to:

  • design a new API or endpoint structure
  • document existing APIs with OpenAPI/Swagger
  • plan API versioning or migration strategy
  • establish authentication/authorization patterns for APIs

Quick Reference

Always run --help first to see usage.

  • scripts/openapi-gen.sh - Generate OpenAPI documentation

Detailed References

  • ./workflows/api-design.md - API design workflow
  • ./guides/rest-api.md - REST API design guide
  • ./guides/graphql.md - GraphQL API design guide
  • ./guides/grpc.md - gRPC API design guide

Escalation Rules

Pause and ask the owner before:

  • locking in an API style, auth model, or versioning strategy that has broad product impact
  • expanding from interface design into implementation details outside this skill's boundary
  • making compatibility assumptions that could break existing clients

Final Output Contract (MANDATORY)

Every use of this skill should end with:

  1. Skill Fit - why API design work was needed
  2. Primary Deliverable - interface design, spec, or contract summary
  3. Execution Evidence - references used, files produced, and validation performed
  4. Risks / Open Questions - compatibility, auth, or rollout concerns
  5. Next Action - the concrete documentation, review, or implementation step

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.