job-api-design

Generate job API designs with schemas, endpoints, and SQS queueing.

Updated Mar 14, 2026
One-click install
npx skills add https://github.com/KazusaNakagawa/claude_docs --skill job-api-design
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: job-api-design
Source: https://github.com/KazusaNakagawa/claude_docs/tree/main/skills/job-api-design
Command: npx skills add https://github.com/KazusaNakagawa/claude_docs --skill job-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Complex job-processing designs are hard to translate into implementable APIs. This skill automates the creation of a complete, production-ready API design from detailed design documents, reducing interpretation errors and wiring gaps.

Core Features & Use Cases

  • Generate a unified job message format and a jobs table schema from design artifacts.
  • Define a lifecycle (PENDING, QUEUED, RUNNING, COMPLETED, FAILED, DEAD) with clear transitions and retry/DLQ guidance.
  • Produce endpoint specifications for create, get, list, cancel, retry, and logs, plus queue and worker integration details.

Quick Start

Feed the skill 04.detail-design.md (or 02.design-doc.md) to generate the full API design.

Frequently Asked Questions about job-api-design

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

FAQPage Schema
How do I design an asynchronous job API from a design document?

A robust job API design requires a unified job message format, a jobs table schema, lifecycle states like PENDING and RUNNING, plus queue and worker integration details. This skill generates these specifications directly from your design documents to reduce interpretation errors.

What should be included in a job status transition model for queueing workflows?

A job status transition model for queueing workflows should include PENDING, QUEUED, RUNNING, COMPLETED, FAILED, and DEAD states. The generated design enforces this lifecycle with clear transitions, retry guidance, and dead letter queue handling for asynchronous job processing.

How do I define endpoints for creating, canceling, and retrying background jobs?

Defining endpoints for creating, canceling, and retrying background jobs requires specifications for create, get, list, cancel, retry, and logs operations. The skill produces these endpoint specifications alongside SQS queue design and worker orchestration guidance from your input design artifacts.

Can I use SQS queue design and SQL-based jobs store for my job processing architecture?

Yes, SQS queue design and a SQL-based jobs store are supported for job processing architecture. The skill outputs a SQL-based jobs store schema, SQS queue configuration, worker orchestration guidance, and observability requirements to ensure robust asynchronous job workflows.

What is the best way to add observability and monitoring to an asynchronous job workflow?

Adding observability and monitoring to an asynchronous job workflow requires defining specific metrics and logging requirements across job states. The generated API design includes built-in observability requirements covering the full lifecycle from PENDING to DEAD for production readiness.