project-onboarding

Project onboarding

Run this skill when you start work on a repository you haven't seen before. The goal is a one-screen orientation, not a full audit.

Steps

1. Read the obvious docs in parallel. Issue these reads concurrently:

   • README.md (or README.*)
   • CLAUDE.md — project conventions Claude must follow
   • AGENTS.md if present
   • The package manifest for whatever language the repo uses:
     • JS/TS → package.json
     • Python → pyproject.toml, fall back to requirements.txt
     • Rust → Cargo.toml
     • Go → go.mod
     • Ruby → Gemfile
     • Java/Kotlin → build.gradle* or pom.xml

2. Map the top level. List the repo root and note which directories exist (src/, app/, tests/, docs/, scripts/, etc.).

3. Identify entry points from the manifest:

   • npm/yarn/pnpm/bun scripts
   • bin entries
   • Python [project.scripts]
   • Go cmd/ main packages

4. Skim one source file. Pick the most likely entry point and read just enough to confirm the framework (Next.js vs plain React, FastAPI vs Django, etc.).

Output

Produce exactly six lines. No headers, no preamble:

• Language / runtime — e.g., TypeScript on Bun, Python 3.12 on uv
• Framework — e.g., Next.js 15 App Router, FastAPI + SQLAlchemy
• Entry points — the one to three commands a developer actually runs
• Layout — four-to-six word description of the directory shape
• Key convention — the single most important thing CLAUDE.md / AGENTS.md says
• Unclear — one thing you would ask the user to clarify before changing code

Stop there. Don't propose work, don't audit quality, don't enumerate dependencies. The user will direct from here.

When NOT to use this skill

• You've already worked in this repo earlier in the session.
• The user gave you a specific file path and a specific task — just do the task.
• The repo is a single file.