home / skills / mattpocock / course-video-manager / document-ai-hero-api

document-ai-hero-api skill

safe

This skill generates or updates API documentation for the AI Hero API by analyzing source code and producing structured docs.

npx playbooks add skill mattpocock/course-video-manager --skill document-ai-hero-api

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.1 KB

---
name: document-ai-hero-api
description: "Generate or update documentation for the AI Hero API by reading the source code at ~/repos/ai/course-builder. Use when user wants to document, update docs for, or understand the AI Hero API endpoints."
---

# Document AI Hero API

Generate/update API documentation by reading the AI Hero source code.

## Prerequisites: Ensure Read Permissions

Before reading the AI Hero source, update `.claude/settings.local.json` to include read permission for the course-builder repo. Add this entry to the `permissions.allow` array if not already present:

```
"Read(/home/mattpocock/repos/ai/course-builder/**)"
```

## Workflow

### 1. Scan API Source

Read the AI Hero API source at `~/repos/ai/course-builder/apps/ai-hero/src/`. Focus on:

- **REST endpoints**: `src/app/api/` — each folder is a route segment. Read every `route.ts` file.
- **tRPC routers**: `src/trpc/api/routers/` — each file is a typed RPC router.
- **Database schema**: `src/db/schema.ts` — table definitions and relationships.
- **Auth**: `src/app/api/auth/` and any middleware files for auth patterns.

### 2. For Each Endpoint, Capture

- HTTP method + path (REST) or procedure name + type (tRPC query/mutation)
- Request body / query params with TypeScript types
- Response shape with TypeScript types
- Auth requirements (public, Bearer token, session, HMAC)
- Side effects (Inngest events, webhooks, S3 uploads)

### 3. Cross-Reference with This Project

Check how endpoints are consumed in this codebase:

- `app/services/ai-hero-auth-service.ts` — OAuth device flow
- `app/services/ai-hero-upload-service.ts` — Upload & post creation
- `app/features/upload-manager/` — SSE client for progress

Flag any endpoints used here that have changed in the source.

### 4. Write Documentation

Output to `docs/ai-hero-api.md` in this repo. Follow the structure in [TEMPLATE.md](TEMPLATE.md).

### 5. Summary

After updating, print a short summary of:

- Number of endpoints documented
- Any breaking changes detected vs. current usage
- Any new endpoints not yet consumed by this project

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.

FAQ

What files does this skill read to build docs?

It reads REST route files under src/app/api, tRPC routers under src/trpc/api/routers, the DB schema file, and auth/middleware files under src/app/api/auth and related middleware.

How are breaking changes detected?

By cross-referencing endpoint signatures and auth requirements with local consumers such as auth and upload services; type mismatches or missing routes are flagged as potential breaking changes.

Where is the generated documentation written?

Documentation is written to docs/ai-hero-api.md and includes a short summary listing endpoint count, detected breaking changes, and new unconsumed endpoints.