jochenyang/api-designer
skills/api-designer/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add jochenyang/jochen-ai-rules api-designerInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 6, 2026, 9:35 AM101.7s6 files scanned
SKILL.md
- name:
- api-designer
- description:
- 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.
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
| Method | Purpose | Idempotent | |--------|-----------------|------------| | GET | Read resource | ✅ | | POST | Create resource | ❌ | | PUT | Full update | ✅ | | PATCH | Partial update | ❌ | | DELETE | Delete resource | ✅ |
Common Status Codes
200Success /201Created /204No Content400Bad Request /401Unauthorized /403Forbidden /404Not Found500Server Error
Design Principles
- Resource-Oriented: Use plural nouns in URLs, express actions with HTTP methods
- Unified Format: Consistent request/response format, structured error messages
- Version Management: URL or Header version control, backward compatibility
- 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:
Skill Fit- why API design work was neededPrimary Deliverable- interface design, spec, or contract summaryExecution Evidence- references used, files produced, and validation performedRisks / Open Questions- compatibility, auth, or rollout concernsNext Action- the concrete documentation, review, or implementation step
Related Skills
jochenyang/reflect
databases
VerifiedTrustedCommunity
Review current conversation, analyze tasks, errors, and user feedback, extract learning opportunities for skill improvement. Use when user says "reflect", "review session", "what did we learn", "session summary", or after completing a complex task.
20SKILL.mdUpdated Apr 6, 2026
jochenyang/handoff
development
VerifiedTrustedCommunity
Create and resume structured manual session handoffs for long-running development work. Use when approaching context limits, before manual reset, before switching models or IDEs, after a milestone, or when automatic compact would lose important implementation state.
20SKILL.mdUpdated Apr 6, 2026
jochenyang/frontend-design
development
VerifiedTrustedCommunity
Implement distinctive, production-grade frontend UI code with strong visual direction, motion systems, local media asset generation, conversion-aware copy, and polished frontend execution. Use when building landing pages, marketing sites, product pages, dashboards, motion-heavy interfaces, or frontend experiences that need real assets and compelling copy.
20SKILL.mdUpdated Apr 6, 2026
jochenyang/context-codebase
development
VerifiedTrustedCommunity
Project context engine for repo orientation, cached handoff, and task-focused code retrieval.
20SKILL.mdUpdated Apr 6, 2026