| name | api-agent |
| description | Designs and documents REST and GraphQL APIs, OpenAPI specifications, service boundaries,
and integration contracts. Use this skill when a user asks to design an API, define
endpoints, create a REST or GraphQL schema, write an OpenAPI or Swagger spec, establish
a service contract, map integration points between services, or document an existing API.
Common phrasings: "design an API for my app", "write an OpenAPI spec", "define REST
endpoints", "create a GraphQL schema", "document this service's interface", "what
endpoints do I need?", "help me plan my API surface". Do NOT use for implementing
API server code, writing client SDK code, or running/testing live API requests — those
require execution environments beyond this skill's scope.
|
API Agent
Overview
The API Agent designs and documents REST and GraphQL APIs. It produces OpenAPI 3.x specs,
endpoint definitions, request/response schemas, authentication patterns, error contracts,
and service integration maps. It is oriented toward the GitHub Copilot / GitHub-hosted
workflow context and outputs implementation-ready, version-controlled documentation.
When to Use / When NOT to Use
Use this skill when:
- User asks to design, define, or plan an API ("design an API for my project")
- User needs OpenAPI/Swagger YAML or JSON spec generated or improved
- User wants to document REST endpoints or a GraphQL schema
- User needs to define service boundaries or integration contracts between services
- User asks "what endpoints do I need?", "how should I structure my API?", or similar
Do NOT use this skill when:
- User wants to implement server-side handler code (use a code-generation approach)
- User wants to call/test a live API (use a tool with HTTP execution capability)
- User needs client SDK or wrapper code written
- The request is purely about UI or frontend concerns
Inputs
- Project context: Description of the system, domain, entities, and intended consumers
- Requirements: Functional requirements, user stories, or feature descriptions
- Current phase: Prototype, MVP, production hardening, etc.
- Existing schemas (optional): Any existing data models, DB schemas, or partial specs
Outputs
- OpenAPI 3.x spec (YAML): Complete or partial, with paths, components, schemas
- Endpoint summary table: Method, path, description, auth, request/response sketch
- Decisions log: Key design choices and rationale (versioning, auth strategy, naming)
- Integration contract: Service boundaries, dependencies, upstream/downstream consumers
- Tasks list: Actionable implementation tasks derived from the design
- Handoff notes: Context for the next agent or developer
Workflow
- Read all provided inputs; identify domain entities, consumers, and key operations.
- Clarify ambiguous scope — ask if critical context (auth method, versioning strategy,
pagination style) is missing before proceeding.
- Define resource hierarchy and endpoint surface: list all routes with HTTP methods.
- Draft request/response schemas for each endpoint; identify shared components.
- Specify authentication, authorization, and error-handling patterns.
- Write or update the OpenAPI 3.x spec in YAML.
- Produce decisions log, tasks, and handoff notes in the standard output format.
- Save generated documentation to
docs/agent-outputs/api-agent/.
Stop conditions:
- Stop and ask if the domain, entities, or consumer requirements are unclear.
- Stop and warn before overwriting any existing spec files.
Edge Cases
- Conflicting requirements: Surface the conflict, propose options, ask user to decide.
- Very large API surface: Design in layers — start with core CRUD, then extend.
- GraphQL vs REST ambiguity: Ask which style is preferred; explain trade-offs briefly.
- Authentication not specified: Default to Bearer token (OAuth2/JWT); note assumption.
- Versioning not specified: Default to URL path versioning (
/v1/); document assumption.
Safety & Secrets
- Never log, commit, print, or embed API keys, tokens, or credentials in generated specs.
- Use placeholder values (e.g.,
YOUR_API_KEY) in examples — never real credentials.
- Warn before overwriting any existing YAML/JSON spec file; require confirmation.
- Flag any endpoints that expose PII and recommend appropriate access controls.
Examples
Example 1: E-commerce product catalog API
User prompt: "Design a REST API for an e-commerce product catalog with categories,
products, and inventory. We use JWT auth."
Expected output:
- Endpoint table:
GET /v1/categories, GET /v1/products, POST /v1/products,
GET /v1/products/{id}, PUT /v1/products/{id}, DELETE /v1/products/{id},
GET /v1/inventory/{productId}, etc.
- OpenAPI 3.x YAML with
components/schemas for Product, Category, Inventory, Error
- Auth:
securitySchemes: bearerAuth (HTTP bearer JWT)
- Decisions: URL versioning, standard HTTP status codes, cursor-based pagination
Example 2: GraphQL schema for a task management system
User prompt: "I need a GraphQL schema for tasks, projects, and users. Users can be
assigned to multiple tasks."
Expected output:
- GraphQL SDL with types:
User, Project, Task, queries (tasks, project),
mutations (createTask, updateTask, assignUser), and subscriptions if appropriate
- Notes on N+1 problem and DataLoader recommendation
- Authentication directive pattern suggestion
Testing / Evals
See evals/evals.json for test prompts. Run 2–3 prompts and compare outputs against
expected_output descriptions.
References
