skills.rest
gleeb
gleebCOMMUNITY
Explore all skills by this author →
GitHub

planning-api-design

Draft per-story API specifications with schemas, authentication, and error cases.

Updated Aug 27, 2026
Search Tags:#authentication#error handling#api design#user stories#system architecture#spec authoring#contract alignment
One-click install
npx skills add https://github.com/gleeb/ai-registry --skill planning-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: planning-api-design
Source: https://github.com/gleeb/ai-registry/tree/main/systems/sdlc/skills/planning-api-design
Command: npx skills add https://github.com/gleeb/ai-registry --skill planning-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents contract drift and rework by producing a story-scoped API specification that matches the Planning Hub’s architecture and consumed contracts.

Core Features & Use Cases

  • Story-scoped API surface analysis: Extracts endpoints needed for a single user story from its acceptance criteria and (optionally) its hld.md component mapping.
  • Contract-aligned contract design: Drafts request/response schemas, auth requirements, and error cases using consumed contracts as the source of truth.
  • Review-ready specification output: Produces plan/user-stories/US-NNN-name/api.md and returns a completion summary after sparring with the user.

Quick Start

Use the planning-api-design skill to create the API spec for a single user story by updating its plan/user-stories/US-NNN-name/api.md based on story.md, plan/system-architecture.md, consumed contracts, and (if available) hld.md.

Frequently Asked Questions about planning-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design per-story API specifications before implementation?▼

Per-story API specifications are designed by extracting endpoints from acceptance criteria and drafting request/response schemas, authentication, and error cases. This process aligns system architecture and consumed contracts into a review-ready specification file.

How do I prevent contract drift when drafting API endpoints for user stories?▼

Contract drift is prevented by using consumed contracts as the source of truth during endpoint enumeration and schema drafting. Aligning request/response schemas and error cases with existing system architecture ensures implementation matches planning.

What files do I need to generate a story-scoped API spec?▼

Generating a story-scoped API spec requires reading story.md, system-architecture.md, and consumed contracts. If available, hld.md provides additional component mapping to extract the required endpoints for the user story.

How do I enumerate API endpoints from acceptance criteria?▼

API endpoints are enumerated by extracting required operations from user story acceptance criteria and optional hld.md component mappings. This analysis defines the exact API surface needed before drafting schemas and authentication requirements.

Does this approach handle authentication and error cases for API design?▼

Authentication and error cases are handled during the specification drafting process. The generated API spec explicitly defines auth requirements and error responses alongside request and response schemas for each endpoint.

Related Skills

Explore More Product & Management Skills→
TestAny-ioTestAny-io
79

hld-writer

Converts PRD and API contracts into structured high-level designs with traceability.

Official
Advanced
ramybarsoumramybarsoum

api-design

Design RESTful API contracts with endpoint specs, JSON Schema, and error codes.

Community
Intermediate
co-cddoco-cddo
4

bmad-agent-architect

Guide system architecture decisions with alignment checks across PRD, UX, and Epics.

Official
Advanced
slgoodrichslgoodrich
121

user-story-templates

Generate user story templates with acceptance criteria and INVEST validation.

Community
Basic