SKILL.md
workflow-onboard — Codebase Orientation
Degree of freedom: MIXED. Briefing synthesis [HIGH freedom]; which files to read and never printing env values [LOW freedom — run exactly].
Orient to any repo in under 5 minutes. Read first, explain second.
How to reason
- Read — manifests, routes, schema, auth — don't guess
- Map — stack, features, data, how-to-run
- Gap — missing README/schema said out loud
- Brief — scannable; top-3 complexity called out
Worked example
Read:
package.jsonis Next.js 16 + Supabase;src/app/(app)/*has dashboard, billing, settings; latest migration addsorganizations.
Map: B2B dashboard; session via middleware +getUser(); runpnpm dev.
Gap: no README scripts section;.env.examplelistsSTRIPESECRETKEY.
Brief: purpose + stack + route map + 4 tables + auth +pnpm dev+ env names + "start insrc/lib/billing".
Self-critique before reporting
- Files read — briefing cites files, not folklore
- Secrets safe — env names only, never values
- Gaps explicit — missing schema/README is stated, not invented
- Right owner — preflight commands/services →
workflow-environment-ready; parked work →housekeep-backlog
Step 1: Stack & entry points [LOW freedom — run exactly]
Read (do not shell-grep unless necessary):
| File | What to extract |
|---|---|
package.json / pyproject.toml / Cargo.toml |
Runtime, framework, key deps, scripts |
README.md |
Stated purpose, setup steps, architecture notes |
src/app/layout.tsx / pages/_app.tsx / App.tsx |
Root component, providers, global context |
src/app//page.tsx / src/routes/ / app/routes/** |
Route tree → feature map |
capacitor.config. / app.json / app.config. |
Mobile targets (Expo/RN/Capacitor) |
android/ / ios/ presence |
Native targets |
Step 2: Data & auth layer [LOW freedom — run exactly]
| File | What to extract |
|---|---|
supabase/migrations/*.sql (latest 3) |
Schema, tables, relationships |
prisma/schema.prisma / drizzle/*.ts |
ORM model |
src/lib/supabase. / src/lib/db. |
Client init, auth helper |
.env.example / .env.local (names only, never values) |
Required env vars |
middleware.ts / auth.ts / src/lib/auth.* |
Auth guard pattern |
Step 3: Recent context [LOW freedom — run exactly]
git log --oneline -15 # recent work direction
git diff HEAD~5 --stat # files changed recentlyStep 4: Orientation briefing [HIGH freedom]
Produce a structured briefing covering:
- What it is — one sentence on the product's purpose
- Tech stack — framework + DB + auth + mobile targets
- Feature map — top-level routes grouped by capability
- Data model — key entities and relationships (3-5 tables max)
- Auth pattern — how sessions work and who the roles are
- How to run — exact commands from
package.jsonscripts - Environment — required env vars (names only) and where to find values
- Top 3 to understand first — the areas with the most business logic or complexity
Format as a scannable briefing, not a wall of text. Use short tables where helpful.
Guardrails [LOW freedom — do not skip]
- Never print
.envvalues — names only - If the codebase is a monorepo, scope the briefing to the specific app/package the user is working in (ask if unclear)
- If critical files are missing (no README, no schema), say so explicitly rather than guessing