Technical Specification
Generate structured API technical specifications with TypeScript data models and documented auth endpoints before you implement.
Overview
Technical Specification is an agent skill most often used in Validate (also Build backend, Ship review) that produces API data models and auth endpoint documentation for solo builders scoping a backend.
Install
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill technical-specificationWhat is this skill?
- TypeScript interface templates for core entities (User, tokens, timestamps)
- Documented REST auth flows: register, login with optional 2FA, JWT refresh
- Request/response JSON examples with HTTP status codes (201, 200, 400, 409, 422)
- Explicit error catalog per endpoint for agent-ready OpenAPI-style specs
Adoption & trust: 590 installs on skills.sh; 250 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You know you need login and user APIs but only have vague chat messages instead of typed models, examples, and error codes your agent can implement.
Who is it for?
Indie SaaS founders or solo full-stack builders defining JWT auth and user APIs before the first backend PR.
Skip if: Teams that already maintain generated OpenAPI from code, or greenfield GraphQL-only APIs with no REST auth surface.
When should I use this skill?
You need API data models and authentication endpoint documentation as a starting spec for a new or revised backend.
What do I get? / Deliverables
You get a structured technical spec with TypeScript interfaces and endpoint sections you can paste into docs or extend into a full API design before coding.
- TypeScript interface blocks for domain entities
- Auth endpoint sections with JSON examples and error lists
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate because solo builders lock API contracts and scope before committing to backend implementation. Scope subphase is where endpoint shapes, request/response types, and error codes belong in a spec artifact agents and humans can implement against.
Where it fits
Define register/login payloads and weak-password rules before estimating backend work.
Hand your agent the User and LoginRequest interfaces so route handlers match the agreed contract.
Compare implemented responses against the documented 201/409/422 cases in the spec.
How it compares
Use instead of free-form “design my API” chat when you want repeatable endpoint and model sections agents can follow.
Common Questions / FAQ
Who is technical-specification for?
Solo and indie builders shipping APIs or SaaS backends with Claude Code, Cursor, or Codex who want a spec artifact before implementation.
When should I use technical-specification?
During Validate scope when locking API contracts; during Build backend when aligning agents on auth payloads; during Ship review when checking docs match intended errors and statuses.
Is technical-specification safe to install?
It is prompt and template content only—review the Security Audits panel on this Prism page and the source repo before trusting third-party skill packs.
SKILL.md
READMESKILL.md - Technical Specification
# API Data Models ## API Data Models ```typescript interface User { id: string; email: string; emailVerified: boolean; twoFactorEnabled: boolean; createdAt: string; updatedAt: string; lastLoginAt?: string; } interface LoginRequest { email: string; password: string; twoFactorCode?: string; } interface LoginResponse { success: boolean; token: string; refreshToken: string; user: User; expiresIn: number; } interface RegisterRequest { email: string; password: string; confirmPassword: string; } ``` --- # Authentication Endpoints ## Authentication Endpoints ### POST /api/auth/register **Description:** Register a new user account **Request:** ```json { "email": "user@example.com", "password": "SecurePass123!", "confirmPassword": "SecurePass123!" } ``` **Response (201):** ```json { "success": true, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "user@example.com", "emailVerified": false }, "message": "Verification email sent" } ``` **Errors:** - 400: Invalid email format - 409: Email already exists - 422: Password too weak ### POST /api/auth/login **Description:** Authenticate user and return JWT token **Request:** ```json { "email": "user@example.com", "password": "SecurePass123!", "twoFactorCode": "123456" } ``` **Response (200):** ```json { "success": true, "token": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "user@example.com" }, "expiresIn": 3600 } ``` **Errors:** - 401: Invalid credentials - 403: Account locked - 428: 2FA code required # Database Schema ## Database Schema ```sql -- Users table CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255), email_verified BOOLEAN DEFAULT FALSE, two_factor_enabled BOOLEAN DEFAULT FALSE, two_factor_secret VARCHAR(32), created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW(), last_login_at TIMESTAMP ); -- OAuth connections CREATE TABLE oauth_connections ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, provider VARCHAR(50) NOT NULL, -- 'google', 'github' provider_user_id VARCHAR(255) NOT NULL, access_token TEXT, refresh_token TEXT, created_at TIMESTAMP DEFAULT NOW(), UNIQUE(provider, provider_user_id) ); -- Sessions CREATE TABLE sessions ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES users(id) ON DELETE CASCADE, token VARCHAR(255) UNIQUE NOT NULL, expires_at TIMESTAMP NOT NULL, created_at TIMESTAMP DEFAULT NOW(), ip_address INET, user_agent TEXT ); -- Indexes CREATE INDEX idx_users_email ON users(email); CREATE INDEX idx_sessions_token ON sessions(token); CREATE INDEX idx_sessions_user_id ON sessions(user_id); CREATE INDEX idx_oauth_user_id ON oauth_connections(user_id); ```` # Functional Requirements ## Functional Requirements ### FR-1: User Authentication **Priority:** P0 (Must Have) **Description:** Users must be able to authenticate using email/password **Acceptance Criteria:** - [ ] User can register with email and password - [ ] User can log in with credentials - [ ] User receives email verification - [ ] User can reset forgotten password - [ ] Session expires after 7 days of inactivity **Dependencies:** None ### FR-2: Social Login **Priority:** P1 (Should Have) **Description:** Users can authenticate using OAuth providers **Acceptance Criteria:** - [ ] Support Google OAuth - [ ] Support GitHub OAuth - [ ] Link social accounts to existing accounts - [ ] Unlink social accounts **Dependencies:** FR-1 ### FR-3: Two-Factor Authentication **Priority:** P2 (Nice to Have) **Description:** Optional 2FA for enhanced security **Acceptance Criteria:** - [ ] Enable/disable 2FA in settings - [ ] Support TOTP (Google Authenticator, Authy) - [ ] B