onboard
Onboard to a new codebase with structured exploration. Scans the project, generates an architecture map with Mermaid diagrams, identifies entry points, explains the tech stack, lists key patterns and
SKILL.mdskills/onboard/SKILL.md
GitHubOverview
Structured codebase exploration that produces a navigable architecture overview and a "Start Here" guide. Designed for the first hour on a new project.
When to Use
- First session in a repository nobody on the current task has worked in.
- Joining a team, or picking up a take-home, an external repository, or untrusted source that needs the Phase 0 trust scan before anything else runs.
- Refreshing a mental model of a project whose structure moved since it was last read.
- For one file or function, use
/explain; for a quality score, use/assessment; for a single diff, use/review.
Arguments
- No arguments: onboard the current working directory. Phase 0 prompts before running the trust scan.
<path>: onboard the specified path as the project root.--trust: I trust this project. Skip the trust scan and the prompt. Recorded in the final Start Here guide as a deliberate skip.--verify: I do not trust this project. Run the trust scan without prompting. Useful for take-homes, external repos, and untrusted source.- Passing both
--trustand--verifytogether is a conflict. Reject with an error.
Process
Phase 0: Trust decision (asked first)
Before any other action, ask the user whether to trust the project. The trust scan is opt-in per invocation.
Decision flow:
| Invocation | Behavior |
|---|---|
/onboard <path> with no flag |
AskUserQuestion fires. Two options below. Default focus is "No, scan it first" |
/onboard <path> --trust |
Skip the prompt. Skip the scan. Continue to Step 1. The Start Here guide records Safety verdict: SKIPPED (--trust) |
/onboard <path> --verify |
Skip the prompt. Run the scan. Continue per the verdict-to-action table below |
/onboard <path> --trust --verify |
Reject with error: conflicting flags |
Prompt wording:
Do you trust this project? Picking "No, scan it first" runs a read-only scan for install-time hooks, credential-theft patterns, and known supply-chain attack signatures. Takes under 30 seconds on most projects.
Options:
| Option | Effect |
|---|---|
| Yes, trust it (skip scan) | Skip scan. Continue to Step 1. Start Here guide records Safety verdict: SKIPPED (user trusts project) |
| No, scan it first (default focus, Recommended for new or external projects) | Call the Skill tool with audit and the arguments trust --json against the project root. Apply the verdict mapping below |
When the scan runs, map the verdict to action:
| Verdict | /onboard action |
|---|---|
| SAFE | Continue to Step 1 silently. Note the verdict in the final Start Here guide |
| SUSPICIOUS | Present the findings to the user. Ask "Continue with onboarding?" with default no. If yes, proceed to Step 1. If no, abort |
| HIGH-RISK | Block. Present the findings. Require the user to type the literal phrase I accept the risk before continuing |
| MALICIOUS | Block. Present the findings. Refuse to continue. Recommend running the project inside a Docker sandbox or deleting the directory. Do not proceed to Step 1 under any circumstance |
Phase 0 constraints, apply when the scan runs:
- Never install dependencies. Never run any command defined in the project.
- Never read
.env,.env.local, or.env.production. Only.env.example. - Never reveal actual secret values found during the scan. Show file, line, and pattern name only.
- The scan is read-only. The user's trust choice is recorded in the Start Here guide either way.
Step 1: Detect the project
Read the manifest file to determine language, framework, and runtime version. Check in order: package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle, mix.exs, Gemfile. Record:
- Language and version
- Framework and version
- Package manager
- Runtime constraints
Step 2: Map directory structure
Run ls on the project root and each top-level directory. Classify each directory by purpose:
| Directory type | Examples |
|---|---|
| Source code | src/, lib/, app/, pkg/, internal/ |
| Tests | test/, tests/, __tests__/, spec/ |
| Configuration | config/, .github/, .husky/ |
| Build output | dist/, build/, .next/, out/ |
| Documentation | docs/, doc/ |
| Infrastructure | infra/, terraform/, k8s/, docker/ |
| Database | prisma/, migrations/, db/ |
| Scripts | scripts/, bin/, tools/ |
| Static assets | public/, static/, assets/ |
Step 3: Identify entry points
Find the files where execution begins:
mainfield in package.json- Files named
main.ts,index.ts,app.ts,server.ts,main.go,main.rs - Route definitions: search for router setup, controller decorators, API route files
- CLI entry points:
binfield in package.json, files with shebang lines - Worker or job entry points: queue consumers, cron handlers
Step 4: Read configuration
Read these files in parallel when they exist:
- TypeScript config:
tsconfig.json - Linter config:
.eslintrc*,biome.json,.prettierrc* - Docker:
Dockerfile,docker-compose.yml - CI:
.github/workflows/*.yml,.gitlab-ci.yml,Jenkinsfile - Environment:
.env.example - Database:
prisma/schema.prisma, migration files
Step 5: Generate architecture diagram
Produce a Mermaid diagram showing:
- Modules and their responsibilities
- Dependencies between modules
- External services and integrations
- Data flow direction
Use graph TD for layered architectures, graph LR for pipeline architectures. Label edges with the type of interaction: HTTP, event, import, query.
Step 6: Identify patterns
Search the codebase for structural patterns:
| Pattern | How to detect |
|---|---|
| Repository | Files named *.repository.ts, *.repo.go, data access abstractions |
| Service layer | Files named *.service.ts, *.svc.go, business logic classes |
| Controller | Files named *.controller.ts, route handlers |
| Middleware | Files in middleware/ directories, request interceptors |
| Event handlers | Files subscribing to events, queue consumers |
| State machines | Enum-based state transitions, status fields with defined flows |
| DTOs | Files named *.dto.ts, input/output shapes at boundaries |
| Guards/interceptors | Auth guards, validation interceptors, logging interceptors |
Step 7: Read existing documentation
Read in parallel: README.md, CONTRIBUTING.md, ARCHITECTURE.md, docs/ directory contents, CLAUDE.md. Note what is documented and what is missing.
Step 8: Detect conventions
Identify the project's conventions by sampling 5-10 source files:
- Naming: camelCase vs snake_case, file naming patterns
- File structure: one export per file, barrel files, feature-based vs layer-based
- Test patterns: co-located tests vs separate test directory, naming convention
- Import style: relative vs absolute, path aliases
- Error handling: exceptions vs Result types, error classes
Step 9: Output the Start Here guide
Produce a structured guide with these sections:
- What This Project Does: one paragraph summary of the project's purpose
- Tech Stack: language, framework, database, key dependencies
- Architecture: the Mermaid diagram from Step 5 with a brief explanation
- Key Patterns: list each pattern found in Step 6 with an example file
- How to Run: commands to install, configure, and start the project
- How to Test: test commands, test database setup, coverage commands
- Where to Start Reading: the 3-5 most important files to read first, ordered
- Conventions to Follow: the conventions detected in Step 8
Step 10: Suggest next steps
Recommend running /retro discover to capture the detected conventions as durable rules in the project's configuration.
Rules
- Phase 0 prompts the user before any scan runs. The default option in the prompt is "No, scan it first", aligned with the protective intent for unknown projects.
- The user can pre-decide non-interactively with
--trust, skip scan or--verify, run scan. Passing both is a conflict. - When the scan runs and returns HIGH-RISK or MALICIOUS, abort onboarding even if the user pressures to continue. The HIGH-RISK override path requires the explicit phrase. MALICIOUS has no override.
- Never modify any project files during onboarding. This is a read-only exploration.
- Do not install dependencies or run build commands unless the user asks.
- When documentation is incomplete or contradicts the code, trust the code.
- Flag discrepancies between docs and code as findings.
- Keep the Start Here guide under 200 lines. Link to files instead of inlining code.
- The Start Here guide must include a "Safety verdict" line near the top, summarizing the trust decision and the scan result if applicable.
Common Rationalizations
- "The repository comes from a well-known organization, the trust question is noise": Phase 0 asks on every run without a flag, and the default focus is the scan.
- "An install would let me read the generated types": onboarding installs nothing and runs no project command unless the user asks.
- "The README says the service uses X, so it does": when the docs and the code disagree, the code wins, and the mismatch becomes a finding.
- "Inlining the key functions saves the reader a click": the guide links to files and stays under 200 lines.
- "The user insists, so the MALICIOUS verdict can be waived": MALICIOUS has no override, and HIGH-RISK continues only on the literal phrase
I accept the risk.
Red Flags
- Stop and ask the trust question when no flag was passed and no other step has run.
- Stop and reject the invocation when both
--trustand--verifywere passed. - Stop and wait for the literal phrase
I accept the riskwhen the scan returns HIGH-RISK. - Stop onboarding and recommend a Docker sandbox or deleting the directory when the scan returns MALICIOUS.
- Stop and read
.env.exampleinstead when the next read targets.env,.env.local, or.env.production.
Verification
- The Start Here guide carries a
Safety verdictline near the top that matches the Phase 0 outcome. - The guide has all eight sections from Step 9 and stays under 200 lines.
- Every file named under Where to Start Reading exists on disk.
- The Mermaid diagram labels every edge with its interaction type.
git statusshows no project file modified by the onboarding run.- Every mismatch found between the docs and the code is listed as a finding.
Related skills
/audit trust-- Untrusted-project safety scan. Runs automatically as Phase 0. Can also be invoked standalone before adding a new dependency or considering a third-party project./explain-- Deep explanation of a specific file or function./assessment-- Full quality assessment of the codebase./retro discover-- Capture conventions as rules./review-- Review specific code changes.