document-ai-hero-api_skill

Overview

This skill generates or updates API documentation for the AI Hero API by reading the TypeScript source at ~/repos/ai/course-builder. It produces a structured docs/ai-hero-api.md file and a short summary of findings including endpoint counts and detected changes. Use it when you need accurate, code-driven API docs or to verify endpoint compatibility with the codebase.

How this skill works

The skill scans key source folders: REST route files under src/app/api, tRPC routers under src/trpc/api/routers, the database schema, and auth/middleware code. For each endpoint or procedure it extracts method/path or procedure name, TypeScript request and response shapes, auth requirements, and notable side effects (events, uploads, webhooks). It cross-references usage in local services and feature code to detect breaking changes or new endpoints, then writes the documentation to docs/ai-hero-api.md and prints a short summary.

When to use it

• When creating initial API docs for AI Hero from source code.
• When updating docs after code changes to endpoints, types, or auth.
• When auditing endpoints for breaking changes or mismatches with consumers.
• When onboarding developers who need typed endpoint references.
• When verifying uploads, events, or auth flows used by local services.

Best practices

• Ensure read permissions include the course-builder path before scanning.
• Scan both REST route.ts files and tRPC router files to capture all endpoints.
• Include TypeScript types for request bodies, query params, and responses for accuracy.
• Cross-reference service and feature folders to find real consumers and detect mismatches.
• Document auth requirements and side effects (Inngest events, S3 uploads, webhooks) explicitly.

Example use cases

• Generate up-to-date API docs after a refactor that changed route handlers or tRPC procedures.
• Detect a breaking change where a consumer expects a different request shape or auth scheme.
• Create a developer-focused reference that lists all endpoints, request/response types, and required scopes.
• Identify new API endpoints added to the codebase that are not yet consumed by local services.
• Verify the OAuth device flow and upload endpoints used by the upload manager and auth service.